From b1d0fe8e42ec5846e812c118d7c095954c990fd6 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Mon, 18 Sep 2017 11:34:33 -0700 Subject: [PATCH 01/27] fixed broken link (#3169) --- docs/standard/collections/index.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/docs/standard/collections/index.md b/docs/standard/collections/index.md index 7941536375151..d864861425ea7 100644 --- a/docs/standard/collections/index.md +++ b/docs/standard/collections/index.md @@ -1,12 +1,8 @@ --- title: "Collections and Data Structures" -ms.custom: "" ms.date: "03/30/2017" ms.prod: ".net" -ms.reviewer: "" -ms.suite: "" ms.technology: dotnet-standard -ms.tgt_pltfrm: "" ms.topic: "article" helpviewer_keywords: - "grouping data in collections" @@ -91,15 +87,9 @@ Similar data can often be handled more efficiently when stored and manipulated a ## Reference - - - - - - - System.Collections.Immutable + From fc8ef624767298101eae9250211e1e0a4cf89597 Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 19 Sep 2017 12:23:04 -0700 Subject: [PATCH 02/27] fixed pipes in tables (#3163) --- .../concepts/linq/linq-to-xml-for-xpath-users.md | 7 +------ .../framework/tools/ngen-exe-native-image-generator.md | 2 +- ...ervice-model-configuration-tool-comsvcconfig-exe.md | 10 +++++----- .../concepts/linq/linq-to-xml-for-xpath-users.md | 8 ++------ 4 files changed, 9 insertions(+), 18 deletions(-) diff --git a/docs/csharp/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md b/docs/csharp/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md index 81c768729b188..4d4513d4e6381 100644 --- a/docs/csharp/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md +++ b/docs/csharp/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md @@ -1,13 +1,9 @@ --- title: "LINQ to XML for XPath Users (C#)" -ms.custom: "" ms.date: "2015-07-20" ms.prod: .net -ms.reviewer: "" -ms.suite: "" ms.technology: - "devlang-csharp" - ms.topic: "article" dev_langs: - "CSharp" @@ -15,7 +11,6 @@ ms.assetid: 91774511-1dca-4f06-ac0b-913746f104fe caps.latest.revision: 3 author: "BillWagner" ms.author: "wiwagn" - --- # LINQ to XML for XPath Users (C#) This set of topics show a number of XPath expressions and their [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] equivalents. @@ -36,7 +31,7 @@ This set of topics show a number of XPath expressions and their [!INCLUDE[sqltec |[How to: Find Elements in a Namespace (XPath-LINQ to XML) (C#)](../../../../csharp/programming-guide/concepts/linq/how-to-find-elements-in-a-namespace-xpath-linq-to-xml.md)|Compares the use of the XPath class with the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] property of the class for working with XML namespaces.

The associated XPath expression is:`"./aw:*"`| |[How to: Find Preceding Siblings (XPath-LINQ to XML) (C#)](../../../../csharp/programming-guide/concepts/linq/how-to-find-preceding-siblings-xpath-linq-to-xml.md)|Compares the XPath `preceding-sibling` axis to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] child axis.

The associated XPath expression is:`"preceding-sibling::*"`| |[How to: Find Descendants of a Child Element (XPath-LINQ to XML) (C#)](../../../../csharp/programming-guide/concepts/linq/how-to-find-descendants-of-a-child-element-xpath-linq-to-xml.md)|Compares how to get the descendant elements of a child element with a particular name with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"./Paragraph//Text/text()"`| -|[How to: Find a Union of Two Location Paths (XPath-LINQ to XML) (C#)](../../../../csharp/programming-guide/concepts/linq/how-to-find-a-union-of-two-location-paths-xpath-linq-to-xml.md)|Compares the use of the union operator, `|`, in XPath with the standard query operator in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"//Category|//Price"`| +|[How to: Find a Union of Two Location Paths (XPath-LINQ to XML) (C#)](../../../../csharp/programming-guide/concepts/linq/how-to-find-a-union-of-two-location-paths-xpath-linq-to-xml.md)|Compares the use of the union operator, |, in XPath with the standard query operator in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:"//Category|//Price"| |[How to: Find Sibling Nodes (XPath-LINQ to XML) (C#)](../../../../csharp/programming-guide/concepts/linq/how-to-find-sibling-nodes-xpath-linq-to-xml.md)|Compares how to find all siblings of a node that have a specific name with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"../Book"`| |[How to: Find an Attribute of the Parent (XPath-LINQ to XML) (C#)](../../../../csharp/programming-guide/concepts/linq/how-to-find-an-attribute-of-the-parent-xpath-linq-to-xml.md)|Compares how to navigate to the parent element and find an associated attribute using XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"../@id"`| |[How to: Find Attributes of Siblings with a Specific Name (XPath-LINQ to XML) (C#)](../../../../csharp/programming-guide/concepts/linq/how-to-find-attributes-of-siblings-with-a-specific-name-xpath-linq-to-xml.md)|Compares how to find specific attributes of the siblings of the context node with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"``../Book/@id``"`| diff --git a/docs/framework/tools/ngen-exe-native-image-generator.md b/docs/framework/tools/ngen-exe-native-image-generator.md index d771ceaf2576d..ac4c3d271aa03 100644 --- a/docs/framework/tools/ngen-exe-native-image-generator.md +++ b/docs/framework/tools/ngen-exe-native-image-generator.md @@ -83,7 +83,7 @@ ngen /? | /help |`uninstall` [`assemblyName` | `assemblyPath`] [`scenarios`] [`config`]|Delete the native images of an assembly and its dependencies from the native image cache.

To uninstall a single image and its dependencies, use the same command-line arguments that were used to install the image. **Note:** Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], the action `uninstall` * is no longer supported.| |`update` [`/queue`]|Update native images that have become invalid.

If `/queue` is specified, the updates are queued for the native image service. Updates are always scheduled at priority 3, so they run when the computer is idle.| |`display` [`assemblyName` | `assemblyPath`]|Display the state of the native images for an assembly and its dependencies.

If no argument is supplied, everything in the native image cache is displayed.| -|`executeQueuedItems` [`1``|``2``|``3`]

-or-

`eqi` [1|2|3]|Execute queued compilation jobs.

If a priority is specified, compilation jobs with greater or equal priority are executed. If no priority is specified, all queued compilation jobs are executed.| +|`executeQueuedItems` [1|2|3]

-or-

`eqi` [1|2|3]|Execute queued compilation jobs.

If a priority is specified, compilation jobs with greater or equal priority are executed. If no priority is specified, all queued compilation jobs are executed.| |`queue` {`pause` | `continue` | `status`}|Pause the native image service, allow the paused service to continue, or query the status of the service.| diff --git a/docs/framework/wcf/com-service-model-configuration-tool-comsvcconfig-exe.md b/docs/framework/wcf/com-service-model-configuration-tool-comsvcconfig-exe.md index df8269a2fb78d..eba93b4090590 100644 --- a/docs/framework/wcf/com-service-model-configuration-tool-comsvcconfig-exe.md +++ b/docs/framework/wcf/com-service-model-configuration-tool-comsvcconfig-exe.md @@ -53,11 +53,11 @@ ComSvcConfig.exe /install | /uninstall | /list [/application:`|Specifies the COM+ application to configure.

Short form `/a`.| -|`/contract:<` *ClassID* `|` *ProgID* `| *,` *InterfaceID* `|` *InterfaceName* `| *` `>`|Specifies the COM+ component and interface that will be configured as the contract for the service.

Short form `/c`.

While the wildcard character (*) can be used when you specify the component and interface names, we recommend that you do not use it, because you might expose interfaces that you did not intend to.| -|`/hosting:<` *complus* `|` *was* `>`|Specifies whether to use the COM+ hosting mode or the Web hosting mode.

Short form `/h`.

Using the COM+ hosting mode requires explicit activation of the COM+ application. Using the Web hosting mode allows the COM+ application to be automatically activated as required. If the COM+ application is a library application, it runs in the Internet Information Services (IIS) process. If the COM+ application is a server application, it runs in the Dllhost.exe process.| -|`/webSite:<` *WebsiteName* `>`|Specifies the Web site for hosting when Web hosting mode is used (see the `/hosting` flag).

Short form `/w`.

If no Web site is specified, the default Web site is used.| -|`/webDirectory:<` *WebDirectoryName* `>`|Specifies the virtual directory for hosting when Web hosting is used (see the `/hosting` flag).

Short form `/d`.| +|`/application:` \<*ApplicationID* | *ApplicationName*\>|Specifies the COM+ application to configure.

Short form `/a`.| +|`/contract:` \<*ClassID* | *ProgID* | \*,*InterfaceID* | *InterfaceName* | \*\>|Specifies the COM+ component and interface that will be configured as the contract for the service.

Short form `/c`.

While the wildcard character (\*) can be used when you specify the component and interface names, we recommend that you do not use it, because you might expose interfaces that you did not intend to.| +|`/hosting:` \<*complus* | *was*\>|Specifies whether to use the COM+ hosting mode or the Web hosting mode.

Short form `/h`.

Using the COM+ hosting mode requires explicit activation of the COM+ application. Using the Web hosting mode allows the COM+ application to be automatically activated as required. If the COM+ application is a library application, it runs in the Internet Information Services (IIS) process. If the COM+ application is a server application, it runs in the Dllhost.exe process.| +|`/webSite:` \<*WebsiteName*\>|Specifies the Web site for hosting when Web hosting mode is used (see the `/hosting` flag).

Short form `/w`.

If no Web site is specified, the default Web site is used.| +|`/webDirectory:` \<*WebDirectoryName*\>|Specifies the virtual directory for hosting when Web hosting is used (see the `/hosting` flag).

Short form `/d`.| |`/mex`|Adds a Metadata Exchange (MEX) service endpoint to the default service configuration to support clients that want to retrieve a contract definition from the service.

Short form `/x`.| |`/id`|Displays the application, component, and interface information as IDs.

Short form `/k`.| |`/nologo`|Prevents ComSvcConfig.exe from displaying its logo.

Short form `/n`.| diff --git a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md index 2f9beb2a2df9d..072041fae4328 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md +++ b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md @@ -1,13 +1,9 @@ --- title: "LINQ to XML for XPath Users (Visual Basic)" -ms.custom: "" ms.date: "2015-07-20" ms.prod: .net -ms.reviewer: "" -ms.suite: "" ms.technology: - "devlang-visual-basic" -ms.tgt_pltfrm: "" ms.topic: "article" dev_langs: - "VB" @@ -15,9 +11,9 @@ ms.assetid: 0e64911c-a7cc-4c20-b927-ca99078b5656 caps.latest.revision: 3 author: dotnet-bot ms.author: dotnetcontent - --- # LINQ to XML for XPath Users (Visual Basic) + This set of topics show a number of XPath expressions and their [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] equivalents. All of the examples use the XPath functionality in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] that is made available by the extension methods in . The examples execute both the XPath expression and the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] expression. Each example then compares the results of both queries, validating that the XPath expression is functionally equivalent to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] query. As both types of queries return nodes from the same XML tree, the query result comparison is made using referential identity. @@ -36,7 +32,7 @@ This set of topics show a number of XPath expressions and their [!INCLUDE[sqltec |[How to: Find Elements in a Namespace (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-elements-in-a-namespace.md)|Compares the use of the XPath class with the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] property of the class for working with XML namespaces.

The associated XPath expression is:`"./aw:*"`| |[How to: Find Preceding Siblings (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-preceding-siblings-xpath-linq-to-xml.md)|Compares the XPath `preceding-sibling` axis to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] child axis.

The associated XPath expression is:`"preceding-sibling::*"`| |[How to: Find Descendants of a Child Element (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-descendants-of-a-child-element-xpath-linq-to-xml.md)|Compares how to get the descendant elements of a child element with a particular name with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"./Paragraph//Text/text()"`| -|[How to: Find a Union of Two Location Paths (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-a-union-of-two-location-paths-xpath.md)|Compares the use of the union operator, `|`, in XPath with the standard query operator in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"//Category|//Price"`| +|[How to: Find a Union of Two Location Paths (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-a-union-of-two-location-paths-xpath.md)|Compares the use of the union operator, |, in XPath with the standard query operator in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:"//Category|//Price"| |[How to: Find Sibling Nodes (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-sibling-nodes-xpath-linq-to-xml.md)|Compares how to find all siblings of a node that have a specific name with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"../Book"`| |[How to: Find an Attribute of the Parent (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-an-attribute-of-the-parent-xpath-linq-to-xml.md)|Compares how to navigate to the parent element and find an associated attribute using XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"../@id"`| |[How to: Find Attributes of Siblings with a Specific Name (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-attributes-of-siblings-with-a-specific-name.md)|Compares how to find specific attributes of the siblings of the context node with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"``../Book/@id``"`| From 2d0dfff3367de5caed2880570e3efa776f30467e Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 19 Sep 2017 12:43:22 -0700 Subject: [PATCH 03/27] added info about relative paths for output (#3042) * added info about relative paths for output * edits --- docs/core/tools/dotnet-publish.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index 689bbcc07e240..e29132bff9c9e 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -1,15 +1,12 @@ --- title: dotnet publish command - .NET Core CLI description: The dotnet publish command publishes your .NET Core project into a directory. -keywords: dotnet-publish, CLI, CLI command, .NET Core -author: blackdwarf +author: mairaw ms.author: mairaw -ms.date: 08/12/2017 +ms.date: 09/01/2017 ms.topic: article ms.prod: .net-core ms.technology: dotnet-cli -ms.devlang: dotnet -ms.assetid: f2ef275a-7c5e-430a-8c30-65f52af62771 --- # dotnet publish @@ -89,6 +86,7 @@ Doesn't perform an implicit restore when running the command. `-o|--output ` Specifies the path for the output directory. If not specified, it defaults to *./bin/[configuration]/[framework]/* for a framework-dependent deployment or *./bin/[configuration]/[framework]/[runtime]* for a self-contained deployment. +If a relative path is provided, the output directory generated is relative to the project file location, not to the current working directory. `--self-contained` @@ -127,6 +125,7 @@ Specifies one or several [target manifests](../deploying/runtime-store.md) to us `-o|--output ` Specifies the path for the output directory. If not specified, it defaults to *./bin/[configuration]/[framework]/* for a framework-dependent deployment or *./bin/[configuration]/[framework]/[runtime]* for a self-contained deployment. +If a relative path is provided, the output directory generated is relative to the project file location, not to the current working directory. `-r|--runtime ` From 51d3e2d3a1680ce0147b6062411dbabfe3dc34ee Mon Sep 17 00:00:00 2001 From: Wasiim Hosenbocus Date: Wed, 20 Sep 2017 04:02:46 +0400 Subject: [PATCH 04/27] Update how-to-write-a-simple-parallel-for-loop.md (#3174) Updated Cut to Copy in Copy/Cut and Paste this code into ... --- .../how-to-write-a-simple-parallel-for-loop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md index 9108d7537c7c2..1cf15bcb08e0d 100644 --- a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md +++ b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md @@ -60,7 +60,7 @@ This topic contains two examples that illustrate the From af9512df683acb2f695aac0150ee20f44326c2fa Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Tue, 19 Sep 2017 22:40:08 -0700 Subject: [PATCH 05/27] fixed formulas (#3182) * fixed formulas * fixed formula * fixed formula --- .../language-reference/keywords/using/using-static1.cs | 4 ++-- .../language-reference/keywords/using/using-static2.cs | 4 ++-- .../language-reference/keywords/using/using-static3.cs | 9 ++++----- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/samples/snippets/csharp/language-reference/keywords/using/using-static1.cs b/samples/snippets/csharp/language-reference/keywords/using/using-static1.cs index 66596826801d6..3827387bc98cf 100644 --- a/samples/snippets/csharp/language-reference/keywords/using/using-static1.cs +++ b/samples/snippets/csharp/language-reference/keywords/using/using-static1.cs @@ -15,12 +15,12 @@ public double Diameter get { return 2 * Radius; } } - public double Area + public double Circumference { get { return 2 * Radius * Math.PI; } } - public double Circumference + public double Area { get { return Math.PI * Math.Pow(Radius, 2); } } diff --git a/samples/snippets/csharp/language-reference/keywords/using/using-static2.cs b/samples/snippets/csharp/language-reference/keywords/using/using-static2.cs index f65e40a06fcd5..5d5b1189152af 100644 --- a/samples/snippets/csharp/language-reference/keywords/using/using-static2.cs +++ b/samples/snippets/csharp/language-reference/keywords/using/using-static2.cs @@ -16,12 +16,12 @@ public double Diameter get { return 2 * Radius; } } - public double Area + public double Circumference { get { return 2 * Radius * PI; } } - public double Circumference + public double Area { get { return PI * Pow(Radius, 2); } } diff --git a/samples/snippets/csharp/language-reference/keywords/using/using-static3.cs b/samples/snippets/csharp/language-reference/keywords/using/using-static3.cs index e5b635140e12d..447e91d16bd31 100644 --- a/samples/snippets/csharp/language-reference/keywords/using/using-static3.cs +++ b/samples/snippets/csharp/language-reference/keywords/using/using-static3.cs @@ -39,12 +39,12 @@ public double Diameter get { return 2 * Radius; } } - public double Area + public double Circumference { get { return 2 * Radius * PI; } } - public double Circumference + public double Area { get { return PI * Pow(Radius, 2); } } @@ -55,6 +55,5 @@ public double Circumference // Information about the circle: // Radius: 12.45 // Diameter: 24.90 -// Circumference: 486.95 -// Area: 78.23 - +// Circumference: 78.23 +// Area: 486.95 From 058c717776f232ac571841bc08cd0c203bf4735c Mon Sep 17 00:00:00 2001 From: Maira Wenzel Date: Wed, 20 Sep 2017 00:48:03 -0700 Subject: [PATCH 06/27] simplifying version list (#3176) --- ...roubleshoot-blocked-installations-and-uninstallations.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/framework/install/troubleshoot-blocked-installations-and-uninstallations.md b/docs/framework/install/troubleshoot-blocked-installations-and-uninstallations.md index c64715ed8ff0f..be56a411895dd 100644 --- a/docs/framework/install/troubleshoot-blocked-installations-and-uninstallations.md +++ b/docs/framework/install/troubleshoot-blocked-installations-and-uninstallations.md @@ -1,13 +1,9 @@ --- title: "Troubleshoot blocked .NET Framework installations and uninstallations" -ms.custom: "" ms.date: "05/26/2017" ms.prod: ".net-framework" -ms.reviewer: "" -ms.suite: "" ms.technology: - "dotnet-clr" -ms.tgt_pltfrm: "" ms.topic: "article" helpviewer_keywords: - ".NET Framework, troubleshooting blocked installations" @@ -21,7 +17,7 @@ manager: "wpickett" # Troubleshoot blocked .NET Framework installations and uninstallations -When you run the [web or offline installer](../../../docs/framework/install/guide-for-developers.md) for the .NET Framework 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, or 4.7 you might encounter an issue that prevents or blocks the installation of the .NET Framework. The following table lists possible blocking issues and provides links to troubleshooting information. +When you run the [web or offline installer](../../../docs/framework/install/guide-for-developers.md) for the .NET Framework 4.5 or later versions, you might encounter an issue that prevents or blocks the installation of the .NET Framework. The following table lists possible blocking issues and provides links to troubleshooting information. In Windows 8 and above, the .NET Framework is an operating system component and cannot be independently uninstalled. Updates to the .NET Framework appear in the **Installed Updates** tab of the Control Panel **Programs and Features** app. For operating systems on which the .NET Framework is not preinstalled, the .NET Framework appears in the **Uninstall or change a program** tab (or the **Add/Remove programs** tab) of the **Program and Features** app in Control Panel. For information on the Windows versions on which the .NET Framework is preinstalled, see [System Requirements](../../../docs/framework/get-started/system-requirements.md). From 3536654b237537f2eb2e7b2c6d9f6c31b84f349c Mon Sep 17 00:00:00 2001 From: Hans De Mulder Date: Wed, 20 Sep 2017 09:50:23 +0200 Subject: [PATCH 07/27] Minor fixes : inconsistent wording and some ghost characters (#3171) * what's new Tuples : sample use InvariantCulture * vb tuple example fix new language feature sample * minor typos * compiler warning corrected to match previously mentioned number * removed a "ghost" quote * fixed inconsistent "read-only" and "read only" * code formatting (missing space) --- docs/csharp/whats-new/csharp-6.md | 10 +++++----- samples/snippets/csharp/new-in-6/Newcode.cs | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/csharp/whats-new/csharp-6.md b/docs/csharp/whats-new/csharp-6.md index e81b1cf3754e7..70c94c4cc495b 100644 --- a/docs/csharp/whats-new/csharp-6.md +++ b/docs/csharp/whats-new/csharp-6.md @@ -64,7 +64,7 @@ auto-properties. C# 6 improves the auto-properties capabilities so that you can them in more scenarios. You won't need to fall back on the more verbose syntax of declaring and manipulating the backing field by hand so often. -The new syntax addresses scenarios for read only properties, and for initializing +The new syntax addresses scenarios for read-only properties, and for initializing the variable storage behind an auto-property. ### Read-only auto-properties @@ -97,7 +97,7 @@ public class Student public void ChangeName(string newLastName) { - // Generates CS 0200: Property or indexer cannot be assigned to -- it is read only + // Generates CS0200: Property or indexer cannot be assigned to -- it is read only LastName = newLastName; } } @@ -131,7 +131,7 @@ is part of the property declaration, making it easier to equate the storage allocation with public interface for `Student` objects. Property Initializers can be used with read/write properties as well -as read only properties, as shown here. +as read-only properties, as shown here. [!code-csharp[ReadWriteInitialization](../../../samples/snippets/csharp/new-in-6/newcode.cs#ReadWriteInitialization)] @@ -140,12 +140,12 @@ as read only properties, as shown here. The body of a lot of members that we write consist of only one statement that can be represented as an expression. You can reduce that syntax by writing an expression-bodied member instead. It works for methods and -read-only properties." For example, an override of `ToString()` is often +read-only properties. For example, an override of `ToString()` is often a great candidate: [!code-csharp[ToStringExpressionMember](../../../samples/snippets/csharp/new-in-6/newcode.cs#ToStringExpressionMember)] -You can also use expression-bodied members in read only properties as well: +You can also use expression-bodied members in read-only properties as well: [!code-csharp[FullNameExpressionMember](../../../samples/snippets/csharp/new-in-6/newcode.cs#FullNameExpressionMember)] diff --git a/samples/snippets/csharp/new-in-6/Newcode.cs b/samples/snippets/csharp/new-in-6/Newcode.cs index 7e792155a53af..6ae01daf2909c 100644 --- a/samples/snippets/csharp/new-in-6/Newcode.cs +++ b/samples/snippets/csharp/new-in-6/Newcode.cs @@ -35,7 +35,7 @@ public Student(string firstName, string lastName) public ICollection Grades { get; } = new List(); // // - public Standing YearInSchool { get; set;} = Standing.Freshman; + public Standing YearInSchool { get; set; } = Standing.Freshman; // // From 7b7b3edf860138a31467d68752d637653d5e40d8 Mon Sep 17 00:00:00 2001 From: Erik Dietrich Date: Wed, 20 Sep 2017 08:18:00 -0400 Subject: [PATCH 08/27] Adding C# version history post (#2867) * Create csharp-version-history.md * Added the actual text * Updated TOC with my entry. * first pass edit 1. Add Metadata 1. Change person 1. Formalize from blog post to docs style language. * Update csharp-version-history.md * fix build warnings on links. * respond to feedback * fixed build warnings * fixed version capitalization --- .../whats-new/csharp-version-history.md | 124 ++++++++++++++++++ docs/toc.md | 1 + 2 files changed, 125 insertions(+) create mode 100644 docs/csharp/whats-new/csharp-version-history.md diff --git a/docs/csharp/whats-new/csharp-version-history.md b/docs/csharp/whats-new/csharp-version-history.md new file mode 100644 index 0000000000000..0472c8c6fcc99 --- /dev/null +++ b/docs/csharp/whats-new/csharp-version-history.md @@ -0,0 +1,124 @@ +--- +title: The history of C# - C# Guide +description: What did the language look like in its earliest versions, and how has it evolved since? +keywords: C#, .NET, .NET Core, What's New, C# History +author: erikdietrich +ms.author: wiwagn +ms.date: 09/20/2017 +ms.topic: article +ms.prod: .net +ms.technology: devlang-csharp +ms.devlang: csharp +--- + +# The history of C# # + +What did the language look like in its earliest incarnations? And how has it evolved in the years since? + +## C# version 1.0 + +When you go back and look, C# version 1.0 looked a lot like Java. As [part of its stated design goals for ECMA](http://feeldotneteasy.blogspot.com/2011/01/c-design-goals.html), it sought to be a "simple, modern, general purpose object-oriented language." At the time, looking like Java meant it achieved those early design goals. + +But if you look back on C# 1.0 now, you'd find yourself a little dizzy. It lacked the built-in async capabilities and some of the slick functionality around generics that we take for granted. As a matter of fact, it lacked generics altogether. And [LINQ](../linq/index.md)? Not available yet. That would take some years to come out. + +C# version 1.0 looked stripped of features, compared to today. You'd find yourself writing some verbose code. But yet, you have to start somewhere. C# version 1.0 was a viable alternative to Java on the Windows platform. + +## C# version 2.0 + +Now things start to get interesting. Let's take a look at some major features of C# 2.0, released in 2005, along with Visual Studio 2005: + +- [Generics](../programming-guide/generics/index.md) +- [Partial types](../programming-guide/classes-and-structs/partial-classes-and-methods.md#partial-classes) +- [Anonymous methods](../programming-guide/statements-expressions-operators/anonymous-methods.md) +- [Nullable types](../programming-guide/nullable-types/index.md) +- [Iterators](../programming-guide/concepts/iterators.md) +- [Covariance and contravariance](../programming-guide/concepts/covariance-contravariance/index.md) + +While C# may have started as a pretty generic Object-Oriented (OO) language, C# version 2.0 changed that in a hurry. Once they had their feet under them, they went after some serious developer pain points. And they went after them in a big way. + +With generics, you have types and methods that can operate on an arbitrary type while still retaining type safety. So, for instance, having a lets you have `List` or `List` and perform type safe operations on those strings or integers while you iterate through them. This is better than creating `ListInt` inheritors or casting from `Object` for every operation. + +C# version 2.0 brought iterators. To put it succinctly, this lets you iterate through the items in a `List` (or other Enumerable types) with a `foreach` loop. Having this as a first-class part of the language dramatically enhanced readability of the language and people's ability to reason about the code. + +And yet, C# continued to play a bit of catch-up with Java. Java had already released versions that included generics and iterators. But that would soon change as the languages continued to evolve apart. + +## C# version 3.0 + +C# version 3.0 came in late 2007, along with Visual Studio 2008, though the full boat of language features would actually come with C# version 3.5. This version marked a major change in the growth of C#. It established C# as a truly formidable programming language. Let's take a look at some major features in this version: + +- [Auto implemented properties](../programming-guide/classes-and-structs/auto-implemented-properties.md) +- [Anonymous types](../programming-guide/classes-and-structs/anonymous-types.md) +- [Query expressions](../linq/query-expression-basics.md) +- [Lambda expression](https://www.daedtech.com/introduction-to-c-lambda-expressions/) +- [Expression trees](https://blogs.msdn.microsoft.com/charlie/2008/01/31/expression-tree-basics/) +- [Extension methods](https://www.codeproject.com/Tips/709310/Extension-Method-In-Csharp) + +In retrospect, many of these features seem both inevitable and inseparable. They all fit together strategically. It's generally thought that C# version's killer feature was the query expression, also known as Language-Integrated Query (LINQ). + +A more nuanced view examines expression tress, lambda expressions, and anonymous types as the foundation upon which LINQ is constructed. But, in either case, C# 3.0 presented a revolutionary concept. C# 3.0 had begun to lay the groundwork for turning C# into a hybrid Object Oriented / Functional language. + +Specifically, you could now write SQL-style, declarative queries to perform operations on collections, among other things. Instead of writing a `for` loop to compute the average of a list of integers, you could now do that as simply as `list.Average()`. The combination of query expressions and extension methods made it look as though that list of integers had gotten a whole lot smarter. + +It took time for people to really grasp and integrate the concept, but they gradually did. And now, years later, code is much more concise, simple, and functional. + +## C# version 4.0 + +C# version 4.0 would have had a difficult time living up to the groundbreaking status of version 3.0. With version 3.0, C# had moved the language firmly out from the shadow of Java and into prominence. The language was quickly becoming elegant. + +The next version did introduce some interesting new features: + +- [Dynamic binding](../language-reference/keywords/dynamic.md) +- [Named/optional arguments](../programming-guide/classes-and-structs/named-and-optional-arguments.md) +- [Generic covariant and contravariant](../../standard/generics/covariance-and-contravariance.md) +- [Embedded interop types](https://stackoverflow.com/questions/20514240/whats-the-difference-setting-embed-interop-types-true-and-false-in-visual-studi) + +Embedded interop types alleviated a deployment pain. Generic covariance and contravariance give you more power to use generics, but they're a bit academic and probably most appreciated by framework and library authors. Named and optional parameters let you eliminate many method overloads and provide convenience. But none of those features are exactly paradigm altering. + +The major feature was the introduction of the `dynamic` keyword. The `dynamic` keyword introduced into C# version 4.0 the ability to override the compiler on compile-time typing. By using the dynamic keyword, you can create constructs similar to dynamically typed languages like JavaScript. You can create a `dynamic x = "a string"` and then add six to it, leaving it up to the runtime to sort out what should happen next. + +This gives you the potential for errors but also great power within the language. + +## C# version 5.0 + +C# version 5.0 was a very focused version of the language. Nearly all of the effort for that version went into another groundbreaking language concept. Here is the major features list: + +- [Asynchronous members](../async.md) +- [Caller info attributes](https://www.codeproject.com/Tips/606379/Caller-Info-Attributes-in-Csharp) + +The caller info attribute lets you easily retrieve information about the context in which you're running without resorting to a ton of boilerplate reflection code. It has many uses in diagnostics and logging tasks. + +But `async` and `await` are the real stars of this release. When these features came out in 2012, C# changed the game again by baking asynchrony into the language as a first-class participant. If you've ever dealt with long running operations and the implementation of webs of callbacks, you probably loved this language feature. + +## C# version 6.0 + +With versions 3.0 and 5.0, C# had added some impressive features in an object oriented language. With version 6.0, it would go away from doing a dominant killer feature and instead release many features that delighted users of the language. Here are some of them: + +- [Static imports](../language-reference/keywords/using-static) +- [Exception filters](https://www.thomaslevesque.com/2015/06/21/exception-filters-in-c-6/) +- [Property initializers](http://geekswithblogs.net/WinAZ/archive/2015/06/30/whatrsquos-new-in-c-6.0-auto-property-initializers.aspx) +- [Expression bodied members](https://lostechies.com/jimmybogard/2015/12/17/c-6-feature-review-expression-bodied-function-members/) +- [Null propagator](https://davefancher.com/2014/08/14/c-6-0-null-propagation-operator/) +- [String interpolation](../language-reference/keywords/interpolated-strings.md) +- [nameof operator](https://stackoverflow.com/questions/31695900/what-is-the-purpose-of-nameof) +- [Dictionary initializer](../programming-guide/classes-and-structs/how-to-initialize-a-dictionary-with-a-collection-initializer.md) + +Each of these features is interesting in its own right. But if you look at them altogether, you see an interesting pattern. In this version, C# eliminated language boilerplate to make code more terse and readable. So for fans of clean, simple code, this language version was a huge win. + +They did one other thing along with this version, though it's not a traditional language feature in itself. They released [Roslyn the compiler as a service](https://github.com/dotnet/roslyn). The C# compiler is now written in C#, and you can use the compiler as part of your programming efforts. + +## C# version 7.0 + +The most recent major version is C# version 7.0. This version has some evolutionary and cool stuff in the vein of C# 6.0, but without the compiler as a service. Here are some of the new features: + +- [Out variables](http://www.c-sharpcorner.com/article/out-variables-in-c-sharp-7-0/) +- [Tuples and deconstruction](https://www.thomaslevesque.com/2016/08/23/tuple-deconstruction-in-c-7/) +- [Pattern matching](./csharp-7.md#pattern-matching) +- [Local functions](http://www.infoworld.com/article/3182416/application-development/c-7-in-depth-exploring-local-functions.html) +- [Expanded expression bodied members](./csharp-7.md#more-expression-bodied-members) +- [Ref locals and returns](./csharp-7.md#ref-locals-and-returns) + +All of these features offer cool new capabilities for developers and the opportunity to write even cleaner code than ever. A highlight is condensing the declaration of variables to use with the `out` keyword and by allowing multiple return values via tuple. + +But C# is being put to ever broader use. .NET Core now targets any operating system and has its eyes firmly on the cloud and on portability. This certainly occupies the language designers' thoughts and time, in addition to coming up with new features. + +_Article_ [_originally published on the NDepend blog_](https://blog.ndepend.com/c-versions-look-language-history/)_, courtesy of Erik Dietrich and Patrick Smacchia._ diff --git a/docs/toc.md b/docs/toc.md index 87ea6136823e3..5edb24dea92e0 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -197,6 +197,7 @@ ### [What's new in C# 7.1](csharp/whats-new/csharp-7-1.md) ### [What's new in C# 7](csharp/whats-new/csharp-7.md) ### [What's new in C# 6](csharp/whats-new/csharp-6.md) +### [C# Version History](csharp/whats-new/csharp-version-history.md) ### [Relationships between language and framework](csharp/whats-new/relationships-between-language-and-library.md) From eb4056d44085cc0b14072a8c7f0a8c280fed581a Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 20 Sep 2017 14:55:18 -0700 Subject: [PATCH 09/27] Learn C# Tutorial (#2306) * First draft of new tutorial Learn the structure of a C# program, and explore the string class. proofread and tighten language. respond to feedback 2nd draft Move more code earlier. Tighten vocabulary discussions. Update outline start on the next draft. add section on searching strings fix build errors finish the string tutorial. reorder: ready for proofread. proofread update to use new syntax Update Tutorial to use the new engine typo in the title * build test, try samples * 2nd draft of the numbers tutorial. * proofread the second tutorial and create the third Branching and looping is ready for initial review. * respond to feedback on first tutorial. * proof read 3rd tutorial And add links to other C# Guide content * Remove links to upcoming tutorials. * Respond to feedback. * fix yaml parsing error. * More feedback. * feedback from team review Configure ms.technology for all quick starts to be devlang-csharp-interactive. Update .NET home page and C# Guide home page to point to the interactive tutorials. * Describe booleans, and update metadata. * add a tip about compiler messages * update timings of tutorials, update tip text * final review. --- .openpublishing.publish.config.json | 3 +- docfx.json | 7 +- docs/csharp/index.md | 4 +- .../quick-starts/branches-and-loops.yml | 257 ++++++++++++++++ docs/csharp/quick-starts/hello-world.yml | 188 ++++++++++++ docs/csharp/quick-starts/index.md | 46 +++ .../csharp/quick-starts/numbers-in-csharp.yml | 285 ++++++++++++++++++ docs/csharp/quick-starts/toc.md | 4 + docs/toc.md | 1 + index.md | 1 + toc.yml | 3 + 11 files changed, 795 insertions(+), 4 deletions(-) create mode 100644 docs/csharp/quick-starts/branches-and-loops.yml create mode 100644 docs/csharp/quick-starts/hello-world.yml create mode 100644 docs/csharp/quick-starts/index.md create mode 100644 docs/csharp/quick-starts/numbers-in-csharp.yml create mode 100644 docs/csharp/quick-starts/toc.md diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 0630b31e5edb5..d907c8028404d 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -54,7 +54,8 @@ "type_mapping": { "Conceptual": "Content", "ManagedReference": "Content", - "RestApi": "Content" + "RestApi": "Content", + "Tutorial": "Content" }, "build_entry_point": "docs", "template_folder": "_themes", diff --git a/docfx.json b/docfx.json index c92edaf5bdfc1..88ccb46b9f7da 100644 --- a/docfx.json +++ b/docfx.json @@ -16,7 +16,8 @@ }, { "files": [ - "**/*.md" + "**/*.md", + "**/*.yml" ], "src": "docs", "dest": ".", @@ -54,7 +55,8 @@ }, { "files": [ - "core/**/*.md" + "core/**/*.md", + "core/**/*.yml" ] }, { @@ -140,6 +142,7 @@ }, "ms.technology": { "_csharplang/spec/*.md": "devlang-csharp", + "csharp/quick-starts/**": "csharp-interactive", "_vblang/spec/*.md": "devlang-visual-basic" }, "ms.date": { diff --git a/docs/csharp/index.md b/docs/csharp/index.md index 9d5d41537ef5b..7ab7c362ec50c 100644 --- a/docs/csharp/index.md +++ b/docs/csharp/index.md @@ -22,7 +22,9 @@ ms.author: "wiwagn" The C# guide provides a wealth of information about the C# language. This site has many different audiences. Depending on your experience with programming, or with the C# language and .NET, you may wish to explore different sections of this guide. * For brand-new developers: - - Start with our [tutorials](tutorials/index.md) section. These tutorials show you how to create C# programs from scratch. The tutorials provide a step-by-step process to create programs. You'll learn the language concepts, and how to build C# programs on your own. If you prefer reading overview information first, try our [tour of the C# language](tour-of-csharp/index.md). It explains the concepts of the C# language. After reading this, you'll have a basic understanding of the language, and be ready to try the tutorials, or build something on your own. + - Start with our [Quick starts](quick-starts/index.md) section. These let you explore + the C# language interactively in your browser. From there, you can move on to our + [tutorials](tutorials/index.md) section. These tutorials show you how to create C# programs from scratch. The tutorials provide a step-by-step process to create programs. You'll learn the language concepts, and how to build C# programs on your own. If you prefer reading overview information first, try our [tour of the C# language](tour-of-csharp/index.md). It explains the concepts of the C# language. After reading this, you'll have a basic understanding of the language, and be ready to try the tutorials, or build something on your own. * For developers new to C#: - If you've done development before, but are new to C#, read the [tour of the C# language](tour-of-csharp/index.md). You will learn the basic syntax and structure for the language, and you can use the language tour to contrast C# with other languages you've used. You can also browse the [tutorials](tutorials/index.md) to try basic C# programs. diff --git a/docs/csharp/quick-starts/branches-and-loops.yml b/docs/csharp/quick-starts/branches-and-loops.yml new file mode 100644 index 0000000000000..db51429ff7158 --- /dev/null +++ b/docs/csharp/quick-starts/branches-and-loops.yml @@ -0,0 +1,257 @@ +### YamlMime:YamlDocument +documentType: Tutorial +title: Branches and loops +metadata: + title: Branches and loops + description: In this tutorial about branches and loops, you'll use your browser to learn C# interactively. You're going to write C# code and see the results of compiling and running your code directly in the browser. + audience: Developer + level: Beginner + displayType: two-column + interactive: csharp +items: +- durationInMinutes: 1 + content: | + This tutorial teaches you about how to write code that examines variables and changes execution path based on those variables. You'll write C# interactively, using your browser to write C# and see the results of compiling and running your code. It contains a series of lessons that explore branching and looping constructs in C#. These lessons teach you the fundamentals of the C# language. +- title: Make decisions using the if statement + durationInMinutes: 4 + content: | + Run the following code in the interactive window. To do that, type the following code block in the interactive window and click the **Run** button: + + ```csharp + int a = 5; + int b = 6; + if (a + b > 10) + Console.WriteLine("The answer is greater than 10."); + ``` + + Modify the declaration of `b` so that the sum is less than 10: + + ```csharp + int b = 3; + ``` + + Click the **Run** button again. Because the answer is less than 10, nothing is printed. The **condition** you're testing is false. You don't have any code to execute because you've only + written one of the possible branches for an `if` statement: the true branch. + + > [!TIP] + > As you explore C# (or any programming language), you'll + > make mistakes when you write code. The **compiler** will + > find those errors and report them to you. When the output + > contains error messages, look closely at the example code, + > and the code in the interactive window to see what to fix. + > That exercise will help you learn the structure of C# code. + + This first sample shows the power of `if` and boolean types. A *boolean* is a variable that can have one of two values: `true` or `false`. C# defines a special type, `bool` for boolean variables. The `if` statement checks the value of a `bool`. When the value is `true`, the statement following the `if` executes. Otherwise, it is skipped. + + This process of checking conditions and executing statements based on those conditions is very powerful. Let's explore more. + +- title: Make if and else work together + durationInMinutes: 10 + content: | + + To execute different code in both the true and false branches, you + create an `else` branch that executes when the condition is false. Try this: + + ```csharp + int a = 5; + int b = 3; + if (a + b > 10) + Console.WriteLine("The answer is greater than 10"); + else + Console.WriteLine("The answer is not greater than 10"); + ``` + + The statement following the `else` keyword executes only when the condition being tested is `false`. Combining `if` and `else` with boolean conditions provides all the power you need. + + > [!IMPORTANT] + > The indentation under the `if` and `else` statements is for human readers. + > The C# language doesn't treat indentation or whitespace as significant. + > The statement following the `if` or `else` keyword will be executed based + > on the condition. All the samples in this tutorial follow a common + > practice to indent lines based on execution. + + Because indentation is not significant, you need to use `{` and `}` to + indicate when you want more than one statement to be part of the block + that executes conditionally. C# programmers typically use those braces + on all `if` and `else` clauses. The following example is the same as what you + just created. Try it. + + ```csharp + int a = 5; + int b = 3; + if (a + b > 10) + { + Console.WriteLine("The answer is greater than 10"); + } + else + { + Console.WriteLine("The answer is not greater than 10"); + } + ``` + + > [!TIP] + > Through the rest of this tutorial, the code samples all include the braces, + > following accepted practices. + + You can test more complicated conditions: + + ```csharp + int a = 5; + int b = 3; + int c = 4; + if ((a + b + c > 10) && (a > b)) + { + Console.WriteLine("The answer is greater than 10"); + Console.WriteLine("And the first number is greater than the second"); + } + else + { + Console.WriteLine("The answer is not greater than 10"); + Console.WriteLine("Or the first number is not greater than the second"); + } + ``` + + The `&&` represents "and". It means both conditions must be true to execute + the statement in the true branch. These examples also show that you can have multiple + statements in each conditional branch, provided you enclose them in `{` and `}`. + + You can also use `||` to represent "or": + + ```csharp + int a = 5; + int b = 3; + int c = 4; + if ((a + b + c > 10) || (a > b)) + { + Console.WriteLine("The answer is greater than 10"); + Console.WriteLine("Or the first number is greater than the second"); + } + else + { + Console.WriteLine("The answer is not greater than 10"); + Console.WriteLine("And the first number is not greater than the second"); + } + ``` + +- title: Use loops to repeat operations + durationInMinutes: 6 + content: | + Another important concept to create larger programs is **loops**. You'll + use loops to repeat statements that you want executed more than once. Try + this code in the interactive window: + + ```csharp + int counter = 0; + while (counter < 10) + { + Console.WriteLine("Hello World! The counter is " + counter); + counter++; + } + ``` + + The `while` statement checks a condition and executes the statement + following the `while`. It will repeat checking the condition and + executing those statements until the condition is false. + + There's one other new operator in this example. The `++` after + the `counter` variable is the **increment** operator. It adds 1 + to the value of counter, and stores that value in the counter variable. + + > [!IMPORTANT] + > Make sure that the `while` loop condition does switch to + > false as you execute the code. Otherwise, you create an + > **infinite loop** where your program never ends. Let's + > not demonstrate that, because the engine that runs your + > code will time out and you'll see no output from your program. + + The `while` loop tests the condition before executing the code + following the `while`. The `do` ... `while` loop executes the + code first, and then checks the condition. It looks like this: + + ```csharp + int counter = 0; + do + { + Console.WriteLine("Hello World! The counter is " + counter); + counter++; + } while (counter < 10); + ``` + + This `do` loop and the earlier `while` loop work the same. + + Let's move on to one last loop statement. + +- title: Work with the for loop + durationInMinutes: 5 + content: | + Another common loop statement that you'll see in C# code is the + `for` loop. Try this code in the interactive window: + + ```csharp + for(int counter = 0; counter < 10; counter++) + { + Console.WriteLine("Hello World! The counter is " + counter); + } + ``` + + This does the same work as the `while` loop and the `do` loop you've + already used. The `for` statement has three parts that control + how it works. + + The first part is the **for initializer**: `for counter = 0;` declares + that `counter` is the loop variable, and sets its initial value to `0`. + + The middle part is the **for condition**: `counter < 10` declares that this + `for` loop continues to execute as long as the value of counter is less than 10. + + The final part is the **for iterator**: `counter++` specifies how to modify the loop + variable after executing the block following the `for` statement. Here, it specifies + that `counter` should be incremented by 1 each time the block executes. + + Experiment with these yourself. Try each of the following: + + - Change the initializer to start at a different value. + - Change the condition to stop at a different value. + + When you're done, let's move on to write some code yourself to + use what you've learned. + +- title: Combining branches and loops + durationInMinutes: 12 + content: | + Now that you've seen the `if` statement and the looping + constructs in the C# language, see if you can write C# code to + find the sum of all integers 1 through 20 that are divisible + by 3. Here are a few hints: + + - The `%` operator gives you the remainder of a division operation. + - The `if` statement givesx you the condition to see if a number should be part of the sum. + - The `for` loop can help you repeat a series of steps for all the numbers 1 through 20. + + Try it yourself. Then check how you did. + +- title: Complete challenge + durationInMinutes: 1 + content: | + Did you come up with something like this? + + ```csharp + int sum = 0; + for (int number = 1; number < 21; number++) + { + if (number % 3 == 0) + { + sum = sum + number; + } + } + Console.WriteLine("The sum is " + sum); + ``` + + content: | + You've completed the "branches and loops" tutorial. You can learn more about these concepts in these topics: + + [If and else statement](../language-reference/keywords/if-else.md) + [While statement](../language-reference/keywords/while.md) + [Do statement](../language-reference/keywords/do.md) + [For statement](../language-reference/keywords/for.md) + diff --git a/docs/csharp/quick-starts/hello-world.yml b/docs/csharp/quick-starts/hello-world.yml new file mode 100644 index 0000000000000..c6504b1bab97b --- /dev/null +++ b/docs/csharp/quick-starts/hello-world.yml @@ -0,0 +1,188 @@ +### YamlMime:YamlDocument +documentType: Tutorial +title: Hello C# +metadata: + title: Hello C#. Your first introduction to the C# language. + description: In this tutorial, you'll use your browser to learn C# interactively. You write C# code and see the results of compiling and running your code directly in the browser. + audience: Developer + level: Beginner + nextTutorialHref: numbers-in-csharp + nextTutorialTitle: Numbers in C# + displayType: two-column + interactive: csharp +items: +- durationInMinutes: 1 + content: | + This tutorial teaches you C# interactively, using your browser to write C# and see the results of compiling and running your code. It contains a series of lessons that begin with a "Hello World" program. These lessons teach you the fundamentals of the C# language. +- title: Run your first C# program + durationInMinutes: 2 + content: | + Run the following code in the interactive window. To do that, type code block in the interactive window and click the **Run** button: + + ```csharp + Console.WriteLine("Hello World!"); + ``` + + Congratulations! You've run your first C# program. It's a simple program that prints the message "Hello World!". + Let's move on and explore more. + +- title: Declare and use variables + durationInMinutes: 3 + content: | + Your first program printed the `string` "Hello World!" on + the screen. The rest of this lesson explores working with + the `string` type, which represents text in C#. + + > [!TIP] + > As you explore C# (or any programming language), you'll + > make mistakes when you write code. The **compiler** will + > find those errors and report them to you. When the output + > contains error messages, look closely at the example code, + > and the code in the interactive window to see what to fix. + > That exercise will help you learn the structure of C# code. + + Your first program is limited to printing one message. You can write more + useful programs by using **variables**. A **variable** is a symbol you can + use to run the same code with different values. Let's try it! Replace the + code you've written in the interactive window with the following code: + + ```csharp + string aFriend = "Bill"; + Console.WriteLine(aFriend); + ``` + + The first line declares a variable, `aFriend` and assigns it a value, "Bill". The second line + prints out the name. + + You can assign different values to any variable you declare. You can change + the name to one of your friends. Add these two lines in the interactive window + following the code you've already added: + + ```csharp + aFriend = "Maria"; + Console.WriteLine(aFriend); + ``` + + Notice that the same line of code prints two different messages, based on + the value stored in the `aFriend` variable. + + You may have also noticed that the word "Hello" was missing in the last two messages. Let's fix + that now. Modify the lines that print the message to the following: + + ```csharp + Console.WriteLine("Hello " + aFriend); + ``` + + Click **Run** again to see the results. +- title: Work with strings + durationInMinutes: 5 + content: | + Your last edit was our first look at what you can do with strings. Let's explore more. + + The `+` is called an operator in C#. When applied to strings like `firstString + secondString`, a new string is created with the text from the first followed by the text from the second. This is referred to as *string concatenation*. You can combine any number of strings, including string variables. Try this: + + ```csharp + string firstFriend = "Maria"; + string secondFriend = "Sage"; + Console.WriteLine("My friends are " + firstFriend + " and " + secondFriend); + ``` + + As you explore more with strings, you can find the length of a string using `Length`. `Length` is a **property** of a string and it returns the number of characters in that string. Add the following code at the bottom of the interactive window: + + ```csharp + Console.WriteLine("The name " + firstFriend + " has " + firstFriend.Length + " letters."); + Console.WriteLine("The name " + secondFriend + " has " + secondFriend.Length + " letters."); + ``` + + > [!TIP] + > This is a good time to explore on your own. You've learned that `Console.WriteLine()` + > writes text to the screen. You've learned how to declare variables and + > concatenate strings together. Experiment in the interactive window. Write + > some more messages yourself. Build strings using the `+` operator. +- title: Do more with strings + durationInMinutes: 5 + content: | + You've been using a **method**, , to print messages. A **method** is a block of code that implements some action. It has a name, so you can access it. + + The `string` type has many useful methods. Let's explore the method, and related methods and . These methods remove leading and trailing spaces: + + ```csharp + string message = " Hello World! "; + Console.WriteLine("[" + message + "]"); + + string trimmedMessage = message.TrimStart(); + Console.WriteLine("[" + trimmedMessage + "]"); + + trimmedMessage = message.TrimEnd(); + Console.WriteLine("[" + trimmedMessage + "]"); + + trimmedMessage = message.Trim(); + Console.WriteLine("[" + trimmedMessage + "]"); + ``` + + This sample reinforces a couple of important concepts for working with strings. The methods that manipulate strings return new string objects rather than making modifications in place. You can see that each call to any of the `Trim` methods returns a new string, but does not change the original message. + + There are other methods available to work with a string. For example, you've probably used a search and replace command in an editor or word processor. The method does something similar in a `string`. It searches for a substring, and replaces it with different text. The method takes two **parameters**. These are the strings between the parentheses. The first string is the text to search for. The second string is the text to replace it with. Try it for yourself. Add this code: + + ```csharp + string message = "Hello World!"; + Console.WriteLine(message); + message = message.Replace("Hello", "Greetings"); + Console.WriteLine(message); + ``` + + Two other useful methods make a string ALL CAPS or all lower case. Try the following code: + + ```csharp + string message = "Hello World!"; + Console.WriteLine(message); + Console.WriteLine(message.ToUpper()); + Console.WriteLine(message.ToLower()); + ``` +- title: Search strings + durationInMinutes: 10 + content: | + The other part of a *search and replace* operation is to find text in a + string. You can use the method for searching. It + tells you if a string contains a substring inside it. Try the following + code to explore : + + ```csharp + string message = "You say goodbye, and I say hello"; + Console.WriteLine(message.Contains("goodbye")); + Console.WriteLine(message.Contains("greetings")); + ``` + + The method returns a **boolean** value which tells you if the + string you were searching for was found. A **boolean** stores either a `true` or a + `false` value. You'll learn more about **boolean** values + in a later lesson. + + ***Challenge*** + + There are two similar methods, and that also search for sub-strings in a string. These find a substring at the beginning or the + end of the string. Try to modify the previous sample to use and + instead of . Search for "You" or "goodbye" at the beginning of a string. Search for "hello" or "goodbye" at the end of a string. + + > [!Note] + > Watch your punctuation when you test for the text at the end of the string. If the string + > ends with a period, you must check for a string that ends with a period. + +- title: Complete challenge + durationInMinutes: 3 + content: | + Did you come up with something like this? + + ```csharp + string message = "You say goodbye, and I say hello"; + Console.WriteLine(message.StartsWith("You")); + Console.WriteLine(message.StartsWith("goodbye")); + + Console.WriteLine(message.EndsWith("hello")); + Console.WriteLine(message.EndsWith("goodbye")); + ``` +- content: | + You've completed the "Hello C#" tutorial. + + You can learn more about working with the `string` type in the + [C# Programming Guide](../programming-guide/index.md) topic on [strings](../programming-guide/strings/index.md). diff --git a/docs/csharp/quick-starts/index.md b/docs/csharp/quick-starts/index.md new file mode 100644 index 0000000000000..235defec1d1d6 --- /dev/null +++ b/docs/csharp/quick-starts/index.md @@ -0,0 +1,46 @@ +--- +title: Quick Starts - C# Guide | Microsoft Docs +description: Learn C# in your browser +keywords: C#, Get Started, Lessons, Interactive +author: billwagner +ms.author: wiwagn +ms.date: 09/18s/2017 +ms.topic: article +ms.prod: .net +ms.technology: devlang-csharp +ms.devlang: csharp +--- +# C# Quick starts # + +Welcome to the C# Quick starts. These start with interactive lessons +that you can run in your browser. + +The first lessons explain C# concepts using small snippets of code. You'll +learn the basics of C# syntax and how to work with data types like strings, +numbers, and booleans. It's all interactive, and you'll be writing code +within minutes. These first lessons assume no prior knowledge of +programming or the C# language. + +## [Hello world](hello-world) + +In the [Hello world](hello-world) lesson, you'll create the most basic +C#. You'll explore the `string` type and how to work with text. + +## [Numbers in C#](numbers-in-csharp) + +In the [Numbers in C#](numbers-in-csharp) lesson, you'll learn +how computers store numbers and how to perform calculations with different +number types. You'll learn the basics of rounding, and how to perform +mathematical calculations using C#. + +This lesson assumes that you have finished the [Hello world](hello-world) tutorial. + +## [Branches and loops](branches-and-loops) + +The [Branches and loops](branches-and-loops) lesson teaches the basics of selecting +different paths of code based on the values stored in variables. You'll learn the +basics of control flow, which is the basics of how programs make decisions and choose +different actions. + +This beginner lesson assumes that you have finished the [Hello World](hello-world) and +[Numbers in C#](numbers-in-csharp) lessons. diff --git a/docs/csharp/quick-starts/numbers-in-csharp.yml b/docs/csharp/quick-starts/numbers-in-csharp.yml new file mode 100644 index 0000000000000..80ef37459a679 --- /dev/null +++ b/docs/csharp/quick-starts/numbers-in-csharp.yml @@ -0,0 +1,285 @@ +### YamlMime:YamlDocument +documentType: Tutorial +title: Numbers in C# +metadata: + title: Numbers in C# + description: In this tutorial about numeric types, you'll use your browser to learn C# interactively. You're going to write C# code and see the results of compiling and running your code directly in the browser. + audience: Developer + level: Beginner + nextTutorialHref: branches-and-loops + nextTutorialTitle: Branches and loops in C# + displayType: two-column + interactive: csharp +items: +- durationInMinutes: 1 + content: | + This tutorial teaches you about the number types in C# interactively, using your browser to write C# and see the results of compiling and running your code. It contains a series of lessons that explore numbers and math operations in C#. These lessons teach you the fundamentals of the C# language. +- title: Explore integer math + durationInMinutes: 4 + content: | + Run the following code in the interactive window. To do that, type the following code block in the interactive window and click the **Run** button: + + ```csharp + int a = 18; + int b = 6; + int c = a + b; + Console.WriteLine(c); + ``` + + You've just seen one of the fundamental math operations with integers. The `int` type represents an **integer**, a positive or negative whole number. You use the `+` symbol for addition. Other common mathematical operations for integers include: + + - `-` for subtraction + - `*` for multiplication + - `/` for division + + > [!TIP] + > Throughout this tutorial, you can explore on your own by modifying the code you've written in the interactive window. This tutorial provides examples that you can try at each step. + + Start by exploring those different operations. Modify the third line to try each of these operations. After each edit, click the **Run** button. + + Subtraction: + + ```csharp + int c = a - b; + ``` + + Multiplication: + + ```csharp + int c = a * b; + ``` + + Division: + + ```csharp + int c = a / b; + ``` + + You can also experiment by performing multiple mathematics operations in the same line, if you'd like. + + > [!TIP] + > As you explore C# (or any programming language), you'll + > make mistakes when you write code. The **compiler** will + > find those errors and report them to you. When the output + > contains error messages, look closely at the example code, + > and the code in the interactive window to see what to fix. + > That exercise will help you learn the structure of C# code. + +- title: Explore order of operations + durationInMinutes: 7 + content: | + The C# language defines the precedence of different mathematics operations + with rules consistent with the rules you learned in mathematics. + Multiplication and division take precedence over addition and subtraction. + Explore that by running the following code in the interactive window: + + ```csharp + int a = 5; + int b = 4; + int c = 2; + int d = a + b * c; + Console.WriteLine(d); + ``` + + The output demonstrates that the multiplication is performed before the addition. + + You can force a different order of operation by adding parentheses around + the operation or operations you want performed first: + + ```csharp + int a = 5; + int b = 4; + int c = 2; + int d = (a + b) * c; + Console.WriteLine(d); + ``` + + Explore more by combining many different operations. Replace the fourth line above with something like this: + + ```csharp + int d = (a + b) - 6 * c + (12 * 4) / 3 + 12; + ``` + + You may have noticed an interesting behavior for integers. Integer + division always produces an integer result, even when the mathematical + result would include a decimal or fraction portion. + + If you haven't seen this behavior, try the following: + + ```csharp + int a = 7; + int b = 4; + int c = 3; + int d = (a + b) / c; + Console.WriteLine(d); + ``` + + Click **Run** again to see the results. +- title: Explore integer precision and limits + durationInMinutes: 5 + content: | + That last sample showed you that integer division truncates the result. + You can get the **remainder** by using the **modulo** operator, the `%` character: + + ```csharp + int a = 7; + int b = 4; + int c = 3; + int d = (a + b) / c; + int e = (a + b) % c; + Console.WriteLine("quotient: " + d); + Console.WriteLine("remainder: " + e); + ``` + + The C# integer type differs from mathematical integers in one other + way: the `int` type has minimum and maximum limits. Run this code + in the interactive window to see those limits: + + ```csharp + int max = int.MaxValue; + int min = int.MinValue; + Console.WriteLine("The range of integers is " + min + " to " + max); + ``` + + If a calculation produces a value that exceeds those limits, you + have an **underflow** or **overflow** condition. The answer appears + to wrap from one limit to the other. Add these two lines to the interactive + window to see an example: + + ```csharp + int what = max + 3; + Console.WriteLine("An example of overflow: " + what); + ``` + + Notice that the answer is very close to the minimum (negative) integer. It's + the same as `min + 2`. + The addition operation **overflowed** the allowed values for integers. + The answer is a very large negative number because an overflow "wraps around" + from the largest possible integer value to the smallest. + + There are other numeric types with different limits and precision that you + would use when the `int` type doesn't meet your needs. Let's explore those next. + +- title: Work with the double type + durationInMinutes: 5 + content: | + The `double` numeric type represents a double-precision floating point + number. Those terms may be new to you. A **floating point** number is + useful to represent non-integral numbers that may be very large, or small + in magnitude. **Double-precision** means that these numbers are stored + using greater precision than **single-precision**. On modern computers, + it is more common to use double precision than single precision numbers. + Let's explore. Try the following code in the interactive window and see the result: + + ```csharp + double a = 5; + double b = 4; + double c = 2; + double d = (a + b) / c; + Console.WriteLine(d); + ``` + + Notice that the answer includes the decimal portion of the quotient. Try a slightly + more complicated expression with doubles: + + ```csharp + double a = 19; + double b = 23; + double c = 8; + double d = (a + b) / c; + Console.WriteLine(d); + ``` + + The range of a double value is much greater than integer values. Try the following + code in the interactive window: + + ```csharp + double max = double.MaxValue; + double min = double.MinValue; + Console.WriteLine("The range of double is " + min + " to " + max); + ``` + + These values are printed out to represent scientific notation. The number to + the left of the `E` is the significant. The number to the right is the exponent, + as a power of 10. Internally, these numbers are represented similarly, but in + a binary form. One part represents the significant binary digits. + Another part represents where to place the binary point (analogous to a decimal point) relative to + those significant digits. + + Just like decimal numbers in math, doubles in C# can have rounding errors. Try this code: + + ```csharp + double third = 1.0 / 3.0; + Console.WriteLine(third); + ``` + + You know that `0.3` repeating is not exactly the same as `1/3`. + + ***Challenge*** + + Try other calculations with large numbers, small numbers, multiplication + and division using the `double` type. Try more complicated calculations. + + +- title: Work with fixed point types + durationInMinutes: 8 + content: | + You've seen the basic numeric types in C#: integers and doubles. There is one + other type to learn: the `decimal` type. The `decimal` type has a smaller + range, but greater precision than `double`. The term **fixed point** means + that the decimal point (or binary point) doesn't move. Let's take a look: + + ```csharp + decimal min = decimal.MinValue; + decimal max = decimal.MaxValue; + Console.WriteLine("The range of the decimal type is " + min + " to " + max); + ``` + + Notice that the range is smaller than the `double` type. You can see the greater + precision with the decimal type by trying the following code: + + ```csharp + double a = 1.0; + double b = 3.0; + Console.WriteLine(a / b); + + decimal c = 1.0M; + decimal d = 3.0M; + Console.WriteLine(c / d); + ``` + + The `M` suffix on the numbers is how you indicate that a constant should use the + `decimal` type. + + Notice that the math using the decimal type has more digits to the right + of the decimal point. + + ***Challenge*** + + Now that you've seen the different numeric types, write code that calculates + the area of a circle whose radius is 2.50 inches. Remember that the area of a circle + is the radius squared multiplied by PI. One hint: C# contains a constant + for PI: `Math.PI` that you can use for that value. + +- title: Complete challenge + durationInMinutes: 1 + content: | + Did you come up with something like this? + + ```csharp + double radius = 2.50; + double area = Math.PI * radius * radius; + Console.WriteLine(area); + ``` + + Try some other formulas if you'd like. + + content: | + You've completed the "Numbers in C#" tutorial. You can learn more about numbers in C# in the following topics: + + [Integral Types Table](../language-reference/keywords/integral-types-table.md) + [Floating-Point Types Table](../language-reference/keywords/floating-point-types-table.md) + [Built-In Types Table](../language-reference/keywords/built-in-types-table.md) + [Implicit Numeric Conversions Table](../language-reference/keywords/implicit-numeric-conversions-table.md) + [Explicit Numeric Conversions Table](../language-reference/keywords/explicit-numeric-conversions-table.md) + diff --git a/docs/csharp/quick-starts/toc.md b/docs/csharp/quick-starts/toc.md new file mode 100644 index 0000000000000..1ab657234f529 --- /dev/null +++ b/docs/csharp/quick-starts/toc.md @@ -0,0 +1,4 @@ +# [Quick Starts](index.md) +## [Hello world](hello-world) +## [Numbers in C#](numbers-in-csharp) +## [Branches and loops](branches-and-loops) diff --git a/docs/toc.md b/docs/toc.md index 5edb24dea92e0..3068142699b73 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -189,6 +189,7 @@ # [C# Guide](csharp/index.md) ## [Get Started](csharp/getting-started/) +## [Quick Starts](csharp/quick-starts/) ## [Tutorials](csharp/tutorials/) ## [Tour of C#](csharp/tour-of-csharp/) `Decimal` type that it is paired with by default. This can result in precision loss when you save data to the database. However, just the opposite can happen if the SQL Server `DECIMAL` type is configured with greater than 29 digits of precision. When a SQL Server `DECIMAL` type has been configured with a greater precision than the CLR , precision loss can occur when retrieving data from the database. + The default precision of SQL Server `DECIMAL` type (18 decimal digits to the left and right of the decimal point) is much smaller than the precision of the CLR `Decimal` type that it is paired with by default. This can result in precision loss when you save data to the database. However, just the opposite can happen if the SQL Server `DECIMAL` type is configured with greater than 29 digits of precision. When a SQL Server `DECIMAL` type has been configured with a greater precision than the CLR , precision loss can occur when retrieving data from the database. - The SQL Server `MONEY` and `SMALLMONEY` types, which are also paired with the CLR type by default, have a much smaller precision, which can result in overflow or data loss exceptions when saving data to the database. + The SQL Server `MONEY` and `SMALLMONEY` types, which are also paired with the CLR type by default, have a much smaller precision, which can result in overflow or data loss exceptions when saving data to the database. ## Text and XML Mapping @@ -136,21 +136,21 @@ In LINQ to SQL, the data model of a relational database maps to an object model |SQL Server Type|Default CLR Type mapping used by O/R Designer and SQLMetal| |---------------------|-----------------------------------------------------------------| -|`CHAR`|| -|`NCHAR`|| -|`VARCHAR`|| -|`NVARCHAR`|| -|`TEXT`|| -|`NTEXT`|| -|`XML`|| +|`CHAR`|| +|`NCHAR`|| +|`VARCHAR`|| +|`NVARCHAR`|| +|`TEXT`|| +|`NTEXT`|| +|`XML`|| - The next table shows the default type mappings used by the method to define which type of SQL columns are created to map to the CLR types defined in your object model or external mapping file. + The next table shows the default type mappings used by the method to define which type of SQL columns are created to map to the CLR types defined in your object model or external mapping file. -|CLR Type|Default SQL Server Type used by | +|CLR Type|Default SQL Server Type used by | |--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -||`NCHAR(1)`| -||`NVARCHAR(4000)`| -|[]|`NVARCHAR(4000)`| +||`NCHAR(1)`| +||`NVARCHAR(4000)`| +|[]|`NVARCHAR(4000)`| |Custom type implementing `Parse()` and `ToString()`|`NVARCHAR(MAX)`| There are many other text-based and XML mappings you can choose, but some may result in overflow or data loss exceptions while translating to or from the database. For more information, see the [Type Mapping Run Time Behavior Matrix](#BehaviorMatrix). @@ -166,13 +166,13 @@ In LINQ to SQL, the data model of a relational database maps to an object model - Comments - Although you can map and to SQL Server as shown in the [Type Mapping Run Time Behavior Matrix](#BehaviorMatrix), the method has no default SQL Server type mapping for these types. + Although you can map and to SQL Server as shown in the [Type Mapping Run Time Behavior Matrix](#BehaviorMatrix), the method has no default SQL Server type mapping for these types. ### Custom Types If a class implements `Parse()` and `ToString()`, you can map the object to any SQL text type (`CHAR`, `NCHAR`, `VARCHAR`, `NVARCHAR`, `TEXT`, `NTEXT`, `XML`). The object is stored in the database by sending the value returned by `ToString()` to the mapped database column. The object is reconstructed by invoking `Parse()` on the string returned by the database. > [!NOTE] -> LINQ to SQL does not support serialization by using . +> LINQ to SQL does not support serialization by using . ## Date and Time Mapping @@ -180,20 +180,20 @@ In LINQ to SQL, the data model of a relational database maps to an object model |SQL Server Type|Default CLR Type mapping used by O/R Designer and SQLMetal| |---------------------|-----------------------------------------------------------------| -|`SMALLDATETIME`|| -|`DATETIME`|| -|`DATETIME2`|| -|`DATETIMEOFFSET`|| -|`DATE`|| -|`TIME`|| +|`SMALLDATETIME`|| +|`DATETIME`|| +|`DATETIME2`|| +|`DATETIMEOFFSET`|| +|`DATE`|| +|`TIME`|| - The next table shows the default type mappings used by the method to define which type of SQL columns are created to map to the CLR types defined in your object model or external mapping file. + The next table shows the default type mappings used by the method to define which type of SQL columns are created to map to the CLR types defined in your object model or external mapping file. -|CLR Type|Default SQL Server Type used by | +|CLR Type|Default SQL Server Type used by | |--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -||`DATETIME`| -||`DATETIMEOFFSET`| -||`TIME`| +||`DATETIME`| +||`DATETIMEOFFSET`| +||`TIME`| There are many other date and time mappings you can choose, but some may result in overflow or data loss exceptions while translating to or from the database. For more information, see the [Type Mapping Run Time Behavior Matrix](#BehaviorMatrix). @@ -201,42 +201,42 @@ In LINQ to SQL, the data model of a relational database maps to an object model > The SQL Server types `DATETIME2`, `DATETIMEOFFSET`, `DATE`, and `TIME` are available starting with Microsoft SQL Server 2008. LINQ to SQL supports mapping to these new types starting with the .NET Framework version 3.5 SP1. ### System.Datetime - The range and precision of the CLR type is greater than the range and precision of the SQL Server `DATETIME` type, which is the default type mapping for the method. To help avoid exceptions related to dates outside the range of `DATETIME`, use `DATETIME2`, which is available starting with Microsoft SQL Server 2008. `DATETIME2` can match the range and precision of the CLR . + The range and precision of the CLR type is greater than the range and precision of the SQL Server `DATETIME` type, which is the default type mapping for the method. To help avoid exceptions related to dates outside the range of `DATETIME`, use `DATETIME2`, which is available starting with Microsoft SQL Server 2008. `DATETIME2` can match the range and precision of the CLR . - SQL Server dates have no concept of , a feature that is richly supported in the CLR. values are saved as is to the database without conversion, regardless of the original information. When values are retrieved from the database, their value is loaded as is into a with a of . For more information about supported methods, see [System.DateTime Methods](../../../../../../docs/framework/data/adonet/sql/linq/system-datetime-methods.md). + SQL Server dates have no concept of , a feature that is richly supported in the CLR. values are saved as is to the database without conversion, regardless of the original information. When values are retrieved from the database, their value is loaded as is into a with a of . For more information about supported methods, see [System.DateTime Methods](../../../../../../docs/framework/data/adonet/sql/linq/system-datetime-methods.md). ### System.TimeSpan - Microsoft SQL Server 2008 and the .NET Framework 3.5 SP1 let you map the CLR type to the SQL Server `TIME` type. However, there is a large difference between the range that the CLR supports and what the SQL Server `TIME` type supports. Mapping values less than 0 or greater than 23:59:59.9999999 hours to the SQL `TIME` will result in overflow exceptions. For more information, see [System.TimeSpan Methods](../../../../../../docs/framework/data/adonet/sql/linq/system-timespan-methods.md). + Microsoft SQL Server 2008 and the .NET Framework 3.5 SP1 let you map the CLR type to the SQL Server `TIME` type. However, there is a large difference between the range that the CLR supports and what the SQL Server `TIME` type supports. Mapping values less than 0 or greater than 23:59:59.9999999 hours to the SQL `TIME` will result in overflow exceptions. For more information, see [System.TimeSpan Methods](../../../../../../docs/framework/data/adonet/sql/linq/system-timespan-methods.md). In Microsoft SQL Server 2000 and SQL Server 2005, you cannot map database fields to . However, operations on are supported because values can be returned from subtraction or introduced into an expression as a literal or bound variable. ## Binary Mapping - There are many SQL Server types that can map to the CLR type . The following table shows the SQL Server types that cause O/R Designer and SQLMetal to define a CLR type when building an object model or external mapping file based on your database. + There are many SQL Server types that can map to the CLR type . The following table shows the SQL Server types that cause O/R Designer and SQLMetal to define a CLR type when building an object model or external mapping file based on your database. |SQL Server Type|Default CLR Type mapping used by O/R Designer and SQLMetal| |---------------------|-----------------------------------------------------------------| -|`BINARY(50)`|| -|`VARBINARY(50)`|| -|`VARBINARY(MAX)`|| -|`VARBINARY(MAX)` with the `FILESTREAM` attribute|| -|`IMAGE`|| -|`TIMESTAMP`|| +|`BINARY(50)`|| +|`VARBINARY(50)`|| +|`VARBINARY(MAX)`|| +|`VARBINARY(MAX)` with the `FILESTREAM` attribute|| +|`IMAGE`|| +|`TIMESTAMP`|| - The next table shows the default type mappings used by the method to define which type of SQL columns are created to map to the CLR types defined in your object model or external mapping file. + The next table shows the default type mappings used by the method to define which type of SQL columns are created to map to the CLR types defined in your object model or external mapping file. -|CLR Type|Default SQL Server Type used by | +|CLR Type|Default SQL Server Type used by | |--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -||`VARBINARY(MAX)`| -||`VARBINARY(MAX)`| -||`VARBINARY(MAX)`| +||`VARBINARY(MAX)`| +||`VARBINARY(MAX)`| +||`VARBINARY(MAX)`| There are many other binary mappings you can choose, but some may result in overflow or data loss exceptions while translating to or from the database. For more information, see the [Type Mapping Run Time Behavior Matrix](#BehaviorMatrix). ### SQL Server FILESTREAM The `FILESTREAM` attribute for `VARBINARY(MAX)` columns is available starting with Microsoft SQL Server 2008; you can map to it with LINQ to SQL starting with the .NET Framework version 3.5 SP1. - Although you can map `VARBINARY(MAX)` columns with the `FILESTREAM` attribute to objects, the method is unable to automatically create columns with the `FILESTREAM` attribute. For more information about `FILESTREAM`, see [FILESTREAM Overview](http://go.microsoft.com/fwlink/?LinkId=115291) on Microsoft SQL Server Books Online. + Although you can map `VARBINARY(MAX)` columns with the `FILESTREAM` attribute to objects, the method is unable to automatically create columns with the `FILESTREAM` attribute. For more information about `FILESTREAM`, see [FILESTREAM Overview](http://go.microsoft.com/fwlink/?LinkId=115291) on Microsoft SQL Server Books Online. ### Binary Serialization @@ -248,15 +248,15 @@ In LINQ to SQL, the data model of a relational database maps to an object model |SQL Server Type|Default CLR Type mapping used by O/R Designer and SQLMetal| |---------------------|-----------------------------------------------------------------| -|`UNIQUEIDENTIFIER`|| -|`SQL_VARIANT`|| +|`UNIQUEIDENTIFIER`|| +|`SQL_VARIANT`|| - The next table shows the default type mappings used by the method to define which type of SQL columns are created to map to the CLR types defined in your object model or external mapping file. + The next table shows the default type mappings used by the method to define which type of SQL columns are created to map to the CLR types defined in your object model or external mapping file. -|CLR Type|Default SQL Server Type used by | +|CLR Type|Default SQL Server Type used by | |--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -||`UNIQUEIDENTIFIER`| -||`SQL_VARIANT`| +||`UNIQUEIDENTIFIER`| +||`SQL_VARIANT`| LINQ to SQL does not support any other type mappings for these miscellaneous types. For more information, see the [Type Mapping Run Time Behavior Matrix](#BehaviorMatrix). diff --git a/docs/framework/data/adonet/sql/linq/sql-clr-type-mismatches.md b/docs/framework/data/adonet/sql/linq/sql-clr-type-mismatches.md index e23ce74e0c2a7..a00cfa8caf09f 100644 --- a/docs/framework/data/adonet/sql/linq/sql-clr-type-mismatches.md +++ b/docs/framework/data/adonet/sql/linq/sql-clr-type-mismatches.md @@ -25,7 +25,7 @@ manager: "jhubbard" Select DateOfBirth From Customer Where CustomerId = @id ``` - Before the query can be executed on SQL Server, the value for the Transact-SQL parameter must be specified. In this example, the `id` parameter value must first be translated from a CLR type to a SQL Server `INT` type so that the database can understand what the value is. Then to retrieve the results, the SQL Server `DateOfBirth` column must be translated from a SQL Server `DATETIME` type to a CLR type for use in the object model. In this example, the types in the CLR object model and SQL Server database have natural mappings. But, this is not always the case. + Before the query can be executed on SQL Server, the value for the Transact-SQL parameter must be specified. In this example, the `id` parameter value must first be translated from a CLR type to a SQL Server `INT` type so that the database can understand what the value is. Then to retrieve the results, the SQL Server `DateOfBirth` column must be translated from a SQL Server `DATETIME` type to a CLR type for use in the object model. In this example, the types in the CLR object model and SQL Server database have natural mappings. But, this is not always the case. ### Missing Counterparts The following types do not have reasonable counterparts. @@ -36,18 +36,18 @@ Select DateOfBirth From Customer Where CustomerId = @id - **Boolean**. These types can be mapped to a bit or larger numeric or string. A literal can be mapped to an expression that evaluates to the same value (for example, `1=1` in SQL for `True` in CLS). - - **TimeSpan**. This type represents the difference between two `DateTime` values and does not correspond to the `timestamp` of SQL Server. The CLR may also map to the SQL Server `TIME` type in some cases. The SQL Server `TIME` type was only intended to represent positive values less than 24 hours. The CLR has a much larger range. + - **TimeSpan**. This type represents the difference between two `DateTime` values and does not correspond to the `timestamp` of SQL Server. The CLR may also map to the SQL Server `TIME` type in some cases. The SQL Server `TIME` type was only intended to represent positive values less than 24 hours. The CLR has a much larger range. > [!NOTE] > SQL Server-specific [!INCLUDE[dnprdnshort](../../../../../../includes/dnprdnshort-md.md)] types in are not included in this comparison. - Mismatches in SQL Server: - - **Fixed length character types**. Transact-SQL distinguishes between Unicode and non-Unicode categories and has three distinct types in each category: fixed length `nchar`/`char`, variable length `nvarchar`/`varchar`, and larger-sized `ntext`/`text`. The fixed length character types could be mapped to the CLR type for retrieving characters, but they do not really correspond to the same type in conversions and behavior. + - **Fixed length character types**. Transact-SQL distinguishes between Unicode and non-Unicode categories and has three distinct types in each category: fixed length `nchar`/`char`, variable length `nvarchar`/`varchar`, and larger-sized `ntext`/`text`. The fixed length character types could be mapped to the CLR type for retrieving characters, but they do not really correspond to the same type in conversions and behavior. - **Bit**. Although the `bit` domain has the same number of values as `Nullable`, the two are different types. `Bit` takes values `1` and `0` instead of `true`/`false`, and cannot be used as an equivalent to Boolean expressions. - - **Timestamp**. Unlike the CLR type, the SQL Server `TIMESTAMP` type represents an 8-byte number generated by the database that is unique for each update and is not based on the difference between values. + - **Timestamp**. Unlike the CLR type, the SQL Server `TIMESTAMP` type represents an 8-byte number generated by the database that is unique for each update and is not based on the difference between values. - **Money** and **SmallMoney**. These types can be mapped to but are basically different types and are treated as such by server-based functions and conversions. @@ -205,7 +205,7 @@ Where Col1 = Col2 [!code-csharp[DLinqMismatch#6](../../../../../../samples/snippets/csharp/VS_Snippets_Data/DLinqMismatch/cs/Program.cs#6)] [!code-vb[DLinqMismatch#6](../../../../../../samples/snippets/visualbasic/VS_Snippets_Data/DLinqMismatch/vb/Module1.vb#6)] -- Operators/ functions applied to fixed length character type arguments in SQL have significantly different semantics than the same operators/functions applied to the CLR . This could also be viewed as an extension of the missing counterpart problem discussed in the section about types. +- Operators/ functions applied to fixed length character type arguments in SQL have significantly different semantics than the same operators/functions applied to the CLR . This could also be viewed as an extension of the missing counterpart problem discussed in the section about types. ``` create table T4 ( diff --git a/docs/framework/data/adonet/sql/linq/system-datetime-methods.md b/docs/framework/data/adonet/sql/linq/system-datetime-methods.md index 0ca231334772c..b18d8f0b16de0 100644 --- a/docs/framework/data/adonet/sql/linq/system-datetime-methods.md +++ b/docs/framework/data/adonet/sql/linq/system-datetime-methods.md @@ -19,7 +19,7 @@ manager: "jhubbard" The following LINQ to SQL-supported methods, operators, and properties are available to use in LINQ to SQL queries. When a method, operator or property is unsupported, LINQ to SQL cannot translate the member for execution on the SQL Server. You may use these members in your code, however, they must be evaluated before the query is translated to Transact-SQL or after the results have been retrieved from the database. ## Supported System.DateTime Members - Once mapped in the object model or external mapping file, LINQ to SQL allows you to call the following members inside LINQ to SQL queries. + Once mapped in the object model or external mapping file, LINQ to SQL allows you to call the following members inside LINQ to SQL queries. |Supported Methods|Supported Operators|Supported Properties| |------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| @@ -62,7 +62,7 @@ The following LINQ to SQL-supported methods, operators, and properties are avail `DATEDIFF({DatePart}, @dateTime1, @dateTime2)` ## SQLMethods Date and Time Methods - In addition to the methods offered by the structure, LINQ to SQL offers the methods listed in the following table from the class for working with date and time. + In addition to the methods offered by the structure, LINQ to SQL offers the methods listed in the following table from the class for working with date and time. |||| |-|-|-| diff --git a/docs/framework/data/adonet/sql/linq/system-datetimeoffset-methods.md b/docs/framework/data/adonet/sql/linq/system-datetimeoffset-methods.md index ad282eaaf9057..5511fcafbd8d7 100644 --- a/docs/framework/data/adonet/sql/linq/system-datetimeoffset-methods.md +++ b/docs/framework/data/adonet/sql/linq/system-datetimeoffset-methods.md @@ -16,15 +16,15 @@ ms.author: "jhubbard" manager: "jhubbard" --- # System.DateTimeOffset Methods -Once mapped in the object model or external mapping file, LINQ to SQL allows you to call most of the methods, operators, and properties from within your LINQ to SQL queries. +Once mapped in the object model or external mapping file, LINQ to SQL allows you to call most of the methods, operators, and properties from within your LINQ to SQL queries. - The only methods not supported are those inherited from that do not make sense in the context of LINQ to SQL queries, such as: `Finalize`, `GetHashCode`, `GetType`, and `MemberwiseClone`. These methods are not supported because LINQ to SQL cannot translate them for execution on the SQL Server. + The only methods not supported are those inherited from that do not make sense in the context of LINQ to SQL queries, such as: `Finalize`, `GetHashCode`, `GetType`, and `MemberwiseClone`. These methods are not supported because LINQ to SQL cannot translate them for execution on the SQL Server. > [!NOTE] -> The common language runtime (CLR) structure, and the ability to map it to a SQL `DATETIMEOFFSET` column with LINQ to SQL, requires the .NET Framework 3.5 SP1 or beyond. The SQL `DATETIMEOFFSET` column is only available in Microsoft SQL Server 2008 and beyond. +> The common language runtime (CLR) structure, and the ability to map it to a SQL `DATETIMEOFFSET` column with LINQ to SQL, requires the .NET Framework 3.5 SP1 or beyond. The SQL `DATETIMEOFFSET` column is only available in Microsoft SQL Server 2008 and beyond. ## SQLMethods Date and Time Methods - In addition to the methods offered by the structure, LINQ to SQL offers the methods listed in the following table from the class for working with date and time. + In addition to the methods offered by the structure, LINQ to SQL offers the methods listed in the following table from the class for working with date and time. |||| |-|-|-| diff --git a/docs/framework/data/adonet/sql/linq/system-math-methods.md b/docs/framework/data/adonet/sql/linq/system-math-methods.md index 93d0991f81d55..9d7896cb28c08 100644 --- a/docs/framework/data/adonet/sql/linq/system-math-methods.md +++ b/docs/framework/data/adonet/sql/linq/system-math-methods.md @@ -18,11 +18,11 @@ manager: "jhubbard" # System.Math Methods [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] does not support the following methods. -- +- -- +- -- +- ## Differences from .NET The .NET Framework has different rounding semantics from SQL Server. The method in the .NET Framework performs *Banker's rounding*, where numbers that ends in .5 round to the nearest even digit instead of to the next higher digit. For example, 2.5 rounds to 2, while 3.5 rounds to 4. (This technique helps avoid systematic bias toward higher values in large data transactions.) diff --git a/docs/framework/data/adonet/sql/linq/system-object-methods.md b/docs/framework/data/adonet/sql/linq/system-object-methods.md index f0418b176e8d9..5d085b6514733 100644 --- a/docs/framework/data/adonet/sql/linq/system-object-methods.md +++ b/docs/framework/data/adonet/sql/linq/system-object-methods.md @@ -20,19 +20,19 @@ manager: "jhubbard" ||| |-|-| -||| -||| +||| +||| [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] does not support the following methods. ||| |-|-| -||| -||| -| for binary types such as `BINARY`, `VARBINARY`, `IMAGE`, and `TIMESTAMP`.|| +||| +||| +| for binary types such as `BINARY`, `VARBINARY`, `IMAGE`, and `TIMESTAMP`.|| ## Differences from .NET - The output of for double uses SQL `CONVERT`(NVARCHAR(30), @x, 2) on SQL. SQL always uses 16 digits and scientific notation in this case (for example, "0.000000000000000e+000" for 0). As a result, conversion does not produce the same string as in the .NET Framework. + The output of for double uses SQL `CONVERT`(NVARCHAR(30), @x, 2) on SQL. SQL always uses 16 digits and scientific notation in this case (for example, "0.000000000000000e+000" for 0). As a result, conversion does not produce the same string as in the .NET Framework. ## See Also [Data Types and Functions](../../../../../../docs/framework/data/adonet/sql/linq/data-types-and-functions.md) diff --git a/docs/framework/data/adonet/sql/linq/system-string-methods.md b/docs/framework/data/adonet/sql/linq/system-string-methods.md index eb6853b17acdc..f1250d9bd9013 100644 --- a/docs/framework/data/adonet/sql/linq/system-string-methods.md +++ b/docs/framework/data/adonet/sql/linq/system-string-methods.md @@ -29,27 +29,27 @@ manager: "jhubbard" |Unsupported System.String Static Methods| |----------------------------------------------| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| ## Unsupported System.String Non-static Methods |Unsupported System.String Non-static Methods| |---------------------------------------------------| -|| -|| -|| -|| -|| -|| +|| +|| +|| +|| +|| +|| ## Differences from .NET diff --git a/docs/framework/data/adonet/sql/linq/system-timespan-methods.md b/docs/framework/data/adonet/sql/linq/system-timespan-methods.md index 6b18f43857eff..ec57406101f98 100644 --- a/docs/framework/data/adonet/sql/linq/system-timespan-methods.md +++ b/docs/framework/data/adonet/sql/linq/system-timespan-methods.md @@ -16,15 +16,15 @@ ms.author: "jhubbard" manager: "jhubbard" --- # System.TimeSpan Methods -Member support for greatly depends on the versions of the .NET Framework and Microsoft SQL Server that you are using. +Member support for greatly depends on the versions of the .NET Framework and Microsoft SQL Server that you are using. When a method, operator, or property is unsupported; it means that LINQ to SQL cannot translate the member for execution on the SQL Server. You may still be able to use these members in your code. However, they must be evaluated before the query is translated to Transact-SQL or after the results have been retrieved from the database. ## Previous Limitations - When using LINQ to SQL with versions of the .NET Framework prior to .NET Framework 3.5 SP1, you cannot map SQL Server database fields to . However, operations on are supported because values can be returned from subtraction or introduced into an expression as a literal or bound variable. + When using LINQ to SQL with versions of the .NET Framework prior to .NET Framework 3.5 SP1, you cannot map SQL Server database fields to . However, operations on are supported because values can be returned from subtraction or introduced into an expression as a literal or bound variable. ## Supported System.TimeSpan Method Support - The following LINQ to SQL-supported methods, operators, and properties are available for you to use in your LINQ to SQL queries. Once mapped in the object model or external mapping file, LINQ to SQL allows you to call many of the members inside your LINQ to SQL queries. + The following LINQ to SQL-supported methods, operators, and properties are available for you to use in your LINQ to SQL queries. Once mapped in the object model or external mapping file, LINQ to SQL allows you to call many of the members inside your LINQ to SQL queries. |Supported Methods|Supported Operators|Supported Properties| |------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| @@ -36,10 +36,10 @@ Member support for greatly depen |||| > [!NOTE] -> The ability to map to a SQL `TIME` column with LINQ to SQL requires the .NET Framework 3.5 SP1 and beyond. The SQL `TIME` data type is only available in Microsoft SQL Server 2008 and beyond. +> The ability to map to a SQL `TIME` column with LINQ to SQL requires the .NET Framework 3.5 SP1 and beyond. The SQL `TIME` data type is only available in Microsoft SQL Server 2008 and beyond. ### Addition and Subtraction - Although the CLR type does support addition and subtraction, the SQL `TIME` type does not. Because of this, your LINQ to SQL queries will generate errors if they attempt addition and subtraction when they are mapped to the SQL `TIME` type. You can find other considerations for working with SQL date and time types in [SQL-CLR Type Mapping](../../../../../../docs/framework/data/adonet/sql/linq/sql-clr-type-mapping.md). + Although the CLR type does support addition and subtraction, the SQL `TIME` type does not. Because of this, your LINQ to SQL queries will generate errors if they attempt addition and subtraction when they are mapped to the SQL `TIME` type. You can find other considerations for working with SQL date and time types in [SQL-CLR Type Mapping](../../../../../../docs/framework/data/adonet/sql/linq/sql-clr-type-mapping.md). ## See Also [Query Concepts](../../../../../../docs/framework/data/adonet/sql/linq/query-concepts.md) diff --git a/docs/framework/data/adonet/sql/linq/unsupported-functionality.md b/docs/framework/data/adonet/sql/linq/unsupported-functionality.md index 9939b1086ac6d..32170de297693 100644 --- a/docs/framework/data/adonet/sql/linq/unsupported-functionality.md +++ b/docs/framework/data/adonet/sql/linq/unsupported-functionality.md @@ -22,7 +22,7 @@ In LINQ to SQL, the following SQL functionality cannot be exposed through transl - `LIKE` - Although `LIKE` is not supported through direct translation, similar functionality exists in the class. For more information, see . + Although `LIKE` is not supported through direct translation, similar functionality exists in the class. For more information, see . - `DATEDIFF` diff --git a/docs/framework/data/adonet/sqlclient-streaming-support.md b/docs/framework/data/adonet/sqlclient-streaming-support.md index bc9439e73dd48..a16afc53ac7ff 100644 --- a/docs/framework/data/adonet/sqlclient-streaming-support.md +++ b/docs/framework/data/adonet/sqlclient-streaming-support.md @@ -34,7 +34,7 @@ Streaming support between [!INCLUDE[ssNoVersion](../../../../includes/ssnoversio 1. -2. +2. 3. diff --git a/docs/framework/data/transactions/security-trust-levels-in-accessing-resources.md b/docs/framework/data/transactions/security-trust-levels-in-accessing-resources.md index 515d5d6b0148f..d687b5ee73592 100644 --- a/docs/framework/data/transactions/security-trust-levels-in-accessing-resources.md +++ b/docs/framework/data/transactions/security-trust-levels-in-accessing-resources.md @@ -50,7 +50,7 @@ This topic discusses how access is restricted on the types of resources that +- - diff --git a/docs/framework/data/wcf/linq-considerations-wcf-data-services.md b/docs/framework/data/wcf/linq-considerations-wcf-data-services.md index 95b480051e792..6ae386193b06e 100644 --- a/docs/framework/data/wcf/linq-considerations-wcf-data-services.md +++ b/docs/framework/data/wcf/linq-considerations-wcf-data-services.md @@ -198,7 +198,7 @@ http://localhost:12345/Northwind.svc/Orders?Orderby=ShippedDate&?filter=Freight ||`int second(DateTime p0)`| ||`int year(DateTime p0)`| - 1The equivalent date and time properties of , as well as the method in Visual Basic are also supported. + 1The equivalent date and time properties of , as well as the method in Visual Basic are also supported. | Member|Supported [!INCLUDE[ssODataShort](../../../../includes/ssodatashort-md.md)] Function| |---------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------| diff --git a/docs/framework/data/wcf/streaming-provider-wcf-data-services.md b/docs/framework/data/wcf/streaming-provider-wcf-data-services.md index b28775f05beef..f4dfb30b9d6fa 100644 --- a/docs/framework/data/wcf/streaming-provider-wcf-data-services.md +++ b/docs/framework/data/wcf/streaming-provider-wcf-data-services.md @@ -88,7 +88,7 @@ A data service can expose large object binary data. This binary data might repre > [!NOTE] -> You must use a transfer mode to ensure that the binary data in both the request and response messages are streamed and not buffered by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. +> You must use a transfer mode to ensure that the binary data in both the request and response messages are streamed and not buffered by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. For more information, see [Streaming Message Transfer](../../../../docs/framework/wcf/feature-details/streaming-message-transfer.md) and [Transport Quotas](../../../../docs/framework/wcf/feature-details/transport-quotas.md). diff --git a/docs/framework/debug-trace-profile/asynchronousthreadabort-mda.md b/docs/framework/debug-trace-profile/asynchronousthreadabort-mda.md index c0de33ab4210c..6e58e0a4c092b 100644 --- a/docs/framework/debug-trace-profile/asynchronousthreadabort-mda.md +++ b/docs/framework/debug-trace-profile/asynchronousthreadabort-mda.md @@ -37,7 +37,7 @@ The `asynchronousThreadAbort` managed debugging assistant (MDA) is activated whe Symptoms can vary widely due to the randomness inherent to the problem. ## Cause - Code in one thread called the method on a target thread to introduce an asynchronous thread abort. The thread abort is asynchronous because the code that makes the call to is running on a different thread than the target of the abort operation. Synchronous thread aborts should not cause a problem because the thread performing the should have done so only at a safe checkpoint where application state is consistent. + Code in one thread called the method on a target thread to introduce an asynchronous thread abort. The thread abort is asynchronous because the code that makes the call to is running on a different thread than the target of the abort operation. Synchronous thread aborts should not cause a problem because the thread performing the should have done so only at a safe checkpoint where application state is consistent. Asynchronous thread aborts present a problem because they are processed at unpredictable points in the target thread's execution. To avoid this, code written to run on a thread that might be aborted in this manner would need to handle a at almost every line of code, taking care to put application data back into a consistent state. It is not realistic to expect code to be written with this problem in mind or to write code that protects against all possible circumstances. diff --git a/docs/framework/debug-trace-profile/bindingfailure-mda.md b/docs/framework/debug-trace-profile/bindingfailure-mda.md index 5fb5d86e280b3..c2941210fdb9c 100644 --- a/docs/framework/debug-trace-profile/bindingfailure-mda.md +++ b/docs/framework/debug-trace-profile/bindingfailure-mda.md @@ -31,7 +31,7 @@ manager: "wpickett" The `bindingFailure` managed debugging assistant (MDA) is activated when an assembly fails to load. ## Symptoms - Code has attempted to load an assembly using a static reference or one of the loader methods, such as or . The assembly is not loaded and a or exception is thrown. + Code has attempted to load an assembly using a static reference or one of the loader methods, such as or . The assembly is not loaded and a or exception is thrown. ## Cause A binding failure occurs when the runtime is unable to load an assembly. A binding failure might be the result of one of the following situations: diff --git a/docs/framework/debug-trace-profile/code-contracts.md b/docs/framework/debug-trace-profile/code-contracts.md index c8e35e4126772..5129edc21aa2f 100644 --- a/docs/framework/debug-trace-profile/code-contracts.md +++ b/docs/framework/debug-trace-profile/code-contracts.md @@ -44,7 +44,7 @@ Code contracts provide a way to specify preconditions, postconditions, and objec For tools and detailed instructions for using code contracts, see [Code Contracts](http://go.microsoft.com/fwlink/?LinkId=152461) on the MSDN DevLabs Web site. ## Preconditions - You can express preconditions by using the method. Preconditions specify state when a method is invoked. They are generally used to specify valid parameter values. All members that are mentioned in preconditions must be at least as accessible as the method itself; otherwise, the precondition might not be understood by all callers of a method. The condition must have no side-effects. The run-time behavior of failed preconditions is determined by the runtime analyzer. + You can express preconditions by using the method. Preconditions specify state when a method is invoked. They are generally used to specify valid parameter values. All members that are mentioned in preconditions must be at least as accessible as the method itself; otherwise, the precondition might not be understood by all callers of a method. The condition must have no side-effects. The run-time behavior of failed preconditions is determined by the runtime analyzer. For example, the following precondition expresses that parameter `x` must be non-null. @@ -61,7 +61,7 @@ Code contracts provide a way to specify preconditions, postconditions, and objec - The entire set of such statements is followed by an explicit method call, such as a call to the , , , or method. - When `if`-`then`-`throw` statements appear in this form, the tools recognize them as legacy `requires` statements. If no other contracts follow the `if`-`then`-`throw` sequence, end the code with the method. + When `if`-`then`-`throw` statements appear in this form, the tools recognize them as legacy `requires` statements. If no other contracts follow the `if`-`then`-`throw` sequence, end the code with the method. ``` if ( x == null ) throw new ... @@ -81,7 +81,7 @@ Contract.EndContractBlock(); // All previous "if" checks are preconditions `Contract.Ensures( this.F > 0 );` ### Exceptional Postconditions - Exceptional postconditions are postconditions that should be `true` when a particular exception is thrown by a method. You can specify these postconditions by using the method, as the following example shows. + Exceptional postconditions are postconditions that should be `true` when a particular exception is thrown by a method. You can specify these postconditions by using the method, as the following example shows. `Contract.EnsuresOnThrow( this.F > 0 );` @@ -187,7 +187,7 @@ Contract.Invariant(this.x > this.y); - Any method whose fully qualified name begins with "System.Diagnostics.Contracts.Contract", "System.String", "System.IO.Path", or "System.Type". -- Any invoked delegate, provided that the delegate type itself is attributed with the . The delegate types and are considered pure. +- Any invoked delegate, provided that the delegate type itself is attributed with the . The delegate types and are considered pure. ### Visibility diff --git a/docs/framework/debug-trace-profile/dangerousthreadingapi-mda.md b/docs/framework/debug-trace-profile/dangerousthreadingapi-mda.md index 0b24bbb09fe0b..aaf64cf64fad0 100644 --- a/docs/framework/debug-trace-profile/dangerousthreadingapi-mda.md +++ b/docs/framework/debug-trace-profile/dangerousthreadingapi-mda.md @@ -29,7 +29,7 @@ ms.author: "mairaw" manager: "wpickett" --- # dangerousThreadingAPI MDA -The `dangerousThreadingAPI` managed debugging assistant (MDA) is activated when the method is called on a thread other than the current thread. +The `dangerousThreadingAPI` managed debugging assistant (MDA) is activated when the method is called on a thread other than the current thread. ## Symptoms An application is unresponsive or hangs indefinitely. System or application data might be left in an unpredictable state temporarily or even after an application has been shut down. Some operations are not completing as expected. diff --git a/docs/framework/debug-trace-profile/datetimeinvalidlocalformat-mda.md b/docs/framework/debug-trace-profile/datetimeinvalidlocalformat-mda.md index 80e2587a6294c..b82926711d895 100644 --- a/docs/framework/debug-trace-profile/datetimeinvalidlocalformat-mda.md +++ b/docs/framework/debug-trace-profile/datetimeinvalidlocalformat-mda.md @@ -42,7 +42,7 @@ Serialize(myDateTime.ToString("yyyy-MM-dd'T'HH:mm:ss.fffffffzzz")); ``` ### Cause - The 'z' format for the method includes the local time zone offset, for example, "+10:00" for Sydney time. As such, it will only produce a meaningful result if the value of the is local. If the value is UTC time, includes the local time zone offset, but it does not display or adjust the time zone specifier. + The 'z' format for the method includes the local time zone offset, for example, "+10:00" for Sydney time. As such, it will only produce a meaningful result if the value of the is local. If the value is UTC time, includes the local time zone offset, but it does not display or adjust the time zone specifier. ### Resolution UTC instances should be formatted in a way that indicates that they are UTC. The recommended format for UTC times to use a 'Z' to denote UTC time: diff --git a/docs/framework/debug-trace-profile/enabling-jit-attach-debugging.md b/docs/framework/debug-trace-profile/enabling-jit-attach-debugging.md index 013553db7e0ba..ebda4b0b960fa 100644 --- a/docs/framework/debug-trace-profile/enabling-jit-attach-debugging.md +++ b/docs/framework/debug-trace-profile/enabling-jit-attach-debugging.md @@ -30,15 +30,15 @@ JIT-attach debugging is the phrase used to describe attaching a debugger to a pr - Unhandled exceptions (in both native and managed code). -- method or [RaiseFailFastException](http://go.microsoft.com/fwlink/?LinkId=182107) function (Windows 7 family). +- method or [RaiseFailFastException](http://go.microsoft.com/fwlink/?LinkId=182107) function (Windows 7 family). - Runtime fatal errors. JIT-attach debugging is also triggered by calls to the following methods and functions: -- method. +- method. -- method. +- method. - [DebugBreak](http://go.microsoft.com/fwlink/?LinkId=182106) function (Win32). diff --git a/docs/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code.md b/docs/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code.md index 4457343c5d4ac..784280220a6a0 100644 --- a/docs/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code.md +++ b/docs/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code.md @@ -88,13 +88,13 @@ The methods used most often for tracing are the methods for writing output to li ``` > [!NOTE] - > You can use **Assert** with both tracing and debugging. This example outputs the call stack to any listener in the **Listeners** collection. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code) and . + > You can use **Assert** with both tracing and debugging. This example outputs the call stack to any listener in the **Listeners** collection. For more information, see [Assertions in Managed Code](/visualstudio/debugger/assertions-in-managed-code) and . ## See Also - - - - + + + + [Tracing and Instrumenting Applications](../../../docs/framework/debug-trace-profile/tracing-and-instrumenting-applications.md) [How to: Create, Initialize and Configure Trace Switches](../../../docs/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches.md) [Trace Switches](../../../docs/framework/debug-trace-profile/trace-switches.md) diff --git a/docs/framework/debug-trace-profile/how-to-create-and-initialize-trace-listeners.md b/docs/framework/debug-trace-profile/how-to-create-and-initialize-trace-listeners.md index 5f6d2f7feb172..11070a8c8d2d9 100644 --- a/docs/framework/debug-trace-profile/how-to-create-and-initialize-trace-listeners.md +++ b/docs/framework/debug-trace-profile/how-to-create-and-initialize-trace-listeners.md @@ -27,7 +27,7 @@ ms.author: "mairaw" manager: "wpickett" --- # How to: Create and Initialize Trace Listeners -The and classes send messages to objects called listeners that receive and process these messages. One such listener, the , is automatically created and initialized when tracing or debugging is enabled. If you want or output to be directed to any additional sources, you must create and initialize additional trace listeners. +The and classes send messages to objects called listeners that receive and process these messages. One such listener, the , is automatically created and initialized when tracing or debugging is enabled. If you want or output to be directed to any additional sources, you must create and initialize additional trace listeners. The listeners you create should reflect your application's needs. For example, if you want a text record of all trace output, create a listener, which writes all output to a new text file when it is enabled. On the other hand, if you want to view output only during application execution, create a listener, which directs all output to a console window. The can direct trace output to an event log. For more information, see [Trace Listeners](../../../docs/framework/debug-trace-profile/trace-listeners.md). diff --git a/docs/framework/debug-trace-profile/how-to-create-and-initialize-trace-sources.md b/docs/framework/debug-trace-profile/how-to-create-and-initialize-trace-sources.md index 7c205fc16cc6b..dfc3ad2c19a1d 100644 --- a/docs/framework/debug-trace-profile/how-to-create-and-initialize-trace-sources.md +++ b/docs/framework/debug-trace-profile/how-to-create-and-initialize-trace-sources.md @@ -75,7 +75,7 @@ The class is used by applications to produ The configuration file initializes the settings for the trace source at the time the application is initialized. The application can dynamically change the properties set by the configuration file to override any settings specified by the user. For example, you might want to ensure that critical messages are always sent to a text file, regardless of the current configuration settings. The example code demonstrates how to override configuration file settings to ensure that critical messages are output to the trace listeners. - Changing the configuration file settings while the application is executing does not change the initial settings. To change the settings, you must either restart the application or programmatically refresh the application by using the method. + Changing the configuration file settings while the application is executing does not change the initial settings. To change the settings, you must either restart the application or programmatically refresh the application by using the method. ### To initialize trace sources, listeners, and filters without a configuration file diff --git a/docs/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches.md b/docs/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches.md index fa49d2b413832..0c5ad87935904 100644 --- a/docs/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches.md +++ b/docs/framework/debug-trace-profile/how-to-create-initialize-and-configure-trace-switches.md @@ -31,13 +31,13 @@ Trace switches enable you to enable, disable, and filter tracing output. ## Creating and initializing a trace switch - In order to use trace switches, you must first create them and place them in your code. There are two predefined classes from which you can create switch objects: the class and the class. You would use if you care only about whether or not a tracing message appears; you would use if you want to discriminate between levels of tracing. If you use a , you can define your own debugging messages and associate them with different trace levels. You can use both types of switches with either tracing or debugging. By default, a is disabled and a is set to level . Trace switches can be created and placed in any part of your code that might use them. + In order to use trace switches, you must first create them and place them in your code. There are two predefined classes from which you can create switch objects: the class and the class. You would use if you care only about whether or not a tracing message appears; you would use if you want to discriminate between levels of tracing. If you use a , you can define your own debugging messages and associate them with different trace levels. You can use both types of switches with either tracing or debugging. By default, a is disabled and a is set to level . Trace switches can be created and placed in any part of your code that might use them. Although you can set trace levels and other configuration options in code, we recommend that you use the configuration file to manage the state of your switches. This is because managing the configuration of your switches in the configuration system gives you greater flexibility — you can turn on and off various switches and change levels without recompiling your application. #### To create and initialize a trace switch -1. Define a switch as either type or type and set the name and description of the switch. +1. Define a switch as either type or type and set the name and description of the switch. 2. Configure your trace switch. For more information, see [Configuring trace switches](#configure). @@ -66,7 +66,7 @@ Trace switches enable you to enable, disable, and filter tracing output. In a deployed application, you enable trace code by reconfiguring switch objects when your application is not running. Typically this involves turning the switch objects on and off or by changing the tracing levels, and then restarting your application. - When you create an instance of a switch, you also initialize it by specifying two arguments: a *displayName* argument and a *description* argument. The *displayName* argument of the constructor sets the property of the class instance. The *displayName* is the name that is used to configure the switch in the .config file, and the *description* argument should return a brief description of the switch and what messages it controls. + When you create an instance of a switch, you also initialize it by specifying two arguments: a *displayName* argument and a *description* argument. The *displayName* argument of the constructor sets the property of the class instance. The *displayName* is the name that is used to configure the switch in the .config file, and the *description* argument should return a brief description of the switch and what messages it controls. In addition to specifying the name of a switch to configure, you must also specify a value for the switch. This value is an Integer. For , a value of 0 corresponds to **Off**, and any nonzero value corresponds to **On**. For , 0,1,2,3, and 4 correspond **Off**, **Error**, **Warning**, **Info**, and **Verbose**, respectively. Any number greater than 4 is treated as **Verbose**, and any number less than zero is treated as **Off**. diff --git a/docs/framework/debug-trace-profile/how-to-use-tracesource-and-filters-with-trace-listeners.md b/docs/framework/debug-trace-profile/how-to-use-tracesource-and-filters-with-trace-listeners.md index 9f14c3a77347b..99918dd5e1e1b 100644 --- a/docs/framework/debug-trace-profile/how-to-use-tracesource-and-filters-with-trace-listeners.md +++ b/docs/framework/debug-trace-profile/how-to-use-tracesource-and-filters-with-trace-listeners.md @@ -108,7 +108,7 @@ One of the new features in the .NET Framework version 2.0 is an enhanced tracing ### To change the level at which a listener writes a trace message -1. The configuration file initializes the settings for the trace source at the time the application is initialized. To change those settings you must change the configuration file and restart the application or programmatically refresh the application using the method. The application can dynamically change the properties set by the configuration file to override any settings specified by the user. For example, you might want to assure that critical messages are always sent to a text file, regardless of the current configuration settings. +1. The configuration file initializes the settings for the trace source at the time the application is initialized. To change those settings you must change the configuration file and restart the application or programmatically refresh the application using the method. The application can dynamically change the properties set by the configuration file to override any settings specified by the user. For example, you might want to assure that critical messages are always sent to a text file, regardless of the current configuration settings. ``` using System; diff --git a/docs/framework/debug-trace-profile/illegalprepareconstrainedregion-mda.md b/docs/framework/debug-trace-profile/illegalprepareconstrainedregion-mda.md index 58d838e44d22b..d38781f6b3054 100644 --- a/docs/framework/debug-trace-profile/illegalprepareconstrainedregion-mda.md +++ b/docs/framework/debug-trace-profile/illegalprepareconstrainedregion-mda.md @@ -27,7 +27,7 @@ ms.author: "mairaw" manager: "wpickett" --- # illegalPrepareConstrainedRegion MDA -The `illegalPrepareConstrainedRegion` managed debugging assistant (MDA) is activated when a method call does not immediately precede the `try` statement of the exception handler. This restriction is at the MSIL level, so it is permissible to have non-code-generating source between the call and the `try`, such as comments. +The `illegalPrepareConstrainedRegion` managed debugging assistant (MDA) is activated when a method call does not immediately precede the `try` statement of the exception handler. This restriction is at the MSIL level, so it is permissible to have non-code-generating source between the call and the `try`, such as comments. ## Symptoms A constrained execution region (CER) that is never treated as such, but as a simple exception handling block (`finally` or `catch`). As a consequence, the region does not run in the event of an out-of-memory condition or a thread abort. diff --git a/docs/framework/debug-trace-profile/invalidapartmentstatechange-mda.md b/docs/framework/debug-trace-profile/invalidapartmentstatechange-mda.md index 9f95f7595b627..7029eee5c986e 100644 --- a/docs/framework/debug-trace-profile/invalidapartmentstatechange-mda.md +++ b/docs/framework/debug-trace-profile/invalidapartmentstatechange-mda.md @@ -44,7 +44,7 @@ The `invalidApartmentStateChange` managed debugging assistant (MDS) is activated ## Cause -- The thread was previously initialized to a different COM apartment state. Note that the apartment state of a thread can be set either explicitly or implicitly. The explicit operations include the property and the and methods. A thread created using the method is implicitly set to unless is called before the thread is started. The main thread of the application is also implicitly initialized to unless the attribute is specified on the main method. +- The thread was previously initialized to a different COM apartment state. Note that the apartment state of a thread can be set either explicitly or implicitly. The explicit operations include the property and the and methods. A thread created using the method is implicitly set to unless is called before the thread is started. The main thread of the application is also implicitly initialized to unless the attribute is specified on the main method. - The `CoUninitialize` method (or the `CoInitializeEx` method) with a different concurrency model is called on the thread. diff --git a/docs/framework/debug-trace-profile/loadfromcontext-mda.md b/docs/framework/debug-trace-profile/loadfromcontext-mda.md index 2da2004f31d65..d0dfcc826b6eb 100644 --- a/docs/framework/debug-trace-profile/loadfromcontext-mda.md +++ b/docs/framework/debug-trace-profile/loadfromcontext-mda.md @@ -26,13 +26,13 @@ ms.author: "mairaw" manager: "wpickett" --- # loadFromContext MDA -The `loadFromContext` managed debugging assistant (MDA) is activated if an assembly is loaded into the `LoadFrom` context. This situation can occur as a result of calling or other similar methods. +The `loadFromContext` managed debugging assistant (MDA) is activated if an assembly is loaded into the `LoadFrom` context. This situation can occur as a result of calling or other similar methods. ## Symptoms The use of some loader methods can result in assemblies being loaded in the `LoadFrom` context. The use of this context can result in unexpected behavior for serialization, casting, and dependency resolution. In general, it is recommended that assemblies be loaded into the `Load` context to avoid these problems. It is difficult to determine which context an assembly has been loaded into without this MDA. ## Cause - Generally, an assembly was loaded into the `LoadFrom` context if it was loaded from a path outside the `Load` context, such as the global assembly cache or the property. + Generally, an assembly was loaded into the `LoadFrom` context if it was loaded from a path outside the `Load` context, such as the global assembly cache or the property. ## Resolution Configure applications such that calls are no longer needed. You can use the following techniques for doing so: @@ -43,7 +43,7 @@ The `loadFromContext` managed debugging assistant (MDA) is activated if an assem - Add a probing path to your application configuration (.config) file or to secondary application domains if dependent assemblies are in child directories relative to the executable. - In each case, the code can be changed to use the method. + In each case, the code can be changed to use the method. ## Effect on the Runtime The MDA does not have any effect on the CLR. It reports the context that was used as a result of a load request. diff --git a/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md b/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md index 38362a865c95d..4eadee34bfc9e 100644 --- a/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md +++ b/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md @@ -53,7 +53,7 @@ AllowOptimize=0 > In the .NET Framework version 2.0, the JIT compiler always generates tracking information regardless of the value for `GenerateTrackingInfo`; however, the `AllowOptimize` value still has an effect. When using the [Ngen.exe (Native Image Generator)](../../../docs/framework/tools/ngen-exe-native-image-generator.md) to precompile the native image without optimization, the .ini file must be present in the target folder with `AllowOptimize=0` when Ngen.exe executes. If you have precompiled an assembly without optimization, you must remove the precompiled code using the NGen.exe **/uninstall** option before rerunning Ngen.exe to precompile the code as optimized. If the .ini file is not present in the folder, by default Ngen.exe precompiles the code as optimized. > [!NOTE] -> The controls the settings for an assembly. **DebuggableAttribute** includes two fields that record the settings for whether the JIT compiler should optimize, and/or generate tracking information. In the .NET Framework version 2.0, the JIT compiler will always generate tracking information. +> The controls the settings for an assembly. **DebuggableAttribute** includes two fields that record the settings for whether the JIT compiler should optimize, and/or generate tracking information. In the .NET Framework version 2.0, the JIT compiler will always generate tracking information. > [!NOTE] > For a retail build, compilers do not set any **DebuggableAttribute**. The JIT-compiler default behavior is to generate the highest performance, hardest to debug machine code. Enabling JIT tracking lowers performance a little, and disabling optimization lowers performance a lot. diff --git a/docs/framework/debug-trace-profile/moduloobjecthashcode-mda.md b/docs/framework/debug-trace-profile/moduloobjecthashcode-mda.md index bac6f58ac4109..8e6896e358df2 100644 --- a/docs/framework/debug-trace-profile/moduloobjecthashcode-mda.md +++ b/docs/framework/debug-trace-profile/moduloobjecthashcode-mda.md @@ -48,7 +48,7 @@ The `moduloObjectHashcode` managed debugging assistant (MDA) changes the behavio The order of enumeration from a may change from one version of the runtime to another if the algorithm used to compute the hash codes for the key change. To test whether your program has taken a dependency on the order of enumeration of keys or values out of a hash table, you can enable this MDA. ## Resolution - Never use hash codes as a substitute for object identity. Implement the override of the method to not compare hash codes. + Never use hash codes as a substitute for object identity. Implement the override of the method to not compare hash codes. Do not create dependencies on the order of enumerations of keys or values in hash tables. @@ -70,6 +70,6 @@ The `moduloObjectHashcode` managed debugging assistant (MDA) changes the behavio ``` ## See Also - - + + [Diagnosing Errors with Managed Debugging Assistants](../../../docs/framework/debug-trace-profile/diagnosing-errors-with-managed-debugging-assistants.md) diff --git a/docs/framework/debug-trace-profile/overlappedfreeerror-mda.md b/docs/framework/debug-trace-profile/overlappedfreeerror-mda.md index f924bb1199e21..6137f4e828041 100644 --- a/docs/framework/debug-trace-profile/overlappedfreeerror-mda.md +++ b/docs/framework/debug-trace-profile/overlappedfreeerror-mda.md @@ -28,7 +28,7 @@ ms.author: "mairaw" manager: "wpickett" --- # overlappedFreeError MDA -The `overlappedFreeError` managed debugging assistant (MDA) is activated when the method is called before the overlapped operation has completed. +The `overlappedFreeError` managed debugging assistant (MDA) is activated when the method is called before the overlapped operation has completed. ## Symptoms Access violations or corruption of the garbage-collected heap. diff --git a/docs/framework/debug-trace-profile/performance-counters.md b/docs/framework/debug-trace-profile/performance-counters.md index 4439d8fa990ad..e63fcdbde18d4 100644 --- a/docs/framework/debug-trace-profile/performance-counters.md +++ b/docs/framework/debug-trace-profile/performance-counters.md @@ -131,7 +131,7 @@ This topic provides a list of performance counters you can find in the [Performa |**# Gen 0 Collections**|Displays the number of times the generation 0 objects (that is, the youngest, most recently allocated objects) are garbage collected since the application started.

Generation 0 garbage collection occurs when the available memory in generation 0 is not sufficient to satisfy an allocation request. This counter is incremented at the end of a generation 0 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 1 or 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| |**# Gen 1 Collections**|Displays the number of times the generation 1 objects are garbage collected since the application started.

The counter is incremented at the end of a generation 1 garbage collection. Higher generation garbage collections include all lower generation collections. This counter is explicitly incremented when a higher generation (generation 2) garbage collection occurs.

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| |**# Gen 2 Collections**|Displays the number of times the generation 2 objects are garbage collected since the application started. The counter is incremented at the end of a generation 2 garbage collection (also called a full garbage collection).

This counter displays the last observed value. The **_Global\_** counter value is not accurate and should be ignored.| -|**# Induced GC**|Displays the peak number of times garbage collection was performed because of an explicit call to . It is good practice to let the garbage collector tune the frequency of its collections.| +|**# Induced GC**|Displays the peak number of times garbage collection was performed because of an explicit call to . It is good practice to let the garbage collector tune the frequency of its collections.| |**# of Pinned Objects**|Displays the number of pinned objects encountered in the last garbage collection. A pinned object is an object that the garbage collector cannot move in memory. This counter tracks pinned objects only in the heaps that are garbage collected. For example, a generation 0 garbage collection causes enumeration of pinned objects only in the generation 0 heap.| |**# of Sink Blocks in use**|Displays the current number of synchronization blocks in use. Synchronization blocks are per-object data structures allocated for storing synchronization information. They hold weak references to managed objects and must be scanned by the garbage collector. Synchronization blocks are not limited to storing synchronization information; they can also store COM interop metadata. This counter indicates performance problems with heavy use of synchronization primitives.| |**# Total committed Bytes**|Displays the amount of virtual memory, in bytes, currently committed by the garbage collector. Committed memory is the physical memory for which space has been reserved in the disk paging file.| diff --git a/docs/framework/debug-trace-profile/raceonrcwcleanup-mda.md b/docs/framework/debug-trace-profile/raceonrcwcleanup-mda.md index f2378db69d747..3492a6a3b8597 100644 --- a/docs/framework/debug-trace-profile/raceonrcwcleanup-mda.md +++ b/docs/framework/debug-trace-profile/raceonrcwcleanup-mda.md @@ -28,7 +28,7 @@ ms.author: "mairaw" manager: "wpickett" --- # raceOnRCWCleanup MDA -The `raceOnRCWCleanup` managed debugging assistant (MDA) is activated when the common language runtime (CLR) detects that a [Runtime Callable Wrapper](../../../docs/framework/interop/runtime-callable-wrapper.md) (RCW) is in use when a call to release it is made using a command such as the method. +The `raceOnRCWCleanup` managed debugging assistant (MDA) is activated when the common language runtime (CLR) detects that a [Runtime Callable Wrapper](../../../docs/framework/interop/runtime-callable-wrapper.md) (RCW) is in use when a call to release it is made using a command such as the method. ## Symptoms Access violations or memory corruption during or after freeing an RCW using or a similar method. diff --git a/docs/framework/debug-trace-profile/runtime-profiling.md b/docs/framework/debug-trace-profile/runtime-profiling.md index fe3b4df10e03e..57ab374e3d3dc 100644 --- a/docs/framework/debug-trace-profile/runtime-profiling.md +++ b/docs/framework/debug-trace-profile/runtime-profiling.md @@ -70,10 +70,10 @@ Profiling is a method of gathering performance data in any development or deploy |Class|Description| |-----------|-----------------| -||Represents a Windows NT performance counter component. Use this class to read existing predefined or custom counters and publish (write) performance data to custom counters.| -||Provides several methods for interacting with counters and categories of counters on the computer.| -||Specifies an installer for the `PerformanceCounter` component.| -||Specifies the formula to calculate the `NextValue` method for a `PerformanceCounter`.| +||Represents a Windows NT performance counter component. Use this class to read existing predefined or custom counters and publish (write) performance data to custom counters.| +||Provides several methods for interacting with counters and categories of counters on the computer.| +||Specifies an installer for the `PerformanceCounter` component.| +||Specifies the formula to calculate the `NextValue` method for a `PerformanceCounter`.| ## See Also [Performance Counters](../../../docs/framework/debug-trace-profile/performance-counters.md) diff --git a/docs/framework/debug-trace-profile/trace-switches.md b/docs/framework/debug-trace-profile/trace-switches.md index bd359ff6344cc..9314ce37479ca 100644 --- a/docs/framework/debug-trace-profile/trace-switches.md +++ b/docs/framework/debug-trace-profile/trace-switches.md @@ -39,13 +39,13 @@ Trace switches enable you to enable, disable, and filter tracing output. They ar ## Trace Levels When you use **TraceSwitch**, there are additional considerations. A **TraceSwitch** object has four properties that return **Boolean** values indicating whether the switch is set to at least a particular level: -- +- -- +- -- +- -- +- Levels allow you to limit the amount of tracing information you receive to only that information needed to solve a problem. You specify the level of detail you want in your tracing output by setting and configuring trace switches to the appropriate trace level. You can receive error messages, warning messages, informational messages, verbose tracing messages, or no message at all. diff --git a/docs/framework/debug-trace-profile/tracing-and-instrumenting-applications.md b/docs/framework/debug-trace-profile/tracing-and-instrumenting-applications.md index 95525fcbc7003..49ed1c9c3fac0 100644 --- a/docs/framework/debug-trace-profile/tracing-and-instrumenting-applications.md +++ b/docs/framework/debug-trace-profile/tracing-and-instrumenting-applications.md @@ -29,7 +29,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Tracing and Instrumenting Applications -Tracing is a way for you to monitor the execution of your application while it is running. You can add tracing and debugging instrumentation to your .NET Framework application when you develop it, and you can use that instrumentation both while you are developing the application and after you have deployed it. You can use the , , and classes to record information about errors and application execution in logs, text files, or other devices for later analysis. +Tracing is a way for you to monitor the execution of your application while it is running. You can add tracing and debugging instrumentation to your .NET Framework application when you develop it, and you can use that instrumentation both while you are developing the application and after you have deployed it. You can use the , , and classes to record information about errors and application execution in logs, text files, or other devices for later analysis. The term *instrumentation* refers to an ability to monitor or measure the level of a product's performance and to diagnose errors. In programming, this means the ability of an application to incorporate: @@ -120,7 +120,7 @@ System.Diagnostics.Debug.WriteLine("Hello World!"); You must exercise special care when placing your trace statements for use during run time. You must consider what tracing information is likely to be needed in a deployed application, so that all likely tracing scenarios are adequately covered. Because applications that use tracing vary widely, however, there are no general guidelines for strategic placement of tracing. For more information on placing trace statements, see [How to: Add Trace Statements to Application Code](../../../docs/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code.md). ## Output from Tracing - Trace output is collected by objects called *listeners*. A listener is an object that receives trace output and writes it to an output device (usually a window, log, or text file). When a trace listener is created, it is typically added to the collection, allowing the listener to receive all trace output. + Trace output is collected by objects called *listeners*. A listener is an object that receives trace output and writes it to an output device (usually a window, log, or text file). When a trace listener is created, it is typically added to the collection, allowing the listener to receive all trace output. Tracing information is always written at least to the default output target, the . If for some reason you have deleted the without adding any other listeners to the collection, you will not receive any tracing messages. For more information, see [Trace Listeners](../../../docs/framework/debug-trace-profile/trace-listeners.md). diff --git a/docs/framework/deployment/best-practices-for-assembly-loading.md b/docs/framework/deployment/best-practices-for-assembly-loading.md index 0b91c21971654..60557794a3d7a 100644 --- a/docs/framework/deployment/best-practices-for-assembly-loading.md +++ b/docs/framework/deployment/best-practices-for-assembly-loading.md @@ -51,7 +51,7 @@ This article discusses ways to avoid problems of type identity that can lead to - The default load context contains assemblies found by probing the global assembly cache, the host assembly store if the runtime is hosted (for example, in SQL Server), and the and of the application domain. Most overloads of the method load assemblies into this context. -- The load-from context contains assemblies that are loaded from locations that are not searched by the loader. For example, add-ins might be installed in a directory that is not under the application path. , , and are examples of methods that load by path. +- The load-from context contains assemblies that are loaded from locations that are not searched by the loader. For example, add-ins might be installed in a directory that is not under the application path. , , and are examples of methods that load by path. - The reflection-only context contains assemblies loaded with the and methods. Code in this context cannot be executed, so it is not discussed here. For more information, see [How to: Load Assemblies into the Reflection-Only Context](../../../docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md). @@ -71,7 +71,7 @@ This article discusses ways to avoid problems of type identity that can lead to ### Load-From Context The load-from context lets you load an assembly from a path that is not under the application path, and therefore is not included in probing. It enables dependencies to be located and loaded from that path, because the path information is maintained by the context. In addition, assemblies in this context can use dependencies that are loaded into the default load context. - Loading assemblies by using the method, or one of the other methods that load by path, has the following disadvantages: + Loading assemblies by using the method, or one of the other methods that load by path, has the following disadvantages: - If an assembly with the same identity is already loaded, returns the loaded assembly even if a different path was specified. @@ -79,7 +79,7 @@ This article discusses ways to avoid problems of type identity that can lead to - If an assembly is loaded with , and the probing path includes an assembly with the same identity but in a different location, an , , or other unexpected behavior can occur. -- demands and , or , on the specified path. +- demands and , or , on the specified path. - If a native image exists for the assembly, it is not used. @@ -94,9 +94,9 @@ This article discusses ways to avoid problems of type identity that can lead to Loading assemblies without context has the following disadvantages: -- Other assemblies cannot bind to assemblies that are loaded without context, unless you handle the event. +- Other assemblies cannot bind to assemblies that are loaded without context, unless you handle the event. -- Dependencies are not loaded automatically. You can preload them without context, preload them into the default load context, or load them by handling the event. +- Dependencies are not loaded automatically. You can preload them without context, preload them into the default load context, or load them by handling the event. - Loading multiple assemblies with the same identity without context can cause type identity problems similar to those caused by loading assemblies with the same identity into multiple contexts. See [Avoid Loading an Assembly into Multiple Contexts](#avoid_loading_into_multiple_contexts). @@ -108,11 +108,11 @@ This article discusses ways to avoid problems of type identity that can lead to ## Avoid Binding on Partial Assembly Names - Partial name binding occurs when you specify only part of the assembly display name () when you load an assembly. For example, you might call the method with only the simple name of the assembly, omitting the version, culture, and public key token. Or you might call the method, which first calls the method and, if that fails to locate the assembly, searches the global assembly cache and loads the latest available version of the assembly. + Partial name binding occurs when you specify only part of the assembly display name () when you load an assembly. For example, you might call the method with only the simple name of the assembly, omitting the version, culture, and public key token. Or you might call the method, which first calls the method and, if that fails to locate the assembly, searches the global assembly cache and loads the latest available version of the assembly. Partial name binding can cause many problems, including the following: -- The method might load a different assembly with the same simple name. For example, two applications might install two completely different assemblies that both have the simple name `GraphicsLibrary` into the global assembly cache. +- The method might load a different assembly with the same simple name. For example, two applications might install two completely different assemblies that both have the simple name `GraphicsLibrary` into the global assembly cache. - The assembly that is actually loaded might not be backward-compatible. For example, not specifying the version might result in the loading of a much later version than the version your program was originally written to use. Changes in the later version might cause errors in your application. @@ -122,7 +122,7 @@ This article discusses ways to avoid problems of type identity that can lead to - Unexpected dependency loading can occur. It you load two assemblies that share a dependency, loading them with partial binding might result in one assembly using a component that it was not built or tested with. - Because of the problems it can cause, the method has been marked obsolete. We recommend that you use the method instead, and specify full assembly display names. See [Understand the Advantages and Disadvantages of Load Contexts](#load_contexts) and [Consider Switching to the Default Load Context](#switch_to_default). + Because of the problems it can cause, the method has been marked obsolete. We recommend that you use the method instead, and specify full assembly display names. See [Understand the Advantages and Disadvantages of Load Contexts](#load_contexts) and [Consider Switching to the Default Load Context](#switch_to_default). If you want to use the method because it makes assembly loading easy, consider that having your application fail with an error message that identifies the missing assembly is likely to provide a better user experience than automatically using an unknown version of the assembly, which might cause unpredictable behavior and security holes. @@ -134,7 +134,7 @@ This article discusses ways to avoid problems of type identity that can lead to Now consider what happens when your program is run. Assemblies that are referenced by your program are loaded into the default load context. If you load a target assembly by its identity, using the method, it will be in the default load context, and so will its dependencies. Both your program and the target assembly will use the same `Utility` assembly. - However, suppose you load the target assembly by its file path, using the method. The assembly is loaded without any context, so its dependencies are not automatically loaded. You might have a handler for the event to supply the dependency, and it might load the `Utility` assembly with no context by using the method. Now when you create an instance of a type that is contained in the target assembly and try to assign it to a variable of type `ICommunicate`, an is thrown because the runtime considers the `ICommunicate` interfaces in the two copies of the `Utility` assembly to be different types. + However, suppose you load the target assembly by its file path, using the method. The assembly is loaded without any context, so its dependencies are not automatically loaded. You might have a handler for the event to supply the dependency, and it might load the `Utility` assembly with no context by using the method. Now when you create an instance of a type that is contained in the target assembly and try to assign it to a variable of type `ICommunicate`, an is thrown because the runtime considers the `ICommunicate` interfaces in the two copies of the `Utility` assembly to be different types. There are many other scenarios in which an assembly can be loaded into multiple contexts. The best approach is to avoid conflicts by relocating the target assembly in your application path and using the method with the full display name. The assembly is then loaded into the default load context, and both assemblies use the same `Utility` assembly. @@ -148,13 +148,13 @@ This article discusses ways to avoid problems of type identity that can lead to For example, your program might load one version of the `Utility` assembly directly, and later it might load another assembly that loads a different version of the `Utility` assembly. Or a coding error might cause two different code paths in your application to load different versions of an assembly. - In the default load context, this problem can occur when you use the method and specify complete assembly display names that include different version numbers. For assemblies that are loaded without context, the problem can be caused by using the method to load the same assembly from different paths. The runtime considers two assemblies that are loaded from different paths to be different assemblies, even if their identities are the same. + In the default load context, this problem can occur when you use the method and specify complete assembly display names that include different version numbers. For assemblies that are loaded without context, the problem can be caused by using the method to load the same assembly from different paths. The runtime considers two assemblies that are loaded from different paths to be different assemblies, even if their identities are the same. In addition to type identity problems, multiple versions of an assembly can cause a if a type that is loaded from one version of the assembly is passed to code that expects that type from a different version. For example, the code might expect a method that was added to the later version. More subtle errors can occur if the behavior of the type changed between versions. For example, a method might throw an unexpected exception or return an unexpected value. - Carefully review your code to ensure that only one version of an assembly is loaded. You can use the method to determine which assemblies are loaded at any given time. + Carefully review your code to ensure that only one version of an assembly is loaded. You can use the method to determine which assemblies are loaded at any given time. ## Consider Switching to the Default Load Context @@ -169,13 +169,13 @@ This article discusses ways to avoid problems of type identity that can lead to Place assemblies in the global assembly cache to get the benefit of a shared assembly path that is outside the application base, without losing the advantages of the default load context or taking on the disadvantages of the other contexts. ### Consider Using Application Domains - If you determine that some of your assemblies cannot be deployed in the application's probing path, consider creating a new application domain for those assemblies. Use an to create the new application domain, and use the property to specify the path that contains the assemblies you want to load. If you have multiple directories to probe, you can set the to a root directory and use the property to identify the subdirectories to probe. Alternatively, you can create multiple application domains and set the of each application domain to the appropriate path for its assemblies. + If you determine that some of your assemblies cannot be deployed in the application's probing path, consider creating a new application domain for those assemblies. Use an to create the new application domain, and use the property to specify the path that contains the assemblies you want to load. If you have multiple directories to probe, you can set the to a root directory and use the property to identify the subdirectories to probe. Alternatively, you can create multiple application domains and set the of each application domain to the appropriate path for its assemblies. - Note that you can use the method to load these assemblies. Because they are now in the probing path, they will be loaded into the default load context instead of the load-from context. However, we recommend that you switch to the method and supply full assembly display names to ensure that correct versions are always used. + Note that you can use the method to load these assemblies. Because they are now in the probing path, they will be loaded into the default load context instead of the load-from context. However, we recommend that you switch to the method and supply full assembly display names to ensure that correct versions are always used. ## See Also - - - - + + + + [Add-ins and Extensibility](../../../docs/framework/add-ins/index.md) diff --git a/docs/framework/deployment/how-the-runtime-locates-assemblies.md b/docs/framework/deployment/how-the-runtime-locates-assemblies.md index fe4c806c5804e..ec5584033d63f 100644 --- a/docs/framework/deployment/how-the-runtime-locates-assemblies.md +++ b/docs/framework/deployment/how-the-runtime-locates-assemblies.md @@ -36,13 +36,13 @@ To successfully deploy your .NET Framework application, you must understand how > You can view binding information in the log file using the [Assembly Binding Log Viewer (Fuslogvw.exe)](../../../docs/framework/tools/fuslogvw-exe-assembly-binding-log-viewer.md), which is included in the [!INCLUDE[winsdklong](../../../includes/winsdklong-md.md)]. ## Initiating the Bind - The process of locating and binding to an assembly begins when the runtime attempts to resolve a reference to another assembly. This reference can be either static or dynamic. The compiler records static references in the assembly manifest's metadata at build time. Dynamic references are constructed on the fly as a result of calling various methods, such as . + The process of locating and binding to an assembly begins when the runtime attempts to resolve a reference to another assembly. This reference can be either static or dynamic. The compiler records static references in the assembly manifest's metadata at build time. Dynamic references are constructed on the fly as a result of calling various methods, such as . The preferred way to reference an assembly is to use a full reference, including the assembly name, version, culture, and public key token (if one exists). The runtime uses this information to locate the assembly, following the steps described later in this section. The runtime uses the same resolution process regardless of whether the reference is for a static or dynamic assembly. - You can also make a dynamic reference to an assembly by providing the calling method with only partial information about the assembly, such as specifying only the assembly name. In this case, only the application directory is searched for the assembly, and no other checking occurs. You make a partial reference using any of the various methods for loading assemblies such as or . + You can also make a dynamic reference to an assembly by providing the calling method with only partial information about the assembly, such as specifying only the assembly name. In this case, only the application directory is searched for the assembly, and no other checking occurs. You make a partial reference using any of the various methods for loading assemblies such as or . - Finally, you can make a dynamic reference using a method such as and provide only partial information; you then qualify the reference using the [\](../../../docs/framework/configure-apps/file-schema/runtime/qualifyassembly-element.md) element in the application configuration file. This element allows you to provide the full reference information (name, version, culture and, if applicable, the public key token) in your application configuration file instead of in your code. You would use this technique if you wanted to fully qualify a reference to an assembly outside the application directory, or if you wanted to reference an assembly in the global assembly cache but you wanted the convenience of specifying the full reference in the configuration file instead of in your code. + Finally, you can make a dynamic reference using a method such as and provide only partial information; you then qualify the reference using the [\](../../../docs/framework/configure-apps/file-schema/runtime/qualifyassembly-element.md) element in the application configuration file. This element allows you to provide the full reference information (name, version, culture and, if applicable, the public key token) in your application configuration file instead of in your code. You would use this technique if you wanted to fully qualify a reference to an assembly outside the application directory, or if you wanted to reference an assembly in the global assembly cache but you wanted the convenience of specifying the full reference in the configuration file instead of in your code. > [!NOTE] > This type of partial reference should not be used with assemblies that are shared among several applications. Because configuration settings are applied per application and not per assembly, a shared assembly using this type of partial reference would require each application using the shared assembly to have the qualifying information in its configuration file. @@ -60,7 +60,7 @@ To successfully deploy your .NET Framework application, you must understand how 4. [Probes for the assembly](#step4) using the following steps: - 1. If configuration and publisher policy do not affect the original reference and if the bind request was created using the method, the runtime checks for location hints. + 1. If configuration and publisher policy do not affect the original reference and if the bind request was created using the method, the runtime checks for location hints. 2. If a codebase is found in the configuration files, the runtime checks only this location. If this probe fails, the runtime determines that the binding request failed and no other probing occurs. @@ -252,7 +252,7 @@ Al.exe /link:asm6.exe.config /out:policy.3.0.asm6.dll /keyfile: compatkey.dat /v ``` #### Other Locations Probed - Assembly location can also be determined using the current binding context. This most often occurs when the method is used and in COM interop scenarios. If an assembly uses the method to reference another assembly, the calling assembly's location is considered to be a hint about where to find the referenced assembly. If a match is found, that assembly is loaded. If no match is found, the runtime continues with its search semantics and then queries the Windows Installer to provide the assembly. If no assembly is provided that matches the binding request, an exception is thrown. This exception is a in managed code if a type was referenced, or a if an assembly being loaded was not found. + Assembly location can also be determined using the current binding context. This most often occurs when the method is used and in COM interop scenarios. If an assembly uses the method to reference another assembly, the calling assembly's location is considered to be a hint about where to find the referenced assembly. If a match is found, that assembly is loaded. If no match is found, the runtime continues with its search semantics and then queries the Windows Installer to provide the assembly. If no assembly is provided that matches the binding request, an exception is thrown. This exception is a in managed code if a type was referenced, or a if an assembly being loaded was not found. For example, if Assembly1 references Assembly2 and Assembly1 was downloaded from http://www.code.microsoft.com/utils, that location is considered to be a hint about where to find Assembly2.dll. The runtime then probes for the assembly in http://www.code.microsoft.com/utils/Assembly2.dll and http://www.code.microsoft.com/utils/Assembly2/Assembly2.dll. If Assembly2 is not found at either of those locations, the runtime queries the Windows Installer. diff --git a/docs/framework/deployment/in-process-side-by-side-execution.md b/docs/framework/deployment/in-process-side-by-side-execution.md index adf05e4c25ba3..66dd9eb5fc41f 100644 --- a/docs/framework/deployment/in-process-side-by-side-execution.md +++ b/docs/framework/deployment/in-process-side-by-side-execution.md @@ -41,7 +41,7 @@ Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)] - **Application developers**. Side-by-side hosting has almost no effect on application developers. By default, applications always run against the version of the .NET Framework they were built on; this has not changed. However, developers can override this behavior and direct the application to run under a newer version of the .NET Framework (see [scenario 2](#scenarios)). -- **Library developers and consumers**. Side-by-side hosting does not solve the compatibility problems that library developers face. A library that is directly loaded by an application -- either through a direct reference or through an call -- continues to use the runtime of the it is loaded into. You should test your libraries against all versions of the .NET Framework that you want to support. If an application is compiled using the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] runtime but includes a library that was built using an earlier runtime, that library will use the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] runtime as well. However, if you have an application that was built using an earlier runtime and a library that was built using the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], you must force your application to also use the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] (see [scenario 3](#scenarios)). +- **Library developers and consumers**. Side-by-side hosting does not solve the compatibility problems that library developers face. A library that is directly loaded by an application -- either through a direct reference or through an call -- continues to use the runtime of the it is loaded into. You should test your libraries against all versions of the .NET Framework that you want to support. If an application is compiled using the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] runtime but includes a library that was built using an earlier runtime, that library will use the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] runtime as well. However, if you have an application that was built using an earlier runtime and a library that was built using the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], you must force your application to also use the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] (see [scenario 3](#scenarios)). - **Managed COM component developers**. In the past, managed COM components automatically ran using the latest version of the runtime installed on the computer. You can now execute COM components against the version of the runtime they were built with. diff --git a/docs/framework/interop/blittable-and-non-blittable-types.md b/docs/framework/interop/blittable-and-non-blittable-types.md index 2062dea9b95fc..bfa3637d1c3bf 100644 --- a/docs/framework/interop/blittable-and-non-blittable-types.md +++ b/docs/framework/interop/blittable-and-non-blittable-types.md @@ -30,29 +30,29 @@ Most data types have a common representation in both managed and unmanaged memor The following types from the namespace are blittable types: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- The following complex types are also blittable types: diff --git a/docs/framework/interop/copying-and-pinning.md b/docs/framework/interop/copying-and-pinning.md index 4820825cb292c..f66bf8d575733 100644 --- a/docs/framework/interop/copying-and-pinning.md +++ b/docs/framework/interop/copying-and-pinning.md @@ -82,9 +82,9 @@ Reference types passed by value and by reference > [!CAUTION] > When a string is passed by value, the callee must never alter the reference passed by the marshaler. Doing so can corrupt the managed heap. - When a is passed by reference, the marshaler copies the contents the string to a secondary buffer before making the call. It then copies the contents of the buffer into a new string on return from the call. This technique ensures that the immutable managed string remains unaltered. + When a is passed by reference, the marshaler copies the contents the string to a secondary buffer before making the call. It then copies the contents of the buffer into a new string on return from the call. This technique ensures that the immutable managed string remains unaltered. - When a is passed by value, the marshaler passes a reference to the internal buffer of the **StringBuilder** directly to the caller. The caller and callee must agree on the size of the buffer. The caller is responsible for creating a **StringBuilder** of adequate length. The callee must take the necessary precautions to ensure that the buffer is not overrun. **StringBuilder** is an exception to the rule that reference types passed by value are passed as In parameters by default. It is always passed as In/Out. + When a is passed by value, the marshaler passes a reference to the internal buffer of the **StringBuilder** directly to the caller. The caller and callee must agree on the size of the buffer. The caller is responsible for creating a **StringBuilder** of adequate length. The callee must take the necessary precautions to ensure that the buffer is not overrun. **StringBuilder** is an exception to the rule that reference types passed by value are passed as In parameters by default. It is always passed as In/Out. ## See Also [Default Marshaling Behavior](../../../docs/framework/interop/default-marshaling-behavior.md) diff --git a/docs/framework/interop/creating-prototypes-in-managed-code.md b/docs/framework/interop/creating-prototypes-in-managed-code.md index 7e9eccb4b7e18..e11682b7d482a 100644 --- a/docs/framework/interop/creating-prototypes-in-managed-code.md +++ b/docs/framework/interop/creating-prototypes-in-managed-code.md @@ -37,7 +37,7 @@ This topic describes how to access unmanaged functions and introduces several at Before you can access an unmanaged DLL function from managed code, you need to know the name of the function and the name of the DLL that exports it. With this information, you can begin to write the managed definition for an unmanaged function that is implemented in a DLL. Furthermore, you can adjust the way that platform invoke creates the function and marshals data to and from the function. > [!NOTE] -> Win32 API functions that allocate a string enable you to free the string by using a method such as `LocalFree`. Platform invoke handles such parameters differently. For platform invoke calls, make the parameter an `IntPtr` type instead of a `String` type. Use methods that are provided by the class to convert the type to a string manually and free it manually. +> Win32 API functions that allocate a string enable you to free the string by using a method such as `LocalFree`. Platform invoke handles such parameters differently. For platform invoke calls, make the parameter an `IntPtr` type instead of a `String` type. Use methods that are provided by the class to convert the type to a string manually and free it manually. ## Declaration Basics Managed definitions to unmanaged functions are language-dependent, as you can see in the following examples. For more complete code examples, see [Platform Invoke Examples](../../../docs/framework/interop/platform-invoke-examples.md). diff --git a/docs/framework/interop/default-marshaling-behavior.md b/docs/framework/interop/default-marshaling-behavior.md index a5af8f6e25f68..ccadbc1df3b92 100644 --- a/docs/framework/interop/default-marshaling-behavior.md +++ b/docs/framework/interop/default-marshaling-behavior.md @@ -81,7 +81,7 @@ BSTR MethodOne (BSTR b) { - For platform invoke, a delegate is marshaled as an unmanaged function pointer by default. -- For COM interop, a delegate is marshaled as a COM interface of type **_Delegate** by default. The **_Delegate** interface is defined in the Mscorlib.tlb type library and contains the method, which enables you to call the method that the delegate references. +- For COM interop, a delegate is marshaled as a COM interface of type **_Delegate** by default. The **_Delegate** interface is defined in the Mscorlib.tlb type library and contains the method, which enables you to call the method that the delegate references. The following table shows the marshaling options for the managed delegate data type. The attribute provides several enumeration values to marshal delegates. @@ -359,34 +359,34 @@ interface _Graphics { ### System Value Types - The namespace has several value types that represent the boxed form of the runtime primitive types. For example, the value type structure represents the boxed form of **ELEMENT_TYPE_I4**. Instead of marshaling these types as structures, as other formatted types are, you marshal them in the same way as the primitive types they box. **System.Int32** is therefore marshaled as **ELEMENT_TYPE_I4** instead of as a structure containing a single member of type **long**. The following table contains a list of the value types in the **System** namespace that are boxed representations of primitive types. + The namespace has several value types that represent the boxed form of the runtime primitive types. For example, the value type structure represents the boxed form of **ELEMENT_TYPE_I4**. Instead of marshaling these types as structures, as other formatted types are, you marshal them in the same way as the primitive types they box. **System.Int32** is therefore marshaled as **ELEMENT_TYPE_I4** instead of as a structure containing a single member of type **long**. The following table contains a list of the value types in the **System** namespace that are boxed representations of primitive types. |System value type|Element type| |-----------------------|------------------| -||**ELEMENT_TYPE_BOOLEAN**| -||**ELEMENT_TYPE_I1**| -||**ELEMENT_TYPE_UI1**| -||**ELEMENT_TYPE_CHAR**| -||**ELEMENT_TYPE_I2**| -||**ELEMENT_TYPE_U2**| -||**ELEMENT_TYPE_I4**| -||**ELEMENT_TYPE_U4**| -||**ELEMENT_TYPE_I8**| -||**ELEMENT_TYPE_U8**| -||**ELEMENT_TYPE_R4**| -||**ELEMENT_TYPE_R8**| -||**ELEMENT_TYPE_STRING**| -||**ELEMENT_TYPE_I**| -||**ELEMENT_TYPE_U**| +||**ELEMENT_TYPE_BOOLEAN**| +||**ELEMENT_TYPE_I1**| +||**ELEMENT_TYPE_UI1**| +||**ELEMENT_TYPE_CHAR**| +||**ELEMENT_TYPE_I2**| +||**ELEMENT_TYPE_U2**| +||**ELEMENT_TYPE_I4**| +||**ELEMENT_TYPE_U4**| +||**ELEMENT_TYPE_I8**| +||**ELEMENT_TYPE_U8**| +||**ELEMENT_TYPE_R4**| +||**ELEMENT_TYPE_R8**| +||**ELEMENT_TYPE_STRING**| +||**ELEMENT_TYPE_I**| +||**ELEMENT_TYPE_U**| Some other value types in the **System** namespace are handled differently. Because the unmanaged code already has well-established formats for these types, the marshaler has special rules for marshaling them. The following table lists the special value types in the **System** namespace, as well as the unmanaged type they are marshaled to. |System value type|IDL type| |-----------------------|--------------| -||**DATE**| -||**DECIMAL**| -||**GUID**| -||**OLE_COLOR**| +||**DATE**| +||**DECIMAL**| +||**GUID**| +||**OLE_COLOR**| The following code shows the definition of the unmanaged types **DATE**, **GUID**, **DECIMAL**, and **OLE_COLOR** in the Stdole2 type library. diff --git a/docs/framework/interop/default-marshaling-for-arrays.md b/docs/framework/interop/default-marshaling-for-arrays.md index b2829daf6f17c..902a8aaeed700 100644 --- a/docs/framework/interop/default-marshaling-for-arrays.md +++ b/docs/framework/interop/default-marshaling-for-arrays.md @@ -40,7 +40,7 @@ In an application consisting entirely of managed code, the common language runti ## Managed Arrays - Managed array types can vary; however, the class is the base class of all array types. The **System.Array** class has properties for determining the rank, length, and lower and upper bounds of an array, as well as methods for accessing, sorting, searching, copying, and creating arrays. + Managed array types can vary; however, the class is the base class of all array types. The **System.Array** class has properties for determining the rank, length, and lower and upper bounds of an array, as well as methods for accessing, sorting, searching, copying, and creating arrays. These array types are dynamic and do not have a corresponding static type defined in the base class library. It is convenient to think of each combination of element type and rank as a distinct type of array. Therefore, a one-dimensional array of integers is of a different type than a one-dimensional array of double types. Similarly a two-dimensional array of integers is different from a one-dimensional array of integers. The bounds of the array are not considered when comparing types. @@ -97,7 +97,7 @@ void New3([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_BSTR)] ref String[] ar); ``` - Multidimensional, or nonzero-bound safe arrays, can be marshaled into managed code if the method signature produced by Tlbimp.exe is modified to indicate an element type of **ELEMENT_TYPE_ARRAY** instead of **ELEMENT_TYPE_SZARRAY**. Alternatively, you can use the **/sysarray** switch with Tlbimp.exe to import all arrays as objects. In cases where the array being passed is known to be multidimensional, you can edit the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompile it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](http://msdn.microsoft.com/en-us/4652beaf-77d0-4f37-9687-ca193288c0be). + Multidimensional, or nonzero-bound safe arrays, can be marshaled into managed code if the method signature produced by Tlbimp.exe is modified to indicate an element type of **ELEMENT_TYPE_ARRAY** instead of **ELEMENT_TYPE_SZARRAY**. Alternatively, you can use the **/sysarray** switch with Tlbimp.exe to import all arrays as objects. In cases where the array being passed is known to be multidimensional, you can edit the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompile it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](http://msdn.microsoft.com/en-us/4652beaf-77d0-4f37-9687-ca193288c0be). ### C-Style Arrays When a C-style array is imported from a type library to a .NET assembly, the array is converted to **ELEMENT_TYPE_SZARRAY**. @@ -204,7 +204,7 @@ void New3(ref String ar); |------------------------|-----------------| |**ELEMENT_TYPE_SZARRAY** **\<** *type* **>**| **.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type is provided in the signature. Rank is always 1, lower bound is always 0. Size is always known at run time.| |**ELEMENT_TYPE_ARRAY** **\<** *type* **>** **\<** *rank* **>**[**\<** *bounds* **>**]|**UnmanagedType.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type, rank, bounds are provided in the signature. Size is always known at run time.| -|**ELEMENT_TYPE_CLASS** **\<****>**|**UT_Interface**

**UnmanagedType.SafeArray(** *type* **)**

Type, rank, bounds, and size are always known at run time.| +|**ELEMENT_TYPE_CLASS** **\<****>**|**UT_Interface**

**UnmanagedType.SafeArray(** *type* **)**

Type, rank, bounds, and size are always known at run time.| There is a limitation in OLE Automation relating to arrays of structures that contain LPSTR or LPWSTR. Therefore, **String** fields have to be marshaled as **UnmanagedType.BSTR**. Otherwise, an exception will be thrown. @@ -330,7 +330,7 @@ void New(long [][][] ar ); ``` ### ELEMENT_TYPE_CLASS \ - When a method containing a parameter is exported from a .NET assembly to a type library, the array parameter is converted to an **_Array** interface. The contents of the managed array are accessible only through the methods and properties of the **_Array** interface. **System.Array** can also be marshaled as a **SAFEARRAY** by using the attribute. When marshaled as a safe array, the array elements are marshaled as variants. For example: + When a method containing a parameter is exported from a .NET assembly to a type library, the array parameter is converted to an **_Array** interface. The contents of the managed array are accessible only through the methods and properties of the **_Array** interface. **System.Array** can also be marshaled as a **SAFEARRAY** by using the attribute. When marshaled as a safe array, the array elements are marshaled as variants. For example: #### Managed signature diff --git a/docs/framework/interop/default-marshaling-for-objects.md b/docs/framework/interop/default-marshaling-for-objects.md index 68c72ffa7a3e5..663083578441f 100644 --- a/docs/framework/interop/default-marshaling-for-objects.md +++ b/docs/framework/interop/default-marshaling-for-objects.md @@ -24,7 +24,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Default Marshaling for Objects -Parameters and fields typed as can be exposed to unmanaged code as one of the following types: +Parameters and fields typed as can be exposed to unmanaged code as one of the following types: - A variant when the object is a parameter. @@ -145,37 +145,37 @@ struct ObjectHolder { - If the object is an instance of any type listed in the following table, the resulting variant type is determined by the rules built into the marshaler and shown in the table. -- Other objects that need to explicitly control the marshaling behavior can implement the interface. In that case, the variant type is determined by the type code returned from the method. Otherwise, the object is marshaled as a variant of type **VT_UNKNOWN**. +- Other objects that need to explicitly control the marshaling behavior can implement the interface. In that case, the variant type is determined by the type code returned from the method. Otherwise, the object is marshaled as a variant of type **VT_UNKNOWN**. ### Marshaling System Types to Variant - The following table shows managed object types and their corresponding COM variant types. These types are converted only when the signature of the method being called is of type . + The following table shows managed object types and their corresponding COM variant types. These types are converted only when the signature of the method being called is of type . |Object type|COM variant type| |-----------------|----------------------| |Null object reference (**Nothing** in Visual Basic).|**VT_EMPTY**| -||**VT_NULL**| -||**VT_ERROR**| -||**VT_ERROR** with **E_PARAMNOTFOUND**| -||**VT_DISPATCH**| -||**VT_UNKNOWN**| -||**VT_CY**| -||**VT_BOOL**| -||**VT_I1**| -||**VT_UI1**| -||**VT_I2**| -||**VT_UI2**| -||**VT_I4**| -||**VT_UI4**| -||**VT_I8**| -||**VT_UI8**| -||**VT_R4**| -||**VT_R8**| -||**VT_DECIMAL**| -||**VT_DATE**| -||**VT_BSTR**| -||**VT_INT**| -||**VT_UINT**| -||**VT_ARRAY**| +||**VT_NULL**| +||**VT_ERROR**| +||**VT_ERROR** with **E_PARAMNOTFOUND**| +||**VT_DISPATCH**| +||**VT_UNKNOWN**| +||**VT_CY**| +||**VT_BOOL**| +||**VT_I1**| +||**VT_UI1**| +||**VT_I2**| +||**VT_UI2**| +||**VT_I4**| +||**VT_UI4**| +||**VT_I8**| +||**VT_UI8**| +||**VT_R4**| +||**VT_R8**| +||**VT_DECIMAL**| +||**VT_DATE**| +||**VT_BSTR**| +||**VT_INT**| +||**VT_UINT**| +||**VT_ARRAY**| Using the `MarshalObject` interface defined in the previous example, the following code example demonstrates how to pass various types of variants to a COM server. @@ -228,7 +228,7 @@ mo.SetVariant(new CurrencyWrapper(new Decimal(5.25))); The wrapper classes are defined in the namespace. ### Marshaling the IConvertible Interface to Variant - Types other than those listed in the previous section can control how they are marshaled by implementing the interface. If the object implements the **IConvertible** interface, the COM variant type is determined at run time by the value of the enumeration returned from the method. + Types other than those listed in the previous section can control how they are marshaled by implementing the interface. If the object implements the **IConvertible** interface, the COM variant type is determined at run time by the value of the enumeration returned from the method. The following table shows the possible values for the **TypeCode** enumeration and the corresponding COM variant type for each value. @@ -268,32 +268,32 @@ mo.SetVariant(new CurrencyWrapper(new Decimal(5.25))); |COM variant type|Object type| |----------------------|-----------------| |**VT_EMPTY**|Null object reference (**Nothing** in Visual Basic).| -|**VT_NULL**|| +|**VT_NULL**|| |**VT_DISPATCH**|**System.__ComObject** or null if (pdispVal == null)| |**VT_UNKNOWN**|**System.__ComObject** or null if (punkVal == null)| -|**VT_ERROR**|| -|**VT_BOOL**|| -|**VT_I1**|| -|**VT_UI1**|| -|**VT_I2**|| -|**VT_UI2**|| -|**VT_I4**|| -|**VT_UI4**|| -|**VT_I8**|| -|**VT_UI8**|| -|**VT_R4**|| -|**VT_R8**|| -|**VT_DECIMAL**|| -|**VT_DATE**|| -|**VT_BSTR**|| -|**VT_INT**|| -|**VT_UINT**|| -|**VT_ARRAY** | **VT_\***|| -|**VT_CY**|| +|**VT_ERROR**|| +|**VT_BOOL**|| +|**VT_I1**|| +|**VT_UI1**|| +|**VT_I2**|| +|**VT_UI2**|| +|**VT_I4**|| +|**VT_UI4**|| +|**VT_I8**|| +|**VT_UI8**|| +|**VT_R4**|| +|**VT_R8**|| +|**VT_DECIMAL**|| +|**VT_DATE**|| +|**VT_BSTR**|| +|**VT_INT**|| +|**VT_UINT**|| +|**VT_ARRAY** | **VT_\***|| +|**VT_CY**|| |**VT_RECORD**|Corresponding boxed value type.| |**VT_VARIANT**|Not supported.| - Variant types passed from COM to managed code and then back to COM might not retain the same variant type for the duration of the call. Consider what happens when a variant of type **VT_DISPATCH** is passed from COM to the .NET Framework. During marshaling, the variant is converted to a . If the **Object** is then passed back to COM, it is marshaled back to a variant of type **VT_UNKNOWN**. There is no guarantee that the variant produced when an object is marshaled from managed code to COM will be the same type as the variant initially used to produce the object. + Variant types passed from COM to managed code and then back to COM might not retain the same variant type for the duration of the call. Consider what happens when a variant of type **VT_DISPATCH** is passed from COM to the .NET Framework. During marshaling, the variant is converted to a . If the **Object** is then passed back to COM, it is marshaled back to a variant of type **VT_UNKNOWN**. There is no guarantee that the variant produced when an object is marshaled from managed code to COM will be the same type as the variant initially used to produce the object. ## Marshaling ByRef Variants diff --git a/docs/framework/interop/default-marshaling-for-strings.md b/docs/framework/interop/default-marshaling-for-strings.md index 7b3a011f96fdc..ee154016f4087 100644 --- a/docs/framework/interop/default-marshaling-for-strings.md +++ b/docs/framework/interop/default-marshaling-for-strings.md @@ -24,7 +24,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Default Marshaling for Strings -Both the and classes have similar marshaling behavior. +Both the and classes have similar marshaling behavior. Strings are marshaled as a COM-style `BSTR` type or as a null-terminated string (a character array that ends with a null character). The characters within the string can be marshaled as Unicode (the default on Windows systems) or ANSI. diff --git a/docs/framework/interop/importing-a-type-library-as-an-assembly.md b/docs/framework/interop/importing-a-type-library-as-an-assembly.md index 43a33d7abf591..b4a53f72e456e 100644 --- a/docs/framework/interop/importing-a-type-library-as-an-assembly.md +++ b/docs/framework/interop/importing-a-type-library-as-an-assembly.md @@ -59,7 +59,7 @@ COM type definitions usually reside in a type library. In contrast, CLS-complian The Type Library Importer provides command-line options to adjust metadata in the resulting interop file, imports types from an existing type library, and generates an interop assembly and a namespace. For instructions, see [How to: Generate Interop Assemblies from Type Libraries](../../../docs/framework/interop/how-to-generate-interop-assemblies-from-type-libraries.md). -- class +- class This class provides methods to convert coclasses and interfaces in a type library to metadata within an assembly. It produces the same metadata output as Tlbimp.exe. However, unlike Tlbimp.exe, the class can convert an in-memory type library to metadata. diff --git a/docs/framework/interop/interop-marshaling.md b/docs/framework/interop/interop-marshaling.md index c315672555b96..a3b9d6fe09639 100644 --- a/docs/framework/interop/interop-marshaling.md +++ b/docs/framework/interop/interop-marshaling.md @@ -82,7 +82,7 @@ Same-apartment marshaling process If you plan to export a managed server, be aware that the COM client determines the apartment of the server. A managed server called by a COM client initialized in an MTA must ensure thread safety. ### Managed Clients and COM Servers - The default setting for managed client apartments is MTA; however, the application type of the .NET client can change the default setting. For example, a [!INCLUDE[vbprvblong](../../../includes/vbprvblong-md.md)] client apartment setting is STA. You can use the , the , the property, or the property to examine and change the apartment setting of a managed client. + The default setting for managed client apartments is MTA; however, the application type of the .NET client can change the default setting. For example, a [!INCLUDE[vbprvblong](../../../includes/vbprvblong-md.md)] client apartment setting is STA. You can use the , the , the property, or the property to examine and change the apartment setting of a managed client. The author of the component sets the thread affinity of a COM server. The following table shows the combinations of apartment settings for .NET clients and COM servers. It also shows the resulting marshaling requirements for the combinations. @@ -168,6 +168,6 @@ Remote calls across firewalls using SOAP or the TcpChannel class ## Reference - + [Back to top](#top) diff --git a/docs/framework/interop/marshaling-classes-structures-and-unions.md b/docs/framework/interop/marshaling-classes-structures-and-unions.md index fb5bf617953b5..2108d7848e92d 100644 --- a/docs/framework/interop/marshaling-classes-structures-and-unions.md +++ b/docs/framework/interop/marshaling-classes-structures-and-unions.md @@ -121,7 +121,7 @@ typedef struct _MYARRAYSTRUCT - `TestArrayInStruct` declares a reference to type `MyArrayStruct` as its parameter. - Structures as arguments to methods are passed by value unless the parameter contains the **ref** (**ByRef** in Visual Basic) keyword. For example, the `TestStructInStruct` method passes a reference (the value of an address) to an object of type `MyPerson2` to unmanaged code. To manipulate the structure that `MyPerson2` points to, the sample creates a buffer of a specified size and returns its address by combining the and methods. Next, the sample copies the content of the managed structure to the unmanaged buffer. Finally, the sample uses the method to marshal data from the unmanaged buffer to a managed object and the method to free the unmanaged block of memory. + Structures as arguments to methods are passed by value unless the parameter contains the **ref** (**ByRef** in Visual Basic) keyword. For example, the `TestStructInStruct` method passes a reference (the value of an address) to an object of type `MyPerson2` to unmanaged code. To manipulate the structure that `MyPerson2` points to, the sample creates a buffer of a specified size and returns its address by combining the and methods. Next, the sample copies the content of the managed structure to the unmanaged buffer. Finally, the sample uses the method to marshal data from the unmanaged buffer to a managed object and the method to free the unmanaged block of memory. ### Declaring Prototypes [!code-cpp[Conceptual.Interop.Marshaling#23](../../../samples/snippets/cpp/VS_Snippets_CLR/conceptual.interop.marshaling/cpp/structures.cpp#23)] diff --git a/docs/framework/interop/marshaling-data-with-platform-invoke.md b/docs/framework/interop/marshaling-data-with-platform-invoke.md index 1ac066ca593e2..a5485cc1ce9ba 100644 --- a/docs/framework/interop/marshaling-data-with-platform-invoke.md +++ b/docs/framework/interop/marshaling-data-with-platform-invoke.md @@ -40,24 +40,24 @@ To call functions exported from an unmanaged library, a .NET Framework applicati |Unmanaged type in Wtypes.h|Unmanaged C language type|Managed class name|Description| |--------------------------------|-------------------------------|------------------------|-----------------| -|**HANDLE**|**void\***||32 bits on 32-bit Windows operating systems, 64 bits on 64-bit Windows operating systems.| -|**BYTE**|**unsigned char**||8 bits| -|**SHORT**|**short**||16 bits| -|**WORD**|**unsigned short**||16 bits| -|**INT**|**int**||32 bits| -|**UINT**|**unsigned int**||32 bits| -|**LONG**|**long**||32 bits| +|**HANDLE**|**void\***||32 bits on 32-bit Windows operating systems, 64 bits on 64-bit Windows operating systems.| +|**BYTE**|**unsigned char**||8 bits| +|**SHORT**|**short**||16 bits| +|**WORD**|**unsigned short**||16 bits| +|**INT**|**int**||32 bits| +|**UINT**|**unsigned int**||32 bits| +|**LONG**|**long**||32 bits| |**BOOL**|**long**||32 bits| -|**DWORD**|**unsigned long**||32 bits| -|**ULONG**|**unsigned long**||32 bits| -|**CHAR**|**char**||Decorate with ANSI.| -|**WCHAR**|**wchar_t**||Decorate with Unicode.| -|**LPSTR**|**char\***| or |Decorate with ANSI.| -|**LPCSTR**|**Const char\***| or |Decorate with ANSI.| -|**LPWSTR**|**wchar_t\***| or |Decorate with Unicode.| -|**LPCWSTR**|**Const wchar_t\***| or |Decorate with Unicode.| -|**FLOAT**|**Float**||32 bits| -|**DOUBLE**|**Double**||64 bits| +|**DWORD**|**unsigned long**||32 bits| +|**ULONG**|**unsigned long**||32 bits| +|**CHAR**|**char**||Decorate with ANSI.| +|**WCHAR**|**wchar_t**||Decorate with Unicode.| +|**LPSTR**|**char\***| or |Decorate with ANSI.| +|**LPCSTR**|**Const char\***| or |Decorate with ANSI.| +|**LPWSTR**|**wchar_t\***| or |Decorate with Unicode.| +|**LPCWSTR**|**Const wchar_t\***| or |Decorate with Unicode.| +|**FLOAT**|**Float**||32 bits| +|**DOUBLE**|**Double**||64 bits| For corresponding types in [!INCLUDE[vbprvblong](../../../includes/vbprvblong-md.md)], C#, and C++, see the [Introduction to the .NET Framework Class Library](../../../docs/standard/class-library-overview.md). diff --git a/docs/framework/interop/platform-invoke-examples.md b/docs/framework/interop/platform-invoke-examples.md index babae7627a80a..30d1d652f7698 100644 --- a/docs/framework/interop/platform-invoke-examples.md +++ b/docs/framework/interop/platform-invoke-examples.md @@ -28,7 +28,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Platform Invoke Examples -The following examples demonstrate how to define and call the **MessageBox** function in User32.dll, passing a simple string as an argument. In the examples, the field is set to **Auto** to let the target platform determine the character width and string marshaling. +The following examples demonstrate how to define and call the **MessageBox** function in User32.dll, passing a simple string as an argument. In the examples, the field is set to **Auto** to let the target platform determine the character width and string marshaling. [!code-cpp[Conceptual.Interop.PInvoke#1](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.Interop.PInvoke/cpp/Example.cpp#1)] [!code-csharp[Conceptual.Interop.PInvoke#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.Interop.PInvoke/cs/Example1.cs#1)] diff --git a/docs/framework/interop/specifying-a-character-set.md b/docs/framework/interop/specifying-a-character-set.md index 79379de9ef32b..d2e8762866b42 100644 --- a/docs/framework/interop/specifying-a-character-set.md +++ b/docs/framework/interop/specifying-a-character-set.md @@ -25,7 +25,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Specifying a Character Set -The field controls string marshaling and determines how platform invoke finds function names in a DLL. This topic describes both behaviors. +The field controls string marshaling and determines how platform invoke finds function names in a DLL. This topic describes both behaviors. Some APIs export two versions of functions that take string arguments: narrow (ANSI) and wide (Unicode). The Win32 API, for instance, includes the following entry-point names for the **MessageBox** function: @@ -48,7 +48,7 @@ The field is **true**, as it is by default in [!INCLUDE[vbprvblong](../../../includes/vbprvblong-md.md)], platform invoke searches only for the name you specify. For example, if you specify **MessageBox**, platform invoke searches for **MessageBox** and fails when it cannot locate the exact spelling. + When the field is **true**, as it is by default in [!INCLUDE[vbprvblong](../../../includes/vbprvblong-md.md)], platform invoke searches only for the name you specify. For example, if you specify **MessageBox**, platform invoke searches for **MessageBox** and fails when it cannot locate the exact spelling. When the **ExactSpelling** field is **false**, as it is by default in C++ and C#, platform invoke searches for the unmangled alias first (**MessageBox**), then the mangled name (**MessageBoxA**) if the unmangled alias is not found. Notice that ANSI name-matching behavior differs from Unicode name-matching behavior. @@ -71,7 +71,7 @@ The field defaults to the ANSI character set. The second and third statements in the example explicitly specify a character set with a keyword. + If you omit the character-set keyword, as is done in the first declaration statement, the field defaults to the ANSI character set. The second and third statements in the example explicitly specify a character set with a keyword. ```vb Imports System.Runtime.InteropServices @@ -92,7 +92,7 @@ End Class ``` ## Specifying a Character Set in C# and C++ - The field identifies the underlying character set as ANSI or Unicode. The character set controls how string arguments to a method should be marshaled. Use one of the following forms to indicate the character set: + The field identifies the underlying character set as ANSI or Unicode. The character set controls how string arguments to a method should be marshaled. Use one of the following forms to indicate the character set: ```csharp [DllImport("dllname", CharSet=CharSet.Ansi)] diff --git a/docs/framework/interop/specifying-an-entry-point.md b/docs/framework/interop/specifying-an-entry-point.md index de091fe98c310..bba68b14e942f 100644 --- a/docs/framework/interop/specifying-an-entry-point.md +++ b/docs/framework/interop/specifying-an-entry-point.md @@ -40,7 +40,7 @@ An entry point identifies the location of a function in a DLL. Within a managed This topic demonstrates how to rename a DLL function in managed code. ## Renaming a Function in Visual Basic - Visual Basic uses the **Function** keyword in the **Declare** statement to set the field. The following example shows a basic declaration. + Visual Basic uses the **Function** keyword in the **Declare** statement to set the field. The following example shows a basic declaration. ```vb Imports System.Runtime.InteropServices @@ -65,7 +65,7 @@ End Class ``` ## Renaming a Function in C# and C++ - You can use the field to specify a DLL function by name or ordinal. If the name of the function in your method definition is the same as the entry point in the DLL, you do not have to explicitly identify the function with the **EntryPoint** field. Otherwise, use one of the following attribute forms to indicate a name or ordinal: + You can use the field to specify a DLL function by name or ordinal. If the name of the function in your method definition is the same as the entry point in the DLL, you do not have to explicitly identify the function with the **EntryPoint** field. Otherwise, use one of the following attribute forms to indicate a name or ordinal: ``` [DllImport("dllname", EntryPoint="Functionname")] diff --git a/docs/framework/interop/type-equivalence-and-embedded-interop-types.md b/docs/framework/interop/type-equivalence-and-embedded-interop-types.md index a0be1f8a38033..e8e78c72fa9e5 100644 --- a/docs/framework/interop/type-equivalence-and-embedded-interop-types.md +++ b/docs/framework/interop/type-equivalence-and-embedded-interop-types.md @@ -47,9 +47,9 @@ Beginning with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md) If a type does not have the attribute, or if it has a attribute that does not specify scope and identifier, the type can still be considered for equivalence as follows: -- For interfaces, the value of the is used instead of the property, and the property (that is, the type name, including the namespace) is used instead of the property. +- For interfaces, the value of the is used instead of the property, and the property (that is, the type name, including the namespace) is used instead of the property. -- For structures, enumerations, and delegates, the of the containing assembly is used instead of the property, and the property is used instead of the property. +- For structures, enumerations, and delegates, the of the containing assembly is used instead of the property, and the property is used instead of the property. ### Marking COM Types for Type Equivalence diff --git a/docs/framework/mef/index.md b/docs/framework/mef/index.md index 392a17f64265d..a8d9b60bc56a6 100644 --- a/docs/framework/mef/index.md +++ b/docs/framework/mef/index.md @@ -474,4 +474,4 @@ public class Mod : SimpleCalculator.IOperation ## Where Do I Go Now? To download the complete code for this example, see the [SimpleCalculator sample](http://code.msdn.microsoft.com/windowsdesktop/Simple-Calculator-MEF-1152654e). - For more information and code examples, see [Managed Extensibility Framework](http://go.microsoft.com/fwlink/?LinkId=144282). For a list of the MEF types, see the namespace. + For more information and code examples, see [Managed Extensibility Framework](http://go.microsoft.com/fwlink/?LinkId=144282). For a list of the MEF types, see the namespace. diff --git a/docs/framework/mef/mef-for-net-for-windows-store-apps.md b/docs/framework/mef/mef-for-net-for-windows-store-apps.md index c5ab503bcb01f..53eb6f0a4fe0a 100644 --- a/docs/framework/mef/mef-for-net-for-windows-store-apps.md +++ b/docs/framework/mef/mef-for-net-for-windows-store-apps.md @@ -16,17 +16,17 @@ ms.author: "ronpet" manager: "wpickett" --- # MEF for .NET for Windows Store Apps - and its child namespaces contain types for developing extensible [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps with Managed Extensibility Framework (MEF). These namespaces are part of the [!INCLUDE[net_win8_profile](../../../includes/net-win8-profile-md.md)] subset for the [!INCLUDE[win8](../../../includes/win8-md.md)] operating system. + and its child namespaces contain types for developing extensible [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps with Managed Extensibility Framework (MEF). These namespaces are part of the [!INCLUDE[net_win8_profile](../../../includes/net-win8-profile-md.md)] subset for the [!INCLUDE[win8](../../../includes/win8-md.md)] operating system. These namespaces are not part of the core class library distributed with the .NET Framework. To install these namespaces, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the **Project** menu, and search online for the Microsoft.Composition package. -- provides classes that constitute the core MEF for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. +- provides classes that constitute the core MEF for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. -- provides types that support using MEF with a convention-based configuration model. +- provides types that support using MEF with a convention-based configuration model. -- provides MEF types that are useful to developers of host applications. +- provides MEF types that are useful to developers of host applications. -- provides MEF types used internally by the composition engine. +- provides MEF types used internally by the composition engine. For more information about [!INCLUDE[net_win8_profile](../../../includes/net-win8-profile-md.md)] and a list of namespaces and types that it contains, see [.NET for Windows Store apps overview](http://go.microsoft.com/fwlink/p/?LinkID=238312) in the Windows Dev Center. diff --git a/docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md b/docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md index ffbb073abb101..391416fe8bb07 100644 --- a/docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md +++ b/docs/framework/migration-guide/how-to-determine-which-versions-are-installed.md @@ -93,7 +93,7 @@ Users can install and run multiple versions of the .NET Framework on their compu #### To find .NET Framework versions by querying the registry in code (.NET Framework 1-4) -- Use the class to access the Software\Microsoft\NET Framework Setup\NDP\ subkey under HKEY_LOCAL_MACHINE in the Windows registry. +- Use the class to access the Software\Microsoft\NET Framework Setup\NDP\ subkey under HKEY_LOCAL_MACHINE in the Windows registry. The following code shows an example of this query. @@ -117,7 +117,7 @@ Users can install and run multiple versions of the .NET Framework on their compu #### To find .NET Framework versions by querying the registry in code (.NET Framework 4.5 and later) -1. The existence of the `Release` DWORD indicates that the .NET Framework 4.5 or later has been installed on a computer. The value of the keyword indicates the installed version. To check this keyword, use the and methods of the class to access the Software\Microsoft\NET Framework Setup\NDP\v4\Full subkey under HKEY_LOCAL_MACHINE in the Windows registry. +1. The existence of the `Release` DWORD indicates that the .NET Framework 4.5 or later has been installed on a computer. The value of the keyword indicates the installed version. To check this keyword, use the and methods of the class to access the Software\Microsoft\NET Framework Setup\NDP\v4\Full subkey under HKEY_LOCAL_MACHINE in the Windows registry. 2. Check the value of the `Release` keyword to determine the installed version. To be forward-compatible, you can check for a value greater than or equal to the values listed in the table. Here are the .NET Framework versions and associated `Release` keywords. @@ -186,14 +186,14 @@ Users can install and run multiple versions of the .NET Framework on their compu #### To find the current runtime version by querying the Environment class in code -- Query the property to retrieve a object that identifies the version of the runtime that is currently executing the code. You can use the property to get the major release identifier (for example, "4" for version 4.0), the property to get the minor release identifier (for example, "0" for version 4.0), or the method to get the entire version string (for example, "4.0.30319.18010", as shown in the following code). This property returns a single value that reflects the version of the runtime that is currently executing the code; it does not return assembly versions or other versions of the runtime that may have been installed on the computer. +- Query the property to retrieve a object that identifies the version of the runtime that is currently executing the code. You can use the property to get the major release identifier (for example, "4" for version 4.0), the property to get the minor release identifier (for example, "0" for version 4.0), or the method to get the entire version string (for example, "4.0.30319.18010", as shown in the following code). This property returns a single value that reflects the version of the runtime that is currently executing the code; it does not return assembly versions or other versions of the runtime that may have been installed on the computer. - For the .NET Framework Versions 4, 4.5, 4.5.1, and 4.5.2, the property returns a object whose string representation has the form `4.0.30319.xxxxx`. For the .NET Framework 4.6 and later, it has the form `4.0.30319.42000`. + For the .NET Framework Versions 4, 4.5, 4.5.1, and 4.5.2, the property returns a object whose string representation has the form `4.0.30319.xxxxx`. For the .NET Framework 4.6 and later, it has the form `4.0.30319.42000`. > [!IMPORTANT] - > For the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] and later, we do not recommend using the property to detect the version of the runtime. Instead, we recommend that you query the registry, as described in the [To find .NET Framework versions by querying the registry in code (.NET Framework 4.5 and later)](#net_d) section earlier in this article. + > For the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] and later, we do not recommend using the property to detect the version of the runtime. Instead, we recommend that you query the registry, as described in the [To find .NET Framework versions by querying the registry in code (.NET Framework 4.5 and later)](#net_d) section earlier in this article. - Here's an example of querying the property for runtime version information: + Here's an example of querying the property for runtime version information: [!code-csharp[ListVersions](../../../samples/snippets/csharp/framework/migration-guide/versions-installed2.cs)] [!code-vb[ListVersions](../../../samples/snippets/visualbasic/framework/migration-guide/versions-installed2.vb)] diff --git a/docs/framework/migration-guide/mitigation-claimsidentity-constructor.md b/docs/framework/migration-guide/mitigation-claimsidentity-constructor.md index ad17243ded500..50abc1160d8fa 100644 --- a/docs/framework/migration-guide/mitigation-claimsidentity-constructor.md +++ b/docs/framework/migration-guide/mitigation-claimsidentity-constructor.md @@ -17,10 +17,10 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: ClaimsIdentity Constructor -Starting with the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], there is change in how the constructor sets the property. If the argument is a object, and the property of that object is not `null`, the property is attached by using the method. In the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], the property is attached as a existing reference. +Starting with the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], there is change in how the constructor sets the property. If the argument is a object, and the property of that object is not `null`, the property is attached by using the method. In the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], the property is attached as a existing reference. ## Impact - Starting with the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], the property of the new object is not equal to the property of the constructor's argument. In the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)] and earlier versions, it is equal. + Starting with the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], the property of the new object is not equal to the property of the constructor's argument. In the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)] and earlier versions, it is equal. ## Mitigation If this behavior is undesirable, you can restore the previous behavior by setting the `Switch.System.Security.ClaimsIdentity.SetActorAsReferenceWhenCopyingClaimsIdentity` switch in your application configuration file to `true`. This requires that you add the following to the [\](../../../docs/framework/configure-apps/file-schema/runtime/runtime-element.md) section of your web.config file: diff --git a/docs/framework/migration-guide/mitigation-culture-and-asynchronous-operations.md b/docs/framework/migration-guide/mitigation-culture-and-asynchronous-operations.md index 00eca51077abb..f9589847659d0 100644 --- a/docs/framework/migration-guide/mitigation-culture-and-asynchronous-operations.md +++ b/docs/framework/migration-guide/mitigation-culture-and-asynchronous-operations.md @@ -17,17 +17,17 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: Culture and Asynchronous Operations -For apps that target the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] and later versions, and are stored in a thread's , which flows across asynchronous operations. +For apps that target the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] and later versions, and are stored in a thread's , which flows across asynchronous operations. ## Impact - As a result of this change, changes to the or are reflected in tasks which are later run asynchronously. This differs from the behavior of previous .NET Framework versions, which would reset and to the system default in all asynchronous tasks. + As a result of this change, changes to the or are reflected in tasks which are later run asynchronously. This differs from the behavior of previous .NET Framework versions, which would reset and to the system default in all asynchronous tasks. ## Mitigation Apps affected by this change can work around it in either of two ways: -- By explicitly setting the desired or property as the first operation in an asynchronous task. +- By explicitly setting the desired or property as the first operation in an asynchronous task. -- By opting into the old behavior of not flowing and by adding the following `AppContextSwitchOverrides` element to the application's configuration file: +- By opting into the old behavior of not flowing and by adding the following `AppContextSwitchOverrides` element to the application's configuration file: ```xml @@ -37,7 +37,7 @@ For apps that target the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] an ``` -- By opting into the old behavior of not flowing and by setting the following compatibility switch programatically: +- By opting into the old behavior of not flowing and by setting the following compatibility switch programatically: ```csharp AppContext.SetSwitch("Switch.System.Globalization.NoAsyncCurrentCulture", true); diff --git a/docs/framework/migration-guide/mitigation-culture-and-dispatcher-operations-in-wpf-apps.md b/docs/framework/migration-guide/mitigation-culture-and-dispatcher-operations-in-wpf-apps.md index 68eb17937a3d7..1f469b9fa77ae 100644 --- a/docs/framework/migration-guide/mitigation-culture-and-dispatcher-operations-in-wpf-apps.md +++ b/docs/framework/migration-guide/mitigation-culture-and-dispatcher-operations-in-wpf-apps.md @@ -17,17 +17,17 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: Culture and Dispatcher Operations in WPF Apps -In apps that target the .NET Framework 4.6 and the .NET Framework 4.6.1, changes to the or properties that are made within a are lost at the end of that dispatcher operation. Similarly, changes to or made outside of a dispatcher operation may not be reflected when that operation executes. +In apps that target the .NET Framework 4.6 and the .NET Framework 4.6.1, changes to the or properties that are made within a are lost at the end of that dispatcher operation. Similarly, changes to or made outside of a dispatcher operation may not be reflected when that operation executes. - This is due to a change in that causes the and to be stored in the execution context. WPF dispatcher operations store the execution context used to begin the operation and restore the previous context when the operation is completed. Because and are now part of that context, changes to them within a dispatcher operation are not persisted outside of the operation. + This is due to a change in that causes the and to be stored in the execution context. WPF dispatcher operations store the execution context used to begin the operation and restore the previous context when the operation is completed. Because and are now part of that context, changes to them within a dispatcher operation are not persisted outside of the operation. ## Impact - Practically, this means that changes to the and properties may not flow between WPF UI callbacks and other code in a WPF application. + Practically, this means that changes to the and properties may not flow between WPF UI callbacks and other code in a WPF application. ## Mitigation Apps affected by this change may work around it in either of two ways: -- By storing the desired or in a field and checking in all operation bodies (including UI event callback handlers) that the correct or is set. +- By storing the desired or in a field and checking in all operation bodies (including UI event callback handlers) that the correct or is set. - Because the change to only affects WPF apps that target the .NET Framework 4.6 or the .NET Framework 4.6.1, this change can be avoided by targeting the .NET Framework 4.5.2 or by targeting a version of the .NET Framework starting with 4.6.2. diff --git a/docs/framework/migration-guide/mitigation-custom-imessagefilter-prefiltermessage-implementations.md b/docs/framework/migration-guide/mitigation-custom-imessagefilter-prefiltermessage-implementations.md index deb976718eea1..88f75a2227785 100644 --- a/docs/framework/migration-guide/mitigation-custom-imessagefilter-prefiltermessage-implementations.md +++ b/docs/framework/migration-guide/mitigation-custom-imessagefilter-prefiltermessage-implementations.md @@ -16,7 +16,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: Custom IMessageFilter.PreFilterMessage Implementations -In Windows Forms apps that target versions of the .NET Framework starting with the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], a custom implementation can safely filter messages when the method is called if the implementation: +In Windows Forms apps that target versions of the .NET Framework starting with the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], a custom implementation can safely filter messages when the method is called if the implementation: - Does one or both of the following: @@ -24,12 +24,12 @@ In Windows Forms apps that target versions of the .NET Framework starting with t - Removes a message filter by calling the method. method. -- **And** pumps messages by calling the method. +- **And** pumps messages by calling the method. ## Impact This change only affects Windows Forms apps that target versions of the .NET Framework starting with the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)]. - For Windows Forms apps that target previous versions of the .NET Framework, such implementations in some cases throw an exception when the method is called + For Windows Forms apps that target previous versions of the .NET Framework, such implementations in some cases throw an exception when the method is called ## Mitigation If this change is undesirable, apps that target the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)] or a later version can opt out of it by adding the following configuration setting to the [\](../../../docs/framework/configure-apps/file-schema/runtime/runtime-element.md) section of the app’s configuration file: diff --git a/docs/framework/migration-guide/mitigation-deserialization-of-objects-across-app-domains.md b/docs/framework/migration-guide/mitigation-deserialization-of-objects-across-app-domains.md index 721d4fffd31f6..9a24e0f51660d 100644 --- a/docs/framework/migration-guide/mitigation-deserialization-of-objects-across-app-domains.md +++ b/docs/framework/migration-guide/mitigation-deserialization-of-objects-across-app-domains.md @@ -23,7 +23,7 @@ In some cases, when an app uses two or more app domains with different applicati 1. An app uses two or more app domains with different application bases. -2. Some types are explicitly added to the by calling a method such as or . These types are not marked as serializable and are not stored in the global assembly cache. +2. Some types are explicitly added to the by calling a method such as or . These types are not marked as serializable and are not stored in the global assembly cache. 3. Later, code running in the non-default app domain tries to read a value from a configuration file or use XML to deserialize an object. diff --git a/docs/framework/migration-guide/mitigation-eventsource-writeevent-method-calls.md b/docs/framework/migration-guide/mitigation-eventsource-writeevent-method-calls.md index 97f15a96ed0b3..a45aa236ed851 100644 --- a/docs/framework/migration-guide/mitigation-eventsource-writeevent-method-calls.md +++ b/docs/framework/migration-guide/mitigation-eventsource-writeevent-method-calls.md @@ -16,7 +16,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: EventSource.WriteEvent Method Calls -The [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] enforces a contract between an ETW event method in a class that is derived from and the method of its base class. The ETW event method must pass the method the event ID followed by the same arguments that were passed to the event method. +The [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] enforces a contract between an ETW event method in a class that is derived from and the method of its base class. The ETW event method must pass the method the event ID followed by the same arguments that were passed to the event method. ## Impact An ETW event method defined in the following way breaks the contract: diff --git a/docs/framework/migration-guide/mitigation-horizontal-scrolling-and-virtualization.md b/docs/framework/migration-guide/mitigation-horizontal-scrolling-and-virtualization.md index c5c73ef9a2212..9549bd07c5a87 100644 --- a/docs/framework/migration-guide/mitigation-horizontal-scrolling-and-virtualization.md +++ b/docs/framework/migration-guide/mitigation-horizontal-scrolling-and-virtualization.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: Horizontal Scrolling and Virtualization -This change applies to an that does its own virtualization in the direction orthogonal to the main scrolling direction. (The chief example is a control with set to `true`.) The outcome of certain horizontal scrolling operations has been changed to produce results that are more intuitive and more analogous to the results of comparable vertical operations. The specific operations include **Scroll Here** and **Right Edge**, to use the names from the menu obtained by right-clicking a horizontal scrollbar. Both of these compute a candidate offset and call . After scrolling to the new offset, the definition of "here" or "right edge" may have changed because newly de-virtualized content has changed the value of . +This change applies to an that does its own virtualization in the direction orthogonal to the main scrolling direction. (The chief example is a control with set to `true`.) The outcome of certain horizontal scrolling operations has been changed to produce results that are more intuitive and more analogous to the results of comparable vertical operations. The specific operations include **Scroll Here** and **Right Edge**, to use the names from the menu obtained by right-clicking a horizontal scrollbar. Both of these compute a candidate offset and call . After scrolling to the new offset, the definition of "here" or "right edge" may have changed because newly de-virtualized content has changed the value of . ## Description of the change Prior to the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], the scroll operation simply uses the candidate offset, even though it may not be "here" or at the "right edge" any more. This results in effects like "bouncing" the scroll thumb, best illustrated by example. Suppose a control has set to 1000 and set to 200. A scroll to "Right Edge" uses candidate offset 1000 - 200 = 800. While scrolling to that offset, new columns are de-virtualized; let's suppose they are very wide, so that the changes to 2000. The scroll ends with =800, and the thumb "bounces" back to near the middle of the scrollbar -- precisely at 800/2000 = 40%. @@ -25,10 +25,10 @@ This change applies to an that does Starting with the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], a new candidate offset is recomputed when this situation occurs. (This is how vertical scrolling works already.) ## Impact - The change produces a more predictable and intuitive experience for the end user, but it could also affect any app that depends on the exact value of after a horizontal scroll, whether invoked by the end user or by an explicit call to . + The change produces a more predictable and intuitive experience for the end user, but it could also affect any app that depends on the exact value of after a horizontal scroll, whether invoked by the end user or by an explicit call to . ## Mitigation - An app that uses a predicted value for should be changed to retrieve the actual value (and the value of ) after any horizontal scroll that could change due to de-virtualization. + An app that uses a predicted value for should be changed to retrieve the actual value (and the value of ) after any horizontal scroll that could change due to de-virtualization. ## See Also [Runtime Changes](../../../docs/framework/migration-guide/runtime-changes-in-the-net-framework-4-6-2.md) diff --git a/docs/framework/migration-guide/mitigation-long-path-support.md b/docs/framework/migration-guide/mitigation-long-path-support.md index 09fa7eb4981ba..558a19b7d1664 100644 --- a/docs/framework/migration-guide/mitigation-long-path-support.md +++ b/docs/framework/migration-guide/mitigation-long-path-support.md @@ -22,7 +22,7 @@ Starting with apps that target the [!INCLUDE[net_v462](../../../includes/net-v46 ## Impact Apps recompiled to target the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] and that previously threw a automatically because a path exceeded 260 characters will now throw a only under the following conditions: -- The length of the path is greater than (32,767) characters. +- The length of the path is greater than (32,767) characters. - The operating system returns `COR_E_PATHTOOLONG` or its equivalent. diff --git a/docs/framework/migration-guide/mitigation-memberdescriptor-equals.md b/docs/framework/migration-guide/mitigation-memberdescriptor-equals.md index fbdbfe2d3b6fd..577bd367c13e6 100644 --- a/docs/framework/migration-guide/mitigation-memberdescriptor-equals.md +++ b/docs/framework/migration-guide/mitigation-memberdescriptor-equals.md @@ -17,15 +17,15 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: MemberDescriptor.Equals -Starting with apps that target the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], the implementation of the method has changed. Because the `System.ComponentModel.EventDescriptor.Equals` and `System.ComponentModel.PropertyDescriptor.Equals` methods inherit the base class implementation, the change also affects these methods. +Starting with apps that target the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], the implementation of the method has changed. Because the `System.ComponentModel.EventDescriptor.Equals` and `System.ComponentModel.PropertyDescriptor.Equals` methods inherit the base class implementation, the change also affects these methods. - In apps that target versions of the .NET Framework prior to [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], a portion of the method's test for equality incorrectly compared the property of one object with the property of the other. Starting with apps that target the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], the method compares the property of the two objects. + In apps that target versions of the .NET Framework prior to [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], a portion of the method's test for equality incorrectly compared the property of one object with the property of the other. Starting with apps that target the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], the method compares the property of the two objects. ## Impact - This change correctly implements the test for equality for objects and should have minimal impact. + This change correctly implements the test for equality for objects and should have minimal impact. ## Mitigation - Two workarounds are available if your app targets the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] or a later version of the .NET Framework and it depends on the method sometimes returning `false` when member descriptors are equivalent: + Two workarounds are available if your app targets the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] or a later version of the .NET Framework and it depends on the method sometimes returning `false` when member descriptors are equivalent: - You can opt out of this change without modifying your source code by adding the following to the [\](../../../docs/framework/configure-apps/file-schema/runtime/runtime-element.md) section of your app.config file: @@ -35,7 +35,7 @@ Starting with apps that target the [!INCLUDE[net_v462](../../../includes/net-v46 ``` -- You can modify your source code to restore the previous behavior by manually comparing the and properties after calling the method, as the following code fragment does. +- You can modify your source code to restore the previous behavior by manually comparing the and properties after calling the method, as the following code fragment does. ```csharp if (memberDescriptor1.Equals(memberDescriptor2) & diff --git a/docs/framework/migration-guide/mitigation-new-64-bit-jit-compiler.md b/docs/framework/migration-guide/mitigation-new-64-bit-jit-compiler.md index 2ec7ab1d75427..89fb8ce42fddc 100644 --- a/docs/framework/migration-guide/mitigation-new-64-bit-jit-compiler.md +++ b/docs/framework/migration-guide/mitigation-new-64-bit-jit-compiler.md @@ -37,7 +37,7 @@ Starting with the .NET Framework 4.6, the runtime includes a new 64-bit JIT comp - Under certain conditions, the comparison of values with their high bit set is incorrect if optimization is enabled. -- Under certain conditions, particularly when initializing array values, memory initialization by the IL instruction may initialize memory with an incorrect value. This can result either in an unhandled exception or incorrect output. +- Under certain conditions, particularly when initializing array values, memory initialization by the IL instruction may initialize memory with an incorrect value. This can result either in an unhandled exception or incorrect output. - Under certain rare conditions, a conditional bit test can return the incorrect value or throw an exception if compiler optimizations are enabled. diff --git a/docs/framework/migration-guide/mitigation-path-colon-checks.md b/docs/framework/migration-guide/mitigation-path-colon-checks.md index 726fe803630a3..1b30a6a728d32 100644 --- a/docs/framework/migration-guide/mitigation-path-colon-checks.md +++ b/docs/framework/migration-guide/mitigation-path-colon-checks.md @@ -20,14 +20,14 @@ manager: "wpickett" Starting with apps that target the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], a number of changes were made to support previously unsupported paths (both in terms of length and format). In particular, checks for the proper drive separator syntax (the colon) were made more correct. ## Impact - These changes block some URI paths the and methods previously supported. + These changes block some URI paths the and methods previously supported. ## Mitigation - To work around the problem of a previously acceptable path that is no longer supported by the and methods, you can do the following: + To work around the problem of a previously acceptable path that is no longer supported by the and methods, you can do the following: - Manually remove the scheme from a URL. For example, remove `file://` from a URL. -- Pass the URI to a constructor, and retrieve the value of the property. +- Pass the URI to a constructor, and retrieve the value of the property. - Opt out of the new path normalization by setting the `Switch.System.IO.UseLegacyPathHandling` switch to `true`. diff --git a/docs/framework/migration-guide/mitigation-png-frames-in-icon-objects.md b/docs/framework/migration-guide/mitigation-png-frames-in-icon-objects.md index 6c5a31464c992..e8b732ba43f1c 100644 --- a/docs/framework/migration-guide/mitigation-png-frames-in-icon-objects.md +++ b/docs/framework/migration-guide/mitigation-png-frames-in-icon-objects.md @@ -16,9 +16,9 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: PNG Frames in Icon Objects -Starting with the .NET Framework 4.6, the method successfully converts icons with PNG frames into objects. +Starting with the .NET Framework 4.6, the method successfully converts icons with PNG frames into objects. - In apps that target the .NET Framework 4.5.2 and earlier versions, the method throws an exception if the object has PNG frames. + In apps that target the .NET Framework 4.5.2 and earlier versions, the method throws an exception if the object has PNG frames. ## Impact This change affects apps that are recompiled to target the .NET Framework 4.6 and that implement special handling for the that is thrown when an object has PNG frames. When running under the .NET Framework 4.6, the conversion is successful, an is no longer thrown, and therefore the exception handler is no longer invoked. diff --git a/docs/framework/migration-guide/mitigation-pool-blocking-period.md b/docs/framework/migration-guide/mitigation-pool-blocking-period.md index 1a6712a984b2f..3c54adc7d7704 100644 --- a/docs/framework/migration-guide/mitigation-pool-blocking-period.md +++ b/docs/framework/migration-guide/mitigation-pool-blocking-period.md @@ -28,7 +28,7 @@ The connection pool blocking period has been removed for connections to Azure SQ This change allows the connection open attempt to be retried immediately for Azure SQL databases, thereby improving the performance of cloud-enabled apps. ## Mitigation - For apps that are adversely affected by this change, the connection pool blocking period can be configured by setting the new property. The value of the property is a member of the enumeration that can take either of three values: + For apps that are adversely affected by this change, the connection pool blocking period can be configured by setting the new property. The value of the property is a member of the enumeration that can take either of three values: - `PoolBlockingPeriod.AlwaysBlock` diff --git a/docs/framework/migration-guide/mitigation-product-versioning.md b/docs/framework/migration-guide/mitigation-product-versioning.md index 9a927d365ed88..81c04b621b871 100644 --- a/docs/framework/migration-guide/mitigation-product-versioning.md +++ b/docs/framework/migration-guide/mitigation-product-versioning.md @@ -27,7 +27,7 @@ In the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] and later, product v - The and attributes for managed assemblies have values in the form `4.6.X.0` for the .NET Framework 4.6 and its point releases, and `4.7.X.0` for the .NET Framework 4.7. -- In the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)], 4.6.1, 4.6.2, and 4.7, the property returns the fixed version string `4.0.30319.42000`. In the .NET Framework 4, 4.5, 4.5.1, and 4.5.2, it returns version strings in the format `4.0.30319.xxxxx` (for example, "4.0.30319.18010"). Note that we do not recommend application code taking any new dependency on the property. +- In the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)], 4.6.1, 4.6.2, and 4.7, the property returns the fixed version string `4.0.30319.42000`. In the .NET Framework 4, 4.5, 4.5.1, and 4.5.2, it returns version strings in the format `4.0.30319.xxxxx` (for example, "4.0.30319.18010"). Note that we do not recommend application code taking any new dependency on the property. ### Handling the product versioning changes In general, applications should depend on the recommended techniques for detecting such things as the runtime version of the .NET Framework and the installation directory: @@ -39,9 +39,9 @@ In the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] and later, product v > [!IMPORTANT] > The subkey name is `NET Framework Setup`, not `.NET Framework Setup`. -- To determine the directory path to the .NET Framework common language runtime, call the method. +- To determine the directory path to the .NET Framework common language runtime, call the method. -- To get the CLR version, call the method. For the .NET Framework 4 and its point releases (the .NET Framework 4.5, 4.5.1, 4.5.2, and [!INCLUDE[net_v46](../../../includes/net-v46-md.md)], 4.6.1, 4.6.2, and 4.7), it returns the string `v4.0.30319`. +- To get the CLR version, call the method. For the .NET Framework 4 and its point releases (the .NET Framework 4.5, 4.5.1, 4.5.2, and [!INCLUDE[net_v46](../../../includes/net-v46-md.md)], 4.6.1, 4.6.2, and 4.7), it returns the string `v4.0.30319`. ## See Also [Runtime Changes](../../../docs/framework/migration-guide/runtime-changes-in-the-net-framework-4-6.md) diff --git a/docs/framework/migration-guide/mitigation-tls-protocols.md b/docs/framework/migration-guide/mitigation-tls-protocols.md index e60ad9261bef2..ece49daba0db4 100644 --- a/docs/framework/migration-guide/mitigation-tls-protocols.md +++ b/docs/framework/migration-guide/mitigation-tls-protocols.md @@ -16,7 +16,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: TLS Protocols -Starting with the .NET Framework 4.6, the and classes are allowed to use one of the following three protocols: Tls1.0, Tls1.1, or Tls 1.2. The SSL3.0 protocol and RC4 cipher are not supported. +Starting with the .NET Framework 4.6, the and classes are allowed to use one of the following three protocols: Tls1.0, Tls1.1, or Tls 1.2. The SSL3.0 protocol and RC4 cipher are not supported. ## Impact This change affects: diff --git a/docs/framework/migration-guide/mitigation-wcf-services-and-certificate-authentication.md b/docs/framework/migration-guide/mitigation-wcf-services-and-certificate-authentication.md index a6e1159c10577..b43ee5d504e4a 100644 --- a/docs/framework/migration-guide/mitigation-wcf-services-and-certificate-authentication.md +++ b/docs/framework/migration-guide/mitigation-wcf-services-and-certificate-authentication.md @@ -53,7 +53,7 @@ The .NET Framework 4.6 adds TLS 1.1 and TLS 1.2 to the WCF SSL protocol default ``` -- If the binding is dynamically configured in source code, update the property to use TLS 1.1 () or an earlier version of the protocol in the source code. +- If the binding is dynamically configured in source code, update the property to use TLS 1.1 () or an earlier version of the protocol in the source code. > [!CAUTION] > This workaround is not recommended, since a certificate with the MD5 hash algorithm is considered insecure. diff --git a/docs/framework/migration-guide/mitigation-x509certificateclaimset-findclaims-method.md b/docs/framework/migration-guide/mitigation-x509certificateclaimset-findclaims-method.md index 511d4c7f61efc..3ecc040314f6c 100644 --- a/docs/framework/migration-guide/mitigation-x509certificateclaimset-findclaims-method.md +++ b/docs/framework/migration-guide/mitigation-x509certificateclaimset-findclaims-method.md @@ -16,12 +16,12 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: X509CertificateClaimSet.FindClaims Method -Starting with apps that target the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], the method will attempt to match the `claimType` argument with all the DNS entries in its SAN field. +Starting with apps that target the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], the method will attempt to match the `claimType` argument with all the DNS entries in its SAN field. ## Impact This change only affects apps that target versions of the .NET Framework starting with the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)]. - For apps that target previous versions of the .NET Framework, the method attempts to match the `claimType` argument only with the last DNS entry. + For apps that target previous versions of the .NET Framework, the method attempts to match the `claimType` argument only with the last DNS entry. ## Mitigation If this change is undesirable, apps that target versions of the .NET Framework starting with the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)] can opt out of it by adding the following configuration setting to the [\](../../../docs/framework/configure-apps/file-schema/runtime/runtime-element.md) section of the app’s configuration file: diff --git a/docs/framework/migration-guide/mitigation-ziparchiveentry-fullname-path-separator.md b/docs/framework/migration-guide/mitigation-ziparchiveentry-fullname-path-separator.md index 76422dc5fedfe..dfbe4c43b65e4 100644 --- a/docs/framework/migration-guide/mitigation-ziparchiveentry-fullname-path-separator.md +++ b/docs/framework/migration-guide/mitigation-ziparchiveentry-fullname-path-separator.md @@ -23,7 +23,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Mitigation: ZipArchiveEntry.FullName Path Separator -Starting with apps that target the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], the path separator used in the property has changed from the backslash ("\\") used in previous versions of the .NET Framework to a forward slash ("/"). objects are created by calling one of the overloads of the method. +Starting with apps that target the [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], the path separator used in the property has changed from the backslash ("\\") used in previous versions of the .NET Framework to a forward slash ("/"). objects are created by calling one of the overloads of the method. ## Impact The change brings the .NET implementation into conformity with section 4.4.17.1 of the [.ZIP File Format Specification](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT) and allows .ZIP archives to be decompressed on non-Windows systems. diff --git a/docs/framework/migration-guide/net-framework-4-migration-issues.md b/docs/framework/migration-guide/net-framework-4-migration-issues.md index 58f634482203d..b40c9eed367e8 100644 --- a/docs/framework/migration-guide/net-framework-4-migration-issues.md +++ b/docs/framework/migration-guide/net-framework-4-migration-issues.md @@ -257,7 +257,7 @@ Namespaces: , , class now inherits from instead of . The following properties are now dependency properties:

*
*
*

This change results in the following:

* An object is now frozen when it is registered instead of remaining mutable.
* You cannot access instance-level objects from multiple threads, due to the restrictions of the class.
* You cannot mutate class-level input bindings after their registration, due to the restrictions of the class.
* You cannot specify input bindings on command instances that are created in a View-Model. | Create separate instances of an class on separate threads if bindings are to be mutable, or freeze them otherwise. Do not mutate a class-level static after it has been registered. | | **Browser applications** | WPF Browser applications (.XBAP) now process key events just like stand-alone WPF applications so that objects receive routed key events in the correct order. | None. | | **Dead key combinations** | WPF obfuscates dead keys, which produce no visible character, but instead indicates that the key is to be combined with the next letter key to produce one character. The key input events, such as the event, report when a key is a dead key by setting the property to the value. This is usually expected behavior because applications usually do not intend to respond to keyboard input that creates a combined character. | Applications that expect to read keys that were part of combined characters can get the now obfuscated key by using the property. | -| **Focus manager** | When the method is passed an element that has the [IsFocusScope](https://msdn.microsoft.com/library/system.windows.input.focusmanager.isfocusscope.aspx) attached property set to `true`, the method returns an element that is the last keyboard-focused element within that focus scope if and only if the returned element belongs to the same object as the element that is passed to the method. | None. | +| **Focus manager** | When the method is passed an element that has the [IsFocusScope](https://msdn.microsoft.com/library/system.windows.input.focusmanager.isfocusscope.aspx) attached property set to `true`, the method returns an element that is the last keyboard-focused element within that focus scope if and only if the returned element belongs to the same object as the element that is passed to the method. | None. | ### UI Automation diff --git a/docs/framework/migration-guide/version-compatibility.md b/docs/framework/migration-guide/version-compatibility.md index 7484640d5c26b..3cc858acc4ba5 100644 --- a/docs/framework/migration-guide/version-compatibility.md +++ b/docs/framework/migration-guide/version-compatibility.md @@ -42,7 +42,7 @@ Backward compatibility means that an app that was developed for a particular ver ## Version compatibility for components An app can control the version of the .NET Framework on which it runs, but a component cannot. Components and class libraries are loaded in the context of a particular app, and therefore automatically run on the version of the .NET Framework that the app runs on. - Because of this restriction, compatibility guarantees are especially important for components. Starting with the .NET Framework 4, you can specify the degree to which a component is expected to remain compatible across multiple versions by applying the attribute to that component. Tools can use this attribute to detect potential violations of the compatibility guarantee in future versions of a component. + Because of this restriction, compatibility guarantees are especially important for components. Starting with the .NET Framework 4, you can specify the degree to which a component is expected to remain compatible across multiple versions by applying the attribute to that component. Tools can use this attribute to detect potential violations of the compatibility guarantee in future versions of a component. ## Backward compatibility and the .NET Framework 4.5 The .NET Framework 4.5 and its point releases (4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, and 4.7) are backward-compatible with apps that were built with earlier versions of the .NET Framework. In other words, apps and components built with previous versions will work without modification on the .NET Framework 4.5. However, by default, apps run on the version of the common language runtime for which they were developed, so you may have to provide a configuration file to enable your app to run on the .NET Framework 4.5. For more information, see the [Version compatibility for apps](#Apps) section earlier in this article. diff --git a/docs/framework/migration-guide/versions-and-dependencies.md b/docs/framework/migration-guide/versions-and-dependencies.md index 2df11f1e6b76e..0c09b3f9c35d0 100644 --- a/docs/framework/migration-guide/versions-and-dependencies.md +++ b/docs/framework/migration-guide/versions-and-dependencies.md @@ -52,9 +52,9 @@ Each version of the .NET Framework contains the common language runtime (CLR), t ## Targeting and Running .NET Framework apps for version 4.5 and later The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] is an in-place update that replaces the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] on your computer, and similarly, the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] 4.5.2, 4.6, 4.6.1, 4.6.2, and 4.7 are in-place updates to the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], which means that they use the same runtime version, but the assembly versions are updated and include new types and members. After you install one of these updates, your [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], or [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] apps should continue to run without requiring recompilation. However, the reverse is not true. We do not recommend running apps that target a later version of the .NET Framework on the an earlier version of the .NET Framework. For example, we do not recommend that you run an app the targets the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] on the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. The following guidelines apply: -- In Visual Studio, you can choose the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] as the target framework for a project (this sets the property) to compile the project as a [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] assembly or executable. This assembly or executable can then be used on any computer that has the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, or 4.7 installed. +- In Visual Studio, you can choose the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] as the target framework for a project (this sets the property) to compile the project as a [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] assembly or executable. This assembly or executable can then be used on any computer that has the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, or 4.7 installed. -- In Visual Studio, you can choose the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] as the target framework for a project (this sets the property) to compile the project as a [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] assembly or executable. This assembly or executable should be run only on computers that have the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] or a later version of the .NET Framework installed. An executable that targets the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] will be blocked from running on a computer that only has an earlier version of the .NET Framework, such as the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], installed, and the user will be prompted to install the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)]. In addition, the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] assemblies should not be called from an app that targets an earlier version of the .NET Framework, such as the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] . +- In Visual Studio, you can choose the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] as the target framework for a project (this sets the property) to compile the project as a [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] assembly or executable. This assembly or executable should be run only on computers that have the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] or a later version of the .NET Framework installed. An executable that targets the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] will be blocked from running on a computer that only has an earlier version of the .NET Framework, such as the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], installed, and the user will be prompted to install the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)]. In addition, the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)] assemblies should not be called from an app that targets an earlier version of the .NET Framework, such as the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] . The[!INCLUDE[net_v451](../../../includes/net-v451-md.md)] and [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] are used here only as examples. This principle applies to any app that targets an a later version of the .NET Framework than the one installed on the system on which it is running. diff --git a/docs/framework/misc/code-access-security-policy-compatibility-and-migration.md b/docs/framework/misc/code-access-security-policy-compatibility-and-migration.md index 297f76b979e6e..8cc45e6160669 100644 --- a/docs/framework/misc/code-access-security-policy-compatibility-and-migration.md +++ b/docs/framework/misc/code-access-security-policy-compatibility-and-migration.md @@ -54,25 +54,25 @@ manager: "wpickett" Examples of these are: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- ## Implicit Use @@ -80,27 +80,27 @@ manager: "wpickett" Here are some examples. The obsolete overloads are those that take as a parameter: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- ## Errors and Warnings - The obsolete types and members produce the following error messages when they are used. Note that the type itself is not obsolete. + The obsolete types and members produce the following error messages when they are used. Note that the type itself is not obsolete. Compile-time warning: @@ -116,24 +116,24 @@ manager: "wpickett" ### Determining an Assembly’s Trust Level CAS policy is often used to determine an assembly’s or application domain’s permission grant set or trust level. The [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] exposes the following useful properties that do not need to resolve security policy: -- +- -- +- -- +- -- +- ### Application Domain Sandboxing - The method is typically used for sandboxing the assemblies in an application domain. The [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] exposes members that do not have to use for this purpose. For more information, see [How to: Run Partially Trusted Code in a Sandbox](../../../docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). + The method is typically used for sandboxing the assemblies in an application domain. The [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] exposes members that do not have to use for this purpose. For more information, see [How to: Run Partially Trusted Code in a Sandbox](../../../docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). ### Determining a Safe or Reasonable Permission Set for Partially Trusted Code - Hosts often need to determine the permissions that are appropriate for sandboxing hosted code. Before the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], CAS policy provided a way to do this with the method. As a replacement, [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] provides the method, which returns a safe, standard permission set for the provided evidence. + Hosts often need to determine the permissions that are appropriate for sandboxing hosted code. Before the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], CAS policy provided a way to do this with the method. As a replacement, [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)] provides the method, which returns a safe, standard permission set for the provided evidence. ### Non-Sandboxing Scenarios: Overloads for Assembly Loads - The reason for using an assembly load overload might be to use parameters that are not otherwise available, instead of sandboxing the assembly. Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], assembly load overloads that do not require a object as a parameter, for example, , enable this scenario. + The reason for using an assembly load overload might be to use parameters that are not otherwise available, instead of sandboxing the assembly. Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], assembly load overloads that do not require a object as a parameter, for example, , enable this scenario. - If you want to sandbox an assembly, use the overload. + If you want to sandbox an assembly, use the overload. ## Compatibility: Using the CAS Policy Legacy Option diff --git a/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md b/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md index 7a4b91bd07058..e0f8b10467894 100644 --- a/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md +++ b/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md @@ -35,7 +35,7 @@ manager: "wpickett" An is an effective way of providing a sandbox for managed applications. Application domains that are used for running partially trusted code have permissions that define the protected resources that are available when running within that . Code that runs inside the is bound by the permissions associated with the and is allowed to access only the specified resources. The also includes a array that is used to identify assemblies that are to be loaded as fully trusted. This enables the creator of an to start a new sandboxed domain that allows specific helper assemblies to be fully trusted. Another option for loading assemblies as fully trusted is to place them in the global assembly cache; however, that will load assemblies as fully trusted in all application domains created on that computer. The list of strong names supports a per- decision that provides more restrictive determination. - You can use the method overload to specify the permission set for applications that run in a sandbox. This overload enables you to specify the exact level of code access security you want. Assemblies that are loaded into an by using this overload can either have the specified grant set only, or can be fully trusted. The assembly is granted full trust if it is in the global assembly cache or listed in the `fullTrustAssemblies` (the ) array parameter. Only assemblies known to be fully trusted should be added to the `fullTrustAssemblies` list. + You can use the method overload to specify the permission set for applications that run in a sandbox. This overload enables you to specify the exact level of code access security you want. Assemblies that are loaded into an by using this overload can either have the specified grant set only, or can be fully trusted. The assembly is granted full trust if it is in the global assembly cache or listed in the `fullTrustAssemblies` (the ) array parameter. Only assemblies known to be fully trusted should be added to the `fullTrustAssemblies` list. The overload has the following signature: @@ -125,7 +125,7 @@ AppDomain.CreateDomain( string friendlyName, - You can use a code base that points to a location that does not contain your assembly. - - You can do the creation under an for full-trust (), which enables you to create an instance of a critical class. (This happens whenever your assembly has no transparency markings and is loaded as fully trusted.) Therefore, you have to be careful to create only code that you trust with this function, and we recommend that you create only instances of fully trusted classes in the new application domain. + - You can do the creation under an for full-trust (), which enables you to create an instance of a critical class. (This happens whenever your assembly has no transparency markings and is loaded as fully trusted.) Therefore, you have to be careful to create only code that you trust with this function, and we recommend that you create only instances of fully trusted classes in the new application domain. ``` ObjectHandle handle = Activator.CreateInstanceFrom( diff --git a/docs/framework/misc/securing-wrapper-code.md b/docs/framework/misc/securing-wrapper-code.md index 14d559f5b0348..9fac812c51e20 100644 --- a/docs/framework/misc/securing-wrapper-code.md +++ b/docs/framework/misc/securing-wrapper-code.md @@ -61,19 +61,19 @@ manager: "wpickett" To help prevent such security holes, the common language runtime extends the check into a full stack-walking demand on any indirect call to a method, constructor, property, or event protected by a **LinkDemand**. This protection incurs some performance costs and changes the semantics of the security check; the full stack-walk demand might fail where the faster, one-level check would have passed. ## Assembly loading wrappers - Several methods used to load managed code, including , load assemblies with the evidence of the caller. If you wrap any of these methods, the security system could use your code's permission grant, instead of the permissions of the caller to your wrapper, to load the assemblies. You should not allow less-trusted code to load code that is granted higher permissions than those of the caller to your wrapper. + Several methods used to load managed code, including , load assemblies with the evidence of the caller. If you wrap any of these methods, the security system could use your code's permission grant, instead of the permissions of the caller to your wrapper, to load the assemblies. You should not allow less-trusted code to load code that is granted higher permissions than those of the caller to your wrapper. Any code that has full trust or significantly higher trust than a potential caller (including an Internet-permissions-level caller) could weaken security in this way. If your code has a public method that takes a byte array and passes it to **Assembly.Load**, thereby creating an assembly on the caller's behalf, it might break security. This issue applies to the following API elements: -- +- -- +- -- +- -- +- ## Demand vs. LinkDemand Declarative security offers two kinds of security checks that are similar but perform very different checks. You should understand both forms because the wrong choice can result in weak security or performance loss. diff --git a/docs/framework/net-native/apis-that-rely-on-reflection.md b/docs/framework/net-native/apis-that-rely-on-reflection.md index fd54e4ea5c84c..1e90d6925d986 100644 --- a/docs/framework/net-native/apis-that-rely-on-reflection.md +++ b/docs/framework/net-native/apis-that-rely-on-reflection.md @@ -19,7 +19,7 @@ manager: "wpickett" In some cases, the use of reflection in code isn't obvious, and so the [!INCLUDE[net_native](../../../includes/net-native-md.md)] tool chain doesn't preserve metadata that is needed at run time. This topic covers some common APIs or common programming patterns that aren't considered part of the reflection API but that rely on reflection to execute successfully. If you use them in your source code, you can add information about them to the runtime directives (.rd.xml) file so that calls to these APIs do not throw a [MissingMetadataException](../../../docs/framework/net-native/missingmetadataexception-class-net-native.md) exception or some other exception at run time. ## Type.MakeGenericType method - You can dynamically instantiate a generic type `AppClass` by calling the method by using code like this: + You can dynamically instantiate a generic type `AppClass` by calling the method by using code like this: [!code-csharp[ProjectN#1](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn/cs/type_makegenerictype1.cs#1)] @@ -29,9 +29,9 @@ In some cases, the use of reflection in code isn't obvious, and so the [!INCLUDE ``` - This allows the method call to succeed and return a valid object. + This allows the method call to succeed and return a valid object. - But even when you add metadata for the uninstantiated generic type, calling the method throws a [MissingMetadataException](../../../docs/framework/net-native/missingmetadataexception-class-net-native.md) exception: + But even when you add metadata for the uninstantiated generic type, calling the method throws a [MissingMetadataException](../../../docs/framework/net-native/missingmetadataexception-class-net-native.md) exception: ``` This operation cannot be carried out as metadata for the following type was removed for performance reasons: @@ -39,14 +39,14 @@ This operation cannot be carried out as metadata for the following type was remo App1.AppClass`1. ``` - You can add the following run-time directive to the runtime directives file to add `Activate` metadata for the specific instantiation over `AppClass` of : + You can add the following run-time directive to the runtime directives file to add `Activate` metadata for the specific instantiation over `AppClass` of : ```xml ``` - Each different instantiation over `AppClass` requires a separate directive if it is being created with the method and not used statically. + Each different instantiation over `AppClass` requires a separate directive if it is being created with the method and not used statically. ## MethodInfo.MakeGenericMethod method Given a class `Class1` with a generic method `GetMethod(T t)`, `GetMethod` can be invoked through reflection by using code like this: @@ -59,7 +59,7 @@ App1.AppClass`1. - `Browse` metadata for the method you want to call. If it is a public method, adding public `Browse` metadata for the containing type includes the method, too. -- Dynamic metadata for the method you want to call, so that the reflection invocation delegate is not removed by the [!INCLUDE[net_native](../../../includes/net-native-md.md)] tool chain. If dynamic metadata is missing for the method, the following exception is thrown when the method is called: +- Dynamic metadata for the method you want to call, so that the reflection invocation delegate is not removed by the [!INCLUDE[net_native](../../../includes/net-native-md.md)] tool chain. If dynamic metadata is missing for the method, the following exception is thrown when the method is called: ``` MakeGenericMethod() cannot create this generic method instantiation because the instantiation was not metadata-enabled: 'App1.Class1.GenMethod(Int32)'. @@ -76,7 +76,7 @@ App1.AppClass`1. A `MethodInstantiation` directive is required for each different instantiation of the method that is dynamically invoked, and the `Arguments` element is updated to reflect each different instantiation argument. ## Array.CreateInstance and Type.MakeTypeArray methods - The following example calls the and methods on a type, `Class1`. + The following example calls the and methods on a type, `Class1`. [!code-csharp[ProjectN#3](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn/cs/array1.cs#3)] diff --git a/docs/framework/net-native/application-element-net-native.md b/docs/framework/net-native/application-element-net-native.md index 439381f89df88..7b929ebb70b89 100644 --- a/docs/framework/net-native/application-element-net-native.md +++ b/docs/framework/net-native/application-element-net-native.md @@ -47,9 +47,9 @@ Serves as a container for application-wide types and type members whose metadata |`Browse`|Reflection|Optional attribute. Controls querying for information about or enumerating the types, but does not enable any dynamic access at run time.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional Attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional Attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional Attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional Attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional Attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional Attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional Attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional Attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional Attribute. Controls policy for marshaling structures to native code.| diff --git a/docs/framework/net-native/assembly-element-net-native.md b/docs/framework/net-native/assembly-element-net-native.md index 7652b958c8ae7..179b67dcc686f 100644 --- a/docs/framework/net-native/assembly-element-net-native.md +++ b/docs/framework/net-native/assembly-element-net-native.md @@ -46,9 +46,9 @@ Applies runtime reflection policy to all the types in a specified assembly. |`Browse`|Reflection|Optional attribute. Controls querying for information about or enumerating the types in the assembly, but does not enable any dynamic access at run time.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling structures to native code.| @@ -57,7 +57,7 @@ Applies runtime reflection policy to all the types in a specified assembly. |Value|Description| |-----------|-----------------| -|*assembly_name*|The simple name of the assembly, without its file extension. This attribute corresponds to the property. For example, the name of an assembly named Extensions.dll is "Extensions".

You can also specify the literal string `*Application*` to apply policy to all assemblies in your app package, whether those assemblies are loaded or not. `*Application*` never applies policy to .NET Framework assemblies.| +|*assembly_name*|The simple name of the assembly, without its file extension. This attribute corresponds to the property. For example, the name of an assembly named Extensions.dll is "Extensions".

You can also specify the literal string `*Application*` to apply policy to all assemblies in your app package, whether those assemblies are loaded or not. `*Application*` never applies policy to .NET Framework assemblies.| ## All other attributes diff --git a/docs/framework/net-native/attributeimplies-element-net-native.md b/docs/framework/net-native/attributeimplies-element-net-native.md index 27d38b81b90c6..c08bf79b67e31 100644 --- a/docs/framework/net-native/attributeimplies-element-net-native.md +++ b/docs/framework/net-native/attributeimplies-element-net-native.md @@ -44,9 +44,9 @@ Defines policy for code elements the containing attribute is applied to. |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling value types to native code.| @@ -67,7 +67,7 @@ Defines policy for code elements the containing attribute is applied to. |[\](../../../docs/framework/net-native/type-element-net-native.md)|Applies reflection policy to a type and all its members.| ## Remarks - The `` element is used if its containing type is an attribute (that is, a class derived from ). If the attribute is applied to a particular program element, the policy defined by the `` element applies to that program element. + The `` element is used if its containing type is an attribute (that is, a class derived from ). If the attribute is applied to a particular program element, the policy defined by the `` element applies to that program element. The reflection, serialization, and interop attributes are all optional, although at least one should be present. diff --git a/docs/framework/net-native/example-handling-exceptions-when-binding-data.md b/docs/framework/net-native/example-handling-exceptions-when-binding-data.md index 4744459ef69c1..20da149e541c8 100644 --- a/docs/framework/net-native/example-handling-exceptions-when-binding-data.md +++ b/docs/framework/net-native/example-handling-exceptions-when-binding-data.md @@ -43,7 +43,7 @@ Windows_UI_Xaml!DirectUI::PropertyPathListener::ConnectPathStep+0x113 ``` ## What was the app doing? - At the base of the stack, frames from the [Windows.UI.Xaml](http://msdn.microsoft.com/library/windows/apps/windows.ui.xaml.aspx) namespace indicate that the XAML rendering engine was running. The use of the method indicates a reflection-based lookup of a property’s value on the type whose metadata was removed. + At the base of the stack, frames from the [Windows.UI.Xaml](http://msdn.microsoft.com/library/windows/apps/windows.ui.xaml.aspx) namespace indicate that the XAML rendering engine was running. The use of the method indicates a reflection-based lookup of a property’s value on the type whose metadata was removed. The first step in providing a metadata directive would be to add `serialize` metadata for the type so that its properties are all accessible: diff --git a/docs/framework/net-native/example-troubleshooting-dynamic-programming.md b/docs/framework/net-native/example-troubleshooting-dynamic-programming.md index f1ba8c57e4396..75904cfebba67 100644 --- a/docs/framework/net-native/example-troubleshooting-dynamic-programming.md +++ b/docs/framework/net-native/example-troubleshooting-dynamic-programming.md @@ -54,9 +54,9 @@ AppViewModel.Current.LayoutVM.PageMap A likely candidate for the failure is that `App.Core.ViewModels.Layout.LayoutApplicationVM` is missing metadata because it's in a different namespace. - In this case, adding a runtime directive for `App.Core.ViewModels` resolved the issue. The root cause was an API call to the method that returned **null**, and the app silently ignored the problem until a crash occurred. + In this case, adding a runtime directive for `App.Core.ViewModels` resolved the issue. The root cause was an API call to the method that returned **null**, and the app silently ignored the problem until a crash occurred. - In dynamic programming, a good practice when using reflection APIs under [!INCLUDE[net_native](../../../includes/net-native-md.md)] is to use the overloads that throw an exception on failure. + In dynamic programming, a good practice when using reflection APIs under [!INCLUDE[net_native](../../../includes/net-native-md.md)] is to use the overloads that throw an exception on failure. ## Is this an isolated case? Other issues might also arise when using `App.Core.ViewModels`. You must decide whether it’s worth identifying and fixing each missing metadata exception, or saving time and adding directives for a larger class of types. Here, adding `dynamic` metadata for `App.Core.ViewModels` might be the best approach if the resulting size increase of the output binary isn’t an issue. diff --git a/docs/framework/net-native/genericparameter-element-net-native.md b/docs/framework/net-native/genericparameter-element-net-native.md index 3a625aecb17fb..eba92a66bf358 100644 --- a/docs/framework/net-native/genericparameter-element-net-native.md +++ b/docs/framework/net-native/genericparameter-element-net-native.md @@ -46,9 +46,9 @@ Applies policy to the parameter type of a generic type or method. |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling value types to native code.| diff --git a/docs/framework/net-native/getting-started-with-net-native.md b/docs/framework/net-native/getting-started-with-net-native.md index 8f4bf9b29a390..553b923b4693a 100644 --- a/docs/framework/net-native/getting-started-with-net-native.md +++ b/docs/framework/net-native/getting-started-with-net-native.md @@ -63,11 +63,11 @@ Whether you are writing a new Windows app for Windows 10 or you are migrating an **Methods that rely on reflection** In some cases, the use of reflection in code is not obvious. Some common APIs or programming patterns aren't considered part of the reflection API but rely on reflection to execute successfully. This includes the following type instantiation and method construction methods: -- The method +- The method -- The and methods +- The and methods -- The method. +- The method. For more information, see [APIs That Rely on Reflection](../../../docs/framework/net-native/apis-that-rely-on-reflection.md). diff --git a/docs/framework/net-native/impliestype-element-net-native.md b/docs/framework/net-native/impliestype-element-net-native.md index 70e890440a18f..99631977e7fed 100644 --- a/docs/framework/net-native/impliestype-element-net-native.md +++ b/docs/framework/net-native/impliestype-element-net-native.md @@ -46,9 +46,9 @@ Applies policy to a type, if that policy has been applied to the containing type |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling value types to native code.| diff --git a/docs/framework/net-native/library-element-net-native.md b/docs/framework/net-native/library-element-net-native.md index e656522f96adf..7eb06d2d7779c 100644 --- a/docs/framework/net-native/library-element-net-native.md +++ b/docs/framework/net-native/library-element-net-native.md @@ -40,7 +40,7 @@ Defines the assembly that contains types and type members whose metadata is avai |Value|Description| |-----------|-----------------| -|*assembly_name*|The simple name of the assembly, without its file extension. This attribute corresponds to the property. For example, the name of an assembly named Extensions.dll is "Extensions". See the Remarks section for a special form of *assembly_name* that supports conditional inclusion of metadata from the assembly.| +|*assembly_name*|The simple name of the assembly, without its file extension. This attribute corresponds to the property. For example, the name of an assembly named Extensions.dll is "Extensions". See the Remarks section for a special form of *assembly_name* that supports conditional inclusion of metadata from the assembly.| ### Child Elements diff --git a/docs/framework/net-native/method-element-net-native.md b/docs/framework/net-native/method-element-net-native.md index 59e29de7a737b..1836f6c1878e8 100644 --- a/docs/framework/net-native/method-element-net-native.md +++ b/docs/framework/net-native/method-element-net-native.md @@ -81,7 +81,7 @@ Applies runtime reflection policy to a constructor or method. You cannot define the runtime reflection policy for a constructor by using the `` element. Instead, use the `Activate` attribute of the [\](../../../docs/framework/net-native/assembly-element-net-native.md), [\](../../../docs/framework/net-native/namespace-element-net-native.md), [\](../../../docs/framework/net-native/type-element-net-native.md), or [\](../../../docs/framework/net-native/typeinstantiation-element-net-native.md) element. ## Example - The `Stringify` method in the following example is a general-purpose formatting method that uses reflection to convert an object to its string representation. In addition to calling the object's default `ToString` method, the method can produce a formatted result string by passing an object's `ToString` method a format string, an implementation, or both. It can also call one of the overloads that converts a number to its binary, hexadecimal, or octal representation. + The `Stringify` method in the following example is a general-purpose formatting method that uses reflection to convert an object to its string representation. In addition to calling the object's default `ToString` method, the method can produce a formatted result string by passing an object's `ToString` method a format string, an implementation, or both. It can also call one of the overloads that converts a number to its binary, hexadecimal, or octal representation. [!code-csharp[ProjectN_Reflection#7](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn_reflection/cs/method1.cs#7)] diff --git a/docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md b/docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md index fe139035c53f9..27681dfd7c9fd 100644 --- a/docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md +++ b/docs/framework/net-native/migrating-your-windows-store-app-to-net-native.md @@ -33,7 +33,7 @@ manager: "wpickett" - Exceptions, such as , that are thrown by the JIT compiler when an app runs on the common language runtime (CLR) generally result in compile-time errors when processed by [!INCLUDE[net_native](../../../includes/net-native-md.md)]. -- Don't call the method from an app's UI thread. This can result in a deadlock on [!INCLUDE[net_native](../../../includes/net-native-md.md)]. +- Don't call the method from an app's UI thread. This can result in a deadlock on [!INCLUDE[net_native](../../../includes/net-native-md.md)]. - Don't rely on static class constructor invocation ordering. In [!INCLUDE[net_native](../../../includes/net-native-md.md)], the invocation order is different from the order on the standard runtime. (Even with the standard runtime, you shouldn't rely on the order of execution of static class constructors.) @@ -43,7 +43,7 @@ manager: "wpickett" [!code-csharp[ProjectN#8](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn/cs/compat1.cs#8)] -- In some cases, [!INCLUDE[net_native](../../../includes/net-native-md.md)] provides different implementations of .NET Framework class libraries. An object returned from a method will always implement the members of the returned type. However, since its backing implementation is different, you may not be able to cast it to the same set of types as you could on other .NET Framework platforms. For example, in some cases, you may not be able to cast the interface object returned by methods such as or to `T[]`. +- In some cases, [!INCLUDE[net_native](../../../includes/net-native-md.md)] provides different implementations of .NET Framework class libraries. An object returned from a method will always implement the members of the returned type. However, since its backing implementation is different, you may not be able to cast it to the same set of types as you could on other .NET Framework platforms. For example, in some cases, you may not be able to cast the interface object returned by methods such as or to `T[]`. - The WinInet cache isn't enabled by default on .NET for Windows Store apps, but it is on [!INCLUDE[net_native](../../../includes/net-native-md.md)]. This improves performance but has working set implications. No developer action is necessary. @@ -62,7 +62,7 @@ manager: "wpickett" The default configuration for [!INCLUDE[net_native](../../../includes/net-native-md.md)] is sufficient for most developers, but some developers might want to fine- tune their configurations by using a runtime directives (.rd.xml) file. In addition, in some cases, the [!INCLUDE[net_native](../../../includes/net-native-md.md)] compiler is unable to determine which metadata must be available for reflection and relies on hints, particularly in the following cases: -- Some constructs like and can't be determined statically. +- Some constructs like and can't be determined statically. - Because the compiler can't determine the instantiations, a generic type that you want to reflect on has to be specified by runtime directives. This isn't just because all code must be included, but because reflection on generic types can form an infinite cycle (for example, when a generic method is invoked on a generic type). @@ -79,13 +79,13 @@ manager: "wpickett" - Private reflection over types and members in the .NET Framework class library is not supported. You can, however, reflect over your own private types and members, as well as types and members in third-party libraries. -- The property correctly returns `false` for a object that represents a return value. In the .NET for Windows Store apps, it returns `true`. Intermediate language (IL) doesn’t support this directly, and interpretation is left to the language. +- The property correctly returns `false` for a object that represents a return value. In the .NET for Windows Store apps, it returns `true`. Intermediate language (IL) doesn’t support this directly, and interpretation is left to the language. - Public members on the and structures aren't supported. These types are supported only for LINQ, expression trees, and static array initialization. -- and include hidden members in base classes and thus may be overridden without explicit overrides. This is also true of other [RuntimeReflectionExtensions.GetRuntime*](http://msdn.microsoft.com/library/system.reflection.runtimereflectionextensions_methods.aspx) methods. +- and include hidden members in base classes and thus may be overridden without explicit overrides. This is also true of other [RuntimeReflectionExtensions.GetRuntime*](http://msdn.microsoft.com/library/system.reflection.runtimereflectionextensions_methods.aspx) methods. -- and don't fail when you try to create certain combinations (for example, an array of byrefs). +- and don't fail when you try to create certain combinations (for example, an array of byrefs). - You can't use reflection to invoke members that have pointer parameters. @@ -93,7 +93,7 @@ manager: "wpickett" - When the argument count is wrong and the type of one of the arguments is incorrect, [!INCLUDE[net_native](../../../includes/net-native-md.md)] throws an instead of a . -- Binary serialization of exceptions is generally not supported. As a result, non-serializable objects can be added to the dictionary. +- Binary serialization of exceptions is generally not supported. As a result, non-serializable objects can be added to the dictionary. ## Unsupported scenarios and APIs @@ -111,7 +111,7 @@ manager: "wpickett" ### General development differences **Value types** -- If you override the and methods for a value type, don't call the base class implementations. In .NET for Windows Store apps, these methods rely on reflection. At compile time, [!INCLUDE[net_native](../../../includes/net-native-md.md)] generates an implementation that doesn't rely on runtime reflection. This means that if you don't override these two methods, they will work as expected, because [!INCLUDE[net_native](../../../includes/net-native-md.md)] generates the implementation at compile time. However, overriding these methods but calling the base class implementation results in an exception. +- If you override the and methods for a value type, don't call the base class implementations. In .NET for Windows Store apps, these methods rely on reflection. At compile time, [!INCLUDE[net_native](../../../includes/net-native-md.md)] generates an implementation that doesn't rely on runtime reflection. This means that if you don't override these two methods, they will work as expected, because [!INCLUDE[net_native](../../../includes/net-native-md.md)] generates the implementation at compile time. However, overriding these methods but calling the base class implementation results in an exception. - Value types larger than one megabyte aren't supported. @@ -119,11 +119,11 @@ manager: "wpickett" **Arrays** -- Arrays with a lower bound other than zero aren't supported. Typically, these arrays are created by calling the overload. +- Arrays with a lower bound other than zero aren't supported. Typically, these arrays are created by calling the overload. -- Dynamic creation of multidimensional arrays isn't supported. Such arrays are typically created by calling an overload of the method that includes a `lengths` parameter, or by calling the method. +- Dynamic creation of multidimensional arrays isn't supported. Such arrays are typically created by calling an overload of the method that includes a `lengths` parameter, or by calling the method. -- Multidimensional arrays that have four or more dimensions aren't supported; that is, their property value is four or greater. Use [jagged arrays](~/docs/csharp/programming-guide/arrays/jagged-arrays.md) (an array of arrays) instead. For example, `array[x,y,z]` is invalid, but `array[x][y][z]` isn't. +- Multidimensional arrays that have four or more dimensions aren't supported; that is, their property value is four or greater. Use [jagged arrays](~/docs/csharp/programming-guide/arrays/jagged-arrays.md) (an array of arrays) instead. For example, `array[x,y,z]` is invalid, but `array[x][y][z]` isn't. - Variance for multidimensional arrays isn't supported and causes an exception at run time. @@ -145,7 +145,7 @@ manager: "wpickett" **Resources** - The use of localized resources with the class isn't supported. The property doesn't define localized resources. + The use of localized resources with the class isn't supported. The property doesn't define localized resources. **Delegates** @@ -157,11 +157,11 @@ manager: "wpickett" **Miscellaneous APIs** -- The property throws a exception if a attribute isn't applied to the type. The GUID is used primarily for COM support. +- The property throws a exception if a attribute isn't applied to the type. The GUID is used primarily for COM support. -- The method correctly parses strings that contain short dates in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. However, it doesn't maintain compatibility with the changes in date and time parsing described in the Microsoft Knowledge Base articles [KB2803771](http://support.microsoft.com/kb/2803771) and [KB2803755](http://support.microsoft.com/kb/2803755). +- The method correctly parses strings that contain short dates in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. However, it doesn't maintain compatibility with the changes in date and time parsing described in the Microsoft Knowledge Base articles [KB2803771](http://support.microsoft.com/kb/2803771) and [KB2803755](http://support.microsoft.com/kb/2803755). -- `("E")` is correctly rounded in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. In some versions of the CLR, the result string is truncated instead of rounded. +- `("E")` is correctly rounded in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. In some versions of the CLR, the result string is truncated instead of rounded. ### HttpClient differences @@ -175,33 +175,33 @@ manager: "wpickett" **Proxy** - The [HttpBaseProtocolFilter](http://msdn.microsoft.com/library/windows/apps/windows.web.http.filters.httpbaseprotocolfilter.aspx) class doesn’t support configuring or overriding the proxy on a per-request basis. This means that all requests on [!INCLUDE[net_native](../../../includes/net-native-md.md)] use the system-configured proxy server or no proxy server, depending on the value of the property. In .NET for Windows Store apps, the proxy server is defined by the property. On [!INCLUDE[net_native](../../../includes/net-native-md.md)], setting the to a value other than `null` throws a exception. The property returns `false` on [!INCLUDE[net_native](../../../includes/net-native-md.md)], whereas it returns `true` in the standard .NET Framework for Windows Store apps. + The [HttpBaseProtocolFilter](http://msdn.microsoft.com/library/windows/apps/windows.web.http.filters.httpbaseprotocolfilter.aspx) class doesn’t support configuring or overriding the proxy on a per-request basis. This means that all requests on [!INCLUDE[net_native](../../../includes/net-native-md.md)] use the system-configured proxy server or no proxy server, depending on the value of the property. In .NET for Windows Store apps, the proxy server is defined by the property. On [!INCLUDE[net_native](../../../includes/net-native-md.md)], setting the to a value other than `null` throws a exception. The property returns `false` on [!INCLUDE[net_native](../../../includes/net-native-md.md)], whereas it returns `true` in the standard .NET Framework for Windows Store apps. **Automatic redirection** - The [HttpBaseProtocolFilter](http://msdn.microsoft.com/library/windows/apps/windows.web.http.filters.httpbaseprotocolfilter.aspx) class doesn't allow the maximum number of automatic redirections to be configured. The value of the property is 50 by default in the standard .NET for Windows Store apps and can be modified. On [!INCLUDE[net_native](../../../includes/net-native-md.md)], the value of this property is 10, and trying to modify it throws a exception. The property returns `false` on [!INCLUDE[net_native](../../../includes/net-native-md.md)], whereas it returns `true` in .NET for Windows Store apps. + The [HttpBaseProtocolFilter](http://msdn.microsoft.com/library/windows/apps/windows.web.http.filters.httpbaseprotocolfilter.aspx) class doesn't allow the maximum number of automatic redirections to be configured. The value of the property is 50 by default in the standard .NET for Windows Store apps and can be modified. On [!INCLUDE[net_native](../../../includes/net-native-md.md)], the value of this property is 10, and trying to modify it throws a exception. The property returns `false` on [!INCLUDE[net_native](../../../includes/net-native-md.md)], whereas it returns `true` in .NET for Windows Store apps. **Automatic decompression** - .NET for Windows Store apps allows you to set the property to , , both and , or . [!INCLUDE[net_native](../../../includes/net-native-md.md)] only supports together with , or . Trying to set the property to either or alone silently sets it to both and . + .NET for Windows Store apps allows you to set the property to , , both and , or . [!INCLUDE[net_native](../../../includes/net-native-md.md)] only supports together with , or . Trying to set the property to either or alone silently sets it to both and . **Cookies** - Cookie handling is performed simultaneously by and WinINet. Cookies from the are combined with cookies in the WinINet cookie cache. Removing a cookie from prevents from sending the cookie, but if the cookie was already seen by WinINet, and cookies weren't deleted by the user, WinINet sends it. It isn't possible to programmatically remove a cookie from WinINet by using the , , or API. Setting the property to `false` causes only to stop sending cookies; WinINet might still include its cookies in the request. + Cookie handling is performed simultaneously by and WinINet. Cookies from the are combined with cookies in the WinINet cookie cache. Removing a cookie from prevents from sending the cookie, but if the cookie was already seen by WinINet, and cookies weren't deleted by the user, WinINet sends it. It isn't possible to programmatically remove a cookie from WinINet by using the , , or API. Setting the property to `false` causes only to stop sending cookies; WinINet might still include its cookies in the request. **Credentials** - In .NET for Windows Store apps, the and properties work independently. Additionally, the property accepts any object that implements the interface. In [!INCLUDE[net_native](../../../includes/net-native-md.md)], setting the property to `true` causes the property to become `null`. In addition, the property can be set only to `null`, , or an object of type . Assigning any other object, the most popular of which is , to the property throws a . + In .NET for Windows Store apps, the and properties work independently. Additionally, the property accepts any object that implements the interface. In [!INCLUDE[net_native](../../../includes/net-native-md.md)], setting the property to `true` causes the property to become `null`. In addition, the property can be set only to `null`, , or an object of type . Assigning any other object, the most popular of which is , to the property throws a . **Other unsupported or unconfigurable features** In [!INCLUDE[net_native](../../../includes/net-native-md.md)]: -- The value of the property is always . In .NET for Windows Store apps, the default is . +- The value of the property is always . In .NET for Windows Store apps, the default is . -- The property isn't configurable. +- The property isn't configurable. -- The property is always `true`. In .NET for Windows Store apps, the default is `false`. +- The property is always `true`. In .NET for Windows Store apps, the default is `false`. - The `SetCookie2` header in responses is ignored as obsolete. @@ -215,74 +215,74 @@ manager: "wpickett" || |-| -|| -|| -|| -|| -|| -|| -|| -|| -|| - - is supported, but it throws an exception in some scenarios, such as when it is used with [IDispatch](http://msdn.microsoft.com/library/windows/apps/ms221608.aspx) or byref variants. +|| +|| +|| +|| +|| +|| +|| +|| +|| + + is supported, but it throws an exception in some scenarios, such as when it is used with [IDispatch](http://msdn.microsoft.com/library/windows/apps/ms221608.aspx) or byref variants. Deprecated APIs for [IDispatch](http://msdn.microsoft.com/library/windows/apps/ms221608.aspx) support: |Type|Member| |----------|------------| -||| -||| -||Attribute isn't supported| +||| +||| +||Attribute isn't supported| Deprecated APIs for classic COM events: || |-| -|| +|| || - Deprecated APIs in the interface, which isn't supported in [!INCLUDE[net_native](../../../includes/net-native-md.md)]: + Deprecated APIs in the interface, which isn't supported in [!INCLUDE[net_native](../../../includes/net-native-md.md)]: |Type|Member| |----------|------------| -||All members.| -||All members.| -||All members.| -||| +||All members.| +||All members.| +||All members.| +||| Other unsupported interop features: |Type|Member| |----------|------------| -||All members.| -||All members.| -||| -||| -||| -||| -||| +||All members.| +||All members.| +||| +||| +||| +||| +||| Rarely used marshalling APIs: |Type|Member| |----------|------------| -||| -||| -||| -||| -||| -||| -||| -||| -||| -||| +||| +||| +||| +||| +||| +||| +||| +||| +||| +||| **Platform invoke and COM interop compatibility** Most platform invoke and COM interop scenarios are still supported in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. In particular, all interoperability with Windows Runtime (WinRT) APIs and all marshaling required for the Windows Runtime is supported. This includes marshaling support for: -- Arrays (including ) +- Arrays (including ) - `BStr` @@ -332,9 +332,9 @@ manager: "wpickett" - Using classic COM events -- Implementing the interface on a managed type +- Implementing the interface on a managed type -- Implementing the [IDispatch](http://msdn.microsoft.com/library/windows/apps/ms221608.aspx) interface on a managed type through the attribute. However, note that you can't call COM objects through `IDispatch`, and your managed object can't implement `IDispatch`. +- Implementing the [IDispatch](http://msdn.microsoft.com/library/windows/apps/ms221608.aspx) interface on a managed type through the attribute. However, note that you can't call COM objects through `IDispatch`, and your managed object can't implement `IDispatch`. Using reflection to invoke a platform invoke method isn't supported. You can work around this limitation by wrapping the method call in another method and using reflection to call the wrapper instead. @@ -348,31 +348,31 @@ manager: "wpickett" || |-| -|| -|| -|| -|| -|| -|| -|| +|| +|| +|| +|| +|| +|| +|| || || || -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| **Visual Basic** @@ -380,31 +380,31 @@ manager: "wpickett" || |-| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| **Reflection Context (System.Reflection.Context namespace)** - The class isn't supported in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. + The class isn't supported in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. **RTC (System.Net.Http.Rtc)** - The class isn't supported in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. + The class isn't supported in [!INCLUDE[net_native](../../../includes/net-native-md.md)]. **Windows Communication Foundation (WCF) (System.ServiceModel.\*)** @@ -412,184 +412,184 @@ manager: "wpickett" || |-| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| -|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| +|| ### Differences in serializers The following differences concern serialization and deserialization with the , , and classes: @@ -610,31 +610,31 @@ manager: "wpickett" - fails to serialize or deserialize if the type of the serialized object is . -- All serializers (, , and ) fail to generate serialization code for type or for a type that contains . They display build-time errors instead. +- All serializers (, , and ) fail to generate serialization code for type or for a type that contains . They display build-time errors instead. - The following constructors of the serialization types aren't guaranteed to work as expected: - - + - - - + - - - + - - - + - - - + - - - + - - - + - - - + - - - + - - - + - - - + - - fails to generate code for a type that has methods attributed with any of the following attributes: diff --git a/docs/framework/net-native/missinginteropdataexception-class-net-native.md b/docs/framework/net-native/missinginteropdataexception-class-net-native.md index 50bb44f0a8eb9..ec3ac022859a7 100644 --- a/docs/framework/net-native/missinginteropdataexception-class-net-native.md +++ b/docs/framework/net-native/missinginteropdataexception-class-net-native.md @@ -41,15 +41,15 @@ manager: "wpickett" |Property|Description| |--------------|-----------------| -|`public IDictionary Data { get; }`|Gets a collection of key/value pairs that provide additional user-defined information about the exception. (Inherited from .)| -|`public string HelpLink { get; set; }`|Gets or sets a link to the help file associated with this exception. (Inherited from .)| -|`public int HResult { get; protected set; }`|Gets or sets the `HRESULT`, which is a coded numeric value that is assigned to a specific exception. (Inherited from .)| -|`public Exception InnerException { get; }`|Gets the exception that caused the current exception. (Inherited from .)| -|`public string Message { get; }`|Gets a message that describes the current exception. (Inherited from .)| +|`public IDictionary Data { get; }`|Gets a collection of key/value pairs that provide additional user-defined information about the exception. (Inherited from .)| +|`public string HelpLink { get; set; }`|Gets or sets a link to the help file associated with this exception. (Inherited from .)| +|`public int HResult { get; protected set; }`|Gets or sets the `HRESULT`, which is a coded numeric value that is assigned to a specific exception. (Inherited from .)| +|`public Exception InnerException { get; }`|Gets the exception that caused the current exception. (Inherited from .)| +|`public string Message { get; }`|Gets a message that describes the current exception. (Inherited from .)| |`public Type MissingType { get; private set; }`|Gets or sets the type whose data is missing.| -|`public string Source { get; set; }`|Gets or sets the name of the app or object that caused the error. (Inherited from .)| -|`public string StackTrace { get; }`|Gets a string representation of the immediate frames on the call stack. (Inherited from .)| -|`public MethodBase TargetSite { get; }`|Gets the method that threw the current exception. (Inherited from .)| +|`public string Source { get; set; }`|Gets or sets the name of the app or object that caused the error. (Inherited from .)| +|`public string StackTrace { get; }`|Gets a string representation of the immediate frames on the call stack. (Inherited from .)| +|`public MethodBase TargetSite { get; }`|Gets the method that threw the current exception. (Inherited from .)| ## Methods @@ -57,18 +57,18 @@ manager: "wpickett" |------------|-----------------| |`public bool Equals(Object obj)`|Determines whether the specified object is equal to the current object. (Inherited from .)| |`protected void Finalize()`|Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from .)| -|`public Exception GetBaseException()`|Returns the exception that is the root cause of one or more subsequent exceptions. (Inherited from .)| +|`public Exception GetBaseException()`|Returns the exception that is the root cause of one or more subsequent exceptions. (Inherited from .)| |`public int GetHashCode()`|Returns a hash code for a `MissingInteropDataException` instance. (Inherited from .)| -|`public void GetObjectData(SerializationInfo info, StreamingContext context)`|Sets a object with information about the exception. (Inherited from .)| -|`public Type GetType()`|Gets the runtime type of the current instance. (Inherited from .)| +|`public void GetObjectData(SerializationInfo info, StreamingContext context)`|Sets a object with information about the exception. (Inherited from .)| +|`public Type GetType()`|Gets the runtime type of the current instance. (Inherited from .)| |`protected Object MemberwiseClone()`|Creates a shallow copy of the current object. (Inherited from .)| -|`public string ToString()`|Returns the string representation of the current exception. (Inherited from .)| +|`public string ToString()`|Returns the string representation of the current exception. (Inherited from .)| ## Events |Event|Description| |-----------|-----------------| -|`protected event EventHandler SerializeObjectState`|Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception. (Inherited from .)| +|`protected event EventHandler SerializeObjectState`|Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception. (Inherited from .)| ## Usage Details The `MissingInteropDataException` exception is thrown when a method call to a COM or Windows Runtime component cannot be made successfully because type information isn't available. @@ -78,9 +78,9 @@ manager: "wpickett" > [!IMPORTANT] > Because this exception indicates that metadata needed by your application isn’t available at run time, you shouldn’t handle this exception in a `try`/`catch` block. Instead, you should diagnose the cause of the exception and eliminate it by adding the appropriate entry to a runtime directives file. - The `MissingInteropDataException` class contains a single unique member, the `MissingType` property, that indicates the type whose metadata is needed for a successful method call. All remaining members are inherited from the base class, . + The `MissingInteropDataException` class contains a single unique member, the `MissingType` property, that indicates the type whose metadata is needed for a successful method call. All remaining members are inherited from the base class, . ## See Also - + [MissingMetadataException Class](../../../docs/framework/net-native/missingmetadataexception-class-net-native.md) [Runtime Directives (rd.xml) Configuration File Reference](../../../docs/framework/net-native/runtime-directives-rd-xml-configuration-file-reference.md) diff --git a/docs/framework/net-native/missingmetadataexception-class-net-native.md b/docs/framework/net-native/missingmetadataexception-class-net-native.md index 024778b856383..f0ed4c0fd9737 100644 --- a/docs/framework/net-native/missingmetadataexception-class-net-native.md +++ b/docs/framework/net-native/missingmetadataexception-class-net-native.md @@ -43,34 +43,34 @@ manager: "wpickett" |Property|Description| |--------------|-----------------| -|`public IDictionary Data { get; }`|Gets a collection of key/value pairs that provide additional user-defined information about the exception. (Inherited from .)| -|`public string HelpLink { get; set; }`|Gets or sets a link to the help file associated with this exception. (Inherited from .)| -|`public int HResult { get; protected set; }`|Gets or sets the `HRESULT`, a coded numeric value that is assigned to a specific exception. (Inherited from .)| -|`public Exception InnerException { get; }`|Gets the exception that caused the current exception. (Inherited from .)| +|`public IDictionary Data { get; }`|Gets a collection of key/value pairs that provide additional user-defined information about the exception. (Inherited from .)| +|`public string HelpLink { get; set; }`|Gets or sets a link to the help file associated with this exception. (Inherited from .)| +|`public int HResult { get; protected set; }`|Gets or sets the `HRESULT`, a coded numeric value that is assigned to a specific exception. (Inherited from .)| +|`public Exception InnerException { get; }`|Gets the exception that caused the current exception. (Inherited from .)| |`public string Message { get; }`|Gets a message that describes the current exception. (Inherited from .)| -|`public string Source { get; set; }`|Gets or sets the name of the application or object that caused the error. (Inherited from .)| -|`public string StackTrace { get; }`|Gets a string representation of the immediate frames on the call stack. (Inherited from .)| -|`public MethodBase TargetSite { get; }`|Gets the method that threw the current exception. (Inherited from .)| +|`public string Source { get; set; }`|Gets or sets the name of the application or object that caused the error. (Inherited from .)| +|`public string StackTrace { get; }`|Gets a string representation of the immediate frames on the call stack. (Inherited from .)| +|`public MethodBase TargetSite { get; }`|Gets the method that threw the current exception. (Inherited from .)| |`public string TypeName { get; ]`|Gets the fully qualified name of the type whose metadata is missing. (Inherited from .)| ## Methods |Method|Description| |------------|-----------------| -|`public bool Equals(Object obj)`|Determines whether the specified object is equal to the current object. (Inherited from .)| +|`public bool Equals(Object obj)`|Determines whether the specified object is equal to the current object. (Inherited from .)| |`protected void Finalize()`|Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from .)| -|`public Exception GetBaseException()`|Returns the exception that is the root cause of one or more subsequent exceptions. (Inherited from .)| +|`public Exception GetBaseException()`|Returns the exception that is the root cause of one or more subsequent exceptions. (Inherited from .)| |`public int GetHashCode()`|Returns a hash code for a `MissingMetadataException` instance. (Inherited from .)| |`public void GetObjectData(SerializationInfo info, StreamingContext context)`|Sets a object with information about the exception. (Inherited from .)| -|`public Type GetType()`|Gets the runtime type of the current instance. (Inherited from .)| +|`public Type GetType()`|Gets the runtime type of the current instance. (Inherited from .)| |`protected Object MemberwiseClone()`|Creates a shallow copy of the current object. (Inherited from .)| -|`public string ToString()`|Returns the string representation of the current exception. (Inherited from .)| +|`public string ToString()`|Returns the string representation of the current exception. (Inherited from .)| ## Events |Event|Description| |-----------|-----------------| -|`protected event EventHandler SerializeObjectState`|Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception. (Inherited from .)| +|`protected event EventHandler SerializeObjectState`|Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception. (Inherited from .)| ## Usage Details The `MissingMetadataException` exception is thrown when reflection is used to access metadata that isn’t available in an assembly. @@ -86,7 +86,7 @@ manager: "wpickett" The `MissingMetadataException` class contains no unique members; all of its members are inherited from its base class, . ## See Also - + [MissingInteropDataException Class](../../../docs/framework/net-native/missinginteropdataexception-class-net-native.md) [MissingRuntimeArtifactException Class](../../../docs/framework/net-native/missingruntimeartifactexception-class-net-native.md) diff --git a/docs/framework/net-native/missingruntimeartifactexception-class-net-native.md b/docs/framework/net-native/missingruntimeartifactexception-class-net-native.md index e4bf408d18283..5cc9af7bd5324 100644 --- a/docs/framework/net-native/missingruntimeartifactexception-class-net-native.md +++ b/docs/framework/net-native/missingruntimeartifactexception-class-net-native.md @@ -43,14 +43,14 @@ manager: "wpickett" |Property|Description| |--------------|-----------------| -|`public IDictionary Data { get; }`|Gets a collection of key/value pairs that provide additional user-defined information about the exception. (Inherited from .)| -|`public string HelpLink { get; set; }`|Gets or sets a link to the help file associated with this exception. (Inherited from .)| -|`public int HResult { get; protected set; }`|Gets or sets the `HRESULT`, a coded numeric value that is assigned to a specific exception. (Inherited from .)| -|`public Exception InnerException { get; }`|Gets the exception that caused the current exception. (Inherited from .)| -|`public string Message { get; }`|Gets a message that describes the current exception. (Inherited from .)| -|`public string Source { get; set; }`|Gets or sets the name of the application or object that caused the error. (Inherited from .)| -|`public string StackTrace { get; }`|Gets a string representation of the immediate frames on the call stack. (Inherited from .)| -|`public MethodBase TargetSite { get; }`|Gets the method that threw the current exception. (Inherited from .)| +|`public IDictionary Data { get; }`|Gets a collection of key/value pairs that provide additional user-defined information about the exception. (Inherited from .)| +|`public string HelpLink { get; set; }`|Gets or sets a link to the help file associated with this exception. (Inherited from .)| +|`public int HResult { get; protected set; }`|Gets or sets the `HRESULT`, a coded numeric value that is assigned to a specific exception. (Inherited from .)| +|`public Exception InnerException { get; }`|Gets the exception that caused the current exception. (Inherited from .)| +|`public string Message { get; }`|Gets a message that describes the current exception. (Inherited from .)| +|`public string Source { get; set; }`|Gets or sets the name of the application or object that caused the error. (Inherited from .)| +|`public string StackTrace { get; }`|Gets a string representation of the immediate frames on the call stack. (Inherited from .)| +|`public MethodBase TargetSite { get; }`|Gets the method that threw the current exception. (Inherited from .)| ## Methods @@ -58,18 +58,18 @@ manager: "wpickett" |------------|-----------------| |`public bool Equals(Object obj)`|Determines whether the specified object is equal to the current object. (Inherited from .)| |`protected void Finalize()`|Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from .)| -|`public Exception GetBaseException()`|Returns the exception that is the root cause of one or more subsequent exceptions. (Inherited from .)| +|`public Exception GetBaseException()`|Returns the exception that is the root cause of one or more subsequent exceptions. (Inherited from .)| |`public int GetHashCode()`|Returns a hash code for a `MissingRuntimeArtifactException` instance. (Inherited from .)| -|`public void GetObjectData(SerializationInfo info, StreamingContext context)`|Sets a object with information about the exception. (Inherited from .)| -|`public Type GetType()`|Gets the runtime type of the current instance. (Inherited from .)| +|`public void GetObjectData(SerializationInfo info, StreamingContext context)`|Sets a object with information about the exception. (Inherited from .)| +|`public Type GetType()`|Gets the runtime type of the current instance. (Inherited from .)| |`protected Object MemberwiseClone()`|Creates a shallow copy of the current object. (Inherited from .)| -|`public string ToString()`|Returns the string representation of the current exception. (Inherited from .)| +|`public string ToString()`|Returns the string representation of the current exception. (Inherited from .)| ## Events |Event|Description| |-----------|-----------------| -|`protected event EventHandler SerializeObjectState`|Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception. (Inherited from .)| +|`protected event EventHandler SerializeObjectState`|Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception. (Inherited from .)| ## Usage Details The `MissingRuntimeArtifactException` exception is thrown when an attempt is made to instantiate a type or invoke a type member and, although the type or member's metadata is present, its implementation has been removed. diff --git a/docs/framework/net-native/namespace-element-net-native.md b/docs/framework/net-native/namespace-element-net-native.md index 4a1221d64b28e..d96b4d360a5d9 100644 --- a/docs/framework/net-native/namespace-element-net-native.md +++ b/docs/framework/net-native/namespace-element-net-native.md @@ -46,9 +46,9 @@ Applies runtime reflection policy to all the types in a specified namespace. |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling structures to native code.| diff --git a/docs/framework/net-native/net-native-and-compilation.md b/docs/framework/net-native/net-native-and-compilation.md index 3d5c7bbb52c54..ad8cedfd95702 100644 --- a/docs/framework/net-native/net-native-and-compilation.md +++ b/docs/framework/net-native/net-native-and-compilation.md @@ -45,7 +45,7 @@ Windows 8.1 applications and Windows Desktop applications that target the.NET Fr In the course of converting an app from IL to native code, the .NET Native tool chain performs operations like the following: -- For certain code paths, it replaces code that relies on reflection and metadata with static native code. For example, if a value type does not override the method, the default test for equality uses reflection to retrieve objects that represent the value type's fields, then compares the field values of two instances. When compiling to native code, the .NET Native tool chain replaces the reflection code and metadata with a static comparison of the field values. +- For certain code paths, it replaces code that relies on reflection and metadata with static native code. For example, if a value type does not override the method, the default test for equality uses reflection to retrieve objects that represent the value type's fields, then compares the field values of two instances. When compiling to native code, the .NET Native tool chain replaces the reflection code and metadata with a static comparison of the field values. - Where possible, it attempts to eliminate all metadata. diff --git a/docs/framework/net-native/parameter-element-net-native.md b/docs/framework/net-native/parameter-element-net-native.md index 6e3fc051c0f7b..b6f3a81f32603 100644 --- a/docs/framework/net-native/parameter-element-net-native.md +++ b/docs/framework/net-native/parameter-element-net-native.md @@ -46,9 +46,9 @@ Applies reflection policy to the type of the argument passed to a method. |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to WinRT and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling value types to native code.| diff --git a/docs/framework/net-native/reflection-and-net-native.md b/docs/framework/net-native/reflection-and-net-native.md index 24885a73f40cc..84f4e677256f2 100644 --- a/docs/framework/net-native/reflection-and-net-native.md +++ b/docs/framework/net-native/reflection-and-net-native.md @@ -27,7 +27,7 @@ In the .NET Framework, managed development supports metaprogramming through the > [!NOTE] > For an overview of the .NET Native compilation process that provides background on why a runtime directives file is needed, see [.NET Native and Compilation](../../../docs/framework/net-native/net-native-and-compilation.md). - In addition, [!INCLUDE[net_native](../../../includes/net-native-md.md)] doesn't allow you to reflect over private members of the .NET Framework class library. For example, a call to the property to retrieve the fields of a .NET Framework class library type returns only public or protected fields. + In addition, [!INCLUDE[net_native](../../../includes/net-native-md.md)] doesn't allow you to reflect over private members of the .NET Framework class library. For example, a call to the property to retrieve the fields of a .NET Framework class library type returns only public or protected fields. The following topics provide the conceptual and reference documentation that you need to support reflection and serialization in your apps: diff --git a/docs/framework/net-native/runtime-directives-rd-xml-configuration-file-reference.md b/docs/framework/net-native/runtime-directives-rd-xml-configuration-file-reference.md index cd4c339a68d61..2df5cbc74242f 100644 --- a/docs/framework/net-native/runtime-directives-rd-xml-configuration-file-reference.md +++ b/docs/framework/net-native/runtime-directives-rd-xml-configuration-file-reference.md @@ -161,11 +161,11 @@ A runtime directives (.rd.xml) file is an XML configuration file that specifies - `Serialize`. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and serialized by third-party libraries such as the Newtonsoft JSON serializer. -- `DataContractSerializer`. Controls policy for serialization that uses the class. +- `DataContractSerializer`. Controls policy for serialization that uses the class. -- `DataContractJsonSerializer`. Controls policy for JSON serialization that uses the class. +- `DataContractJsonSerializer`. Controls policy for JSON serialization that uses the class. -- `XmlSerializer`. Controls policy for XML serialization that uses the class. +- `XmlSerializer`. Controls policy for XML serialization that uses the class. - `MarshalObject`. Controls policy for marshaling reference types to WinRT and COM. @@ -390,7 +390,7 @@ A runtime directives (.rd.xml) file is an XML configuration file that specifies - If the method is generic, the types over which the method is instantiated are marked with the `Browse` policy. -- The method can be invoked by `MethodInfo.Invoke`, and delegate creation becomes possible by . +- The method can be invoked by `MethodInfo.Invoke`, and delegate creation becomes possible by . Applying the `Dynamic` policy to a field involves the following policy changes: @@ -411,7 +411,7 @@ A runtime directives (.rd.xml) file is an XML configuration file that specifies Applying the `Activation` policy to a method involves the following policy change: -- The constructor can be invoked by the and methods. For methods, the `Activation` policy affects constructors only. +- The constructor can be invoked by the and methods. For methods, the `Activation` policy affects constructors only. Applying the `Activation` policy to a field has no effect. diff --git a/docs/framework/net-native/serialization-and-metadata.md b/docs/framework/net-native/serialization-and-metadata.md index 39be006902938..1d7d2cdc8c073 100644 --- a/docs/framework/net-native/serialization-and-metadata.md +++ b/docs/framework/net-native/serialization-and-metadata.md @@ -56,7 +56,7 @@ If your app serializes and deserializes objects, you may need to add entries to ``` - Similarly, if you call a constructor such as and provide an array of additional objects to serialize, as in the following code, the [!INCLUDE[net_native](../../../includes/net-native-md.md)] compiler cannot resolve these types. + Similarly, if you call a constructor such as and provide an array of additional objects to serialize, as in the following code, the [!INCLUDE[net_native](../../../includes/net-native-md.md)] compiler cannot resolve these types. [!code-csharp[ProjectN#7](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn/cs/serialize1.cs#7)] diff --git a/docs/framework/net-native/subtypes-element-net-native.md b/docs/framework/net-native/subtypes-element-net-native.md index fa21cc3b74726..09bef57b45097 100644 --- a/docs/framework/net-native/subtypes-element-net-native.md +++ b/docs/framework/net-native/subtypes-element-net-native.md @@ -44,9 +44,9 @@ Applies runtime policy to all classes inherited from the containing type. |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling value types to native code.| @@ -89,7 +89,7 @@ Applies runtime policy to all classes inherited from the containing type. ``` - Because of the `` directive, the following code that instantiates a `Derived1` instance dynamically by calling the method executes successfully. The block variable here is a object in a blank Windows Store app. + Because of the `` directive, the following code that instantiates a `Derived1` instance dynamically by calling the method executes successfully. The block variable here is a object in a blank Windows Store app. [!code-csharp[ProjectN_Reflection#5](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn_reflection/cs/subtypes.cs#5)] diff --git a/docs/framework/net-native/type-element-net-native.md b/docs/framework/net-native/type-element-net-native.md index 53311e05668b3..75afdcbdf6197 100644 --- a/docs/framework/net-native/type-element-net-native.md +++ b/docs/framework/net-native/type-element-net-native.md @@ -46,9 +46,9 @@ Applies runtime policy to a particular type, such as a class or structure. |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling value types to native code.| @@ -99,10 +99,10 @@ Applies runtime policy to a particular type, such as a class or structure. A `` element of a generic type applies its policy to all instantiations that do not have their own policy. The policy of constructed generic types is defined by the [\](../../../docs/framework/net-native/typeinstantiation-element-net-native.md) element. - If the type is a generic type, its name is decorated by a grave accent symbol (\`) followed by its number of generic parameters. For example, the `Name` attribute of a `` element for the class appears as `Name="System.Collections.Generic.List`1"`. + If the type is a generic type, its name is decorated by a grave accent symbol (\`) followed by its number of generic parameters. For example, the `Name` attribute of a `` element for the class appears as `Name="System.Collections.Generic.List`1"`. ## Example - The following example uses reflection to display information about the fields, properties, and methods of the class. The variable `b` in the example is a [TextBlock](http://msdn.microsoft.com/library/windows/apps/windows.ui.xaml.controls.textblock.aspx) control. Because the example simply retrieves type information, the availability of metadata is controlled by the `Browse` policy setting. + The following example uses reflection to display information about the fields, properties, and methods of the class. The variable `b` in the example is a [TextBlock](http://msdn.microsoft.com/library/windows/apps/windows.ui.xaml.controls.textblock.aspx) control. Because the example simply retrieves type information, the availability of metadata is controlled by the `Browse` policy setting. [!code-csharp[ProjectN_Reflection#3](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn_reflection/cs/browsegenerictype1.cs#3)] @@ -120,11 +120,11 @@ Applies runtime policy to a particular type, such as a class or structure. ``` ## Example - The following example uses reflection to retrieve a object that represents the property. It then uses the method to retrieve the value of the seventh character in a string, and to display all the characters in the string. The variable `b` in the example is a [TextBlock](http://msdn.microsoft.com/library/windows/apps/windows.ui.xaml.controls.textblock.aspx) control. + The following example uses reflection to retrieve a object that represents the property. It then uses the method to retrieve the value of the seventh character in a string, and to display all the characters in the string. The variable `b` in the example is a [TextBlock](http://msdn.microsoft.com/library/windows/apps/windows.ui.xaml.controls.textblock.aspx) control. [!code-csharp[ProjectN_Reflection#1](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn_reflection/cs/propertyinfo1.cs#1)] - Because metadata for the object isn't available, the call to the method throws a exception at run time when compiled with the [!INCLUDE[net_native](../../../includes/net-native-md.md)] tool chain. To eliminate the exception and provide the necessary metadata, add the following `` element to the runtime directives file: + Because metadata for the object isn't available, the call to the method throws a exception at run time when compiled with the [!INCLUDE[net_native](../../../includes/net-native-md.md)] tool chain. To eliminate the exception and provide the necessary metadata, add the following `` element to the runtime directives file: ```xml diff --git a/docs/framework/net-native/typeinstantiation-element-net-native.md b/docs/framework/net-native/typeinstantiation-element-net-native.md index 6d873d53853cb..9bb5262b4893e 100644 --- a/docs/framework/net-native/typeinstantiation-element-net-native.md +++ b/docs/framework/net-native/typeinstantiation-element-net-native.md @@ -48,9 +48,9 @@ Applies runtime reflection policy to a constructed generic type. |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling structures to native code.| @@ -59,7 +59,7 @@ Applies runtime reflection policy to a constructed generic type. |Value|Description| |-----------|-----------------| -|*type_name*|The type name. If this `` element is the child of a [\](../../../docs/framework/net-native/namespace-element-net-native.md) element, a [\](../../../docs/framework/net-native/type-element-net-native.md) element, or another `` element, *type_name* can specify the name of the type without its namespace. Otherwise, *type_name* must include the fully qualified type name. The type name isn't decorated. For example, for a object, the `` element might appear as follows:

`\`| +|*type_name*|The type name. If this `` element is the child of a [\](../../../docs/framework/net-native/namespace-element-net-native.md) element, a [\](../../../docs/framework/net-native/type-element-net-native.md) element, or another `` element, *type_name* can specify the name of the type without its namespace. Otherwise, *type_name* must include the fully qualified type name. The type name isn't decorated. For example, for a object, the `` element might appear as follows:

`\`| ## Arguments attribute @@ -107,7 +107,7 @@ Applies runtime reflection policy to a constructed generic type. [!code-csharp[ProjectN_Reflection#2](../../../samples/snippets/csharp/VS_Snippets_CLR/projectn_reflection/cs/makegenerictype1.cs#2)] - After compilation with the [!INCLUDE[net_native](../../../includes/net-native-md.md)] tool chain, the example throws a [MissingMetadataException](../../../docs/framework/net-native/missingmetadataexception-class-net-native.md) exception on the line that calls the method. You can eliminate the exception and provide the necessary metadata by adding the following `` element to the runtime directives file: + After compilation with the [!INCLUDE[net_native](../../../includes/net-native-md.md)] tool chain, the example throws a [MissingMetadataException](../../../docs/framework/net-native/missingmetadataexception-class-net-native.md) exception on the line that calls the method. You can eliminate the exception and provide the necessary metadata by adding the following `` element to the runtime directives file: ```xml diff --git a/docs/framework/net-native/typeparameter-element-net-native.md b/docs/framework/net-native/typeparameter-element-net-native.md index 601b839a2c504..28147cb7bb3e2 100644 --- a/docs/framework/net-native/typeparameter-element-net-native.md +++ b/docs/framework/net-native/typeparameter-element-net-native.md @@ -46,9 +46,9 @@ Applies policy to the type represented by a Type argument passed to a method. |`Browse`|Reflection|Optional attribute. Controls querying for information about program elements, but does not enable any runtime access.| |`Dynamic`|Reflection|Optional attribute. Controls runtime access to all type members, including constructors, methods, fields, properties, and events, to enable dynamic programming.| |`Serialize`|Serialization|Optional attribute. Controls runtime access to constructors, fields, and properties, to enable type instances to be serialized and deserialized by libraries such as the Newtonsoft JSON serializer.| -|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| -|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| -|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| +|`DataContractSerializer`|Serialization|Optional attribute. Controls policy for serialization that uses the class.| +|`DataContractJsonSerializer`|Serialization|Optional attribute. Controls policy for JSON serialization that uses the class.| +|`XmlSerializer`|Serialization|Optional attribute. Controls policy for XML serialization that uses the class.| |`MarshalObject`|Interop|Optional attribute. Controls policy for marshaling reference types to Windows Runtime and COM.| |`MarshalDelegate`|Interop|Optional attribute. Controls policy for marshaling delegate types as function pointers to native code.| |`MarshalStructure`|Interop|Optional attribute. Controls policy for marshaling value types to native code.| diff --git a/docs/framework/network-programming/best-practices-for-system-net-classes.md b/docs/framework/network-programming/best-practices-for-system-net-classes.md index 07e219ed151c5..7546e5fc3d10b 100644 --- a/docs/framework/network-programming/best-practices-for-system-net-classes.md +++ b/docs/framework/network-programming/best-practices-for-system-net-classes.md @@ -33,7 +33,7 @@ The following recommendations will help you use the classes contained in and . -- The number of connections opened to an Internet resource can have a significant impact on network performance and throughput. **System.Net** uses two connections per application per host by default. Setting the property in the for your application can increase this number for a particular host. Setting the property can increase this default for all hosts. +- The number of connections opened to an Internet resource can have a significant impact on network performance and throughput. **System.Net** uses two connections per application per host by default. Setting the property in the for your application can increase this number for a particular host. Setting the property can increase this default for all hosts. - When writing socket-level protocols, try to use or whenever possible instead of writing directly to a . These two client classes encapsulate the creation of TCP and UDP sockets without requiring you to handle the details of the connection. diff --git a/docs/framework/network-programming/changes-to-ntlm-authentication-for-httpwebrequest-in-version-3-5-sp1.md b/docs/framework/network-programming/changes-to-ntlm-authentication-for-httpwebrequest-in-version-3-5-sp1.md index ae40ac94c6aa8..0018d696a2f43 100644 --- a/docs/framework/network-programming/changes-to-ntlm-authentication-for-httpwebrequest-in-version-3-5-sp1.md +++ b/docs/framework/network-programming/changes-to-ntlm-authentication-for-httpwebrequest-in-version-3-5-sp1.md @@ -33,9 +33,9 @@ Security changes were made in .NET Framework version 3.5 SP1 and later that affe When configured for large deployments, it is also common for a single virtual server name to be given to the deployment with the underlying machine names never used by client applications and end users. For example, you might call the server www.contoso.com, but on an internal network simply use "contoso". This name is called the Host header in the client web request. As specified by the HTTP protocol, the Host request-header field specifies the Internet host and port number of the resource being requested. This information is obtained from the original URI given by the user or referring resource (generally an HTTP URL). On .NET Framework version 4, this information can also be set by the client using the new property. - The class controls the managed authentication components ("modules") that are used by derivative classes and the class. The class provides a property that exposes a object, indexed by URI string, for applications to supply a custom SPN string to be used during authentication. + The class controls the managed authentication components ("modules") that are used by derivative classes and the class. The class provides a property that exposes a object, indexed by URI string, for applications to supply a custom SPN string to be used during authentication. - Version 3.5 SP1 now defaults to specifying the host name used in the request URL in the SPN in the NTLM (NT LAN Manager) authentication exchange when the property is not set. The host name used in the request URL may be different from the Host header specified in the in the client request. The host name used in the request URL may be different from the actual host name of the server, the machine name of the server, the computer's IP address, or the loopback address. In these cases, Windows will fail the authentication request. To address the issue, we need to notify Windows that the host name used in the request URL in the client request ("contoso", for example) is actually an alternate name for the local computer. + Version 3.5 SP1 now defaults to specifying the host name used in the request URL in the SPN in the NTLM (NT LAN Manager) authentication exchange when the property is not set. The host name used in the request URL may be different from the Host header specified in the in the client request. The host name used in the request URL may be different from the actual host name of the server, the machine name of the server, the computer's IP address, or the loopback address. In these cases, Windows will fail the authentication request. To address the issue, we need to notify Windows that the host name used in the request URL in the client request ("contoso", for example) is actually an alternate name for the local computer. There are several possible methods for a server application to work around this change. The recommended approach is to map the host name used in the request URL to the `BackConnectionHostNames` key in the registry on the server. The `BackConnectionHostNames` registry key is normally used to map a host name to a loopback address. The steps are listed below. @@ -60,6 +60,6 @@ Security changes were made in .NET Framework version 3.5 SP1 and later that affe A less secure work around is to disable the loop back check, as described in [http://support.microsoft.com/kb/896861](http://go.microsoft.com/fwlink/?LinkID=179657). This disables the protection against reflection attacks. So it is better to constrain the set of alternate names to only those you expect the machine to actually use. ## See Also - - - + + + diff --git a/docs/framework/network-programming/changes-to-the-system-uri-namespace-in-version-2-0.md b/docs/framework/network-programming/changes-to-the-system-uri-namespace-in-version-2-0.md index 4f10e2ae46334..06abb7a3e3898 100644 --- a/docs/framework/network-programming/changes-to-the-system-uri-namespace-in-version-2-0.md +++ b/docs/framework/network-programming/changes-to-the-system-uri-namespace-in-version-2-0.md @@ -19,7 +19,7 @@ ms.author: "markl" manager: "markl" --- # Changes to the System.Uri namespace in Version 2.0 -Several changes were made to the class. These changes fixed incorrect behavior, enhanced usability, and enhanced security. +Several changes were made to the class. These changes fixed incorrect behavior, enhanced usability, and enhanced security. ## Obsolete and Deprecated Members Constructors: @@ -79,4 +79,4 @@ Several changes were made to the clas - URI path compression is fixed so that a broken URI cannot traverse the file system above the root. ## See Also - + diff --git a/docs/framework/network-programming/creating-internet-requests.md b/docs/framework/network-programming/creating-internet-requests.md index a7d659c6db655..887d461f5db17 100644 --- a/docs/framework/network-programming/creating-internet-requests.md +++ b/docs/framework/network-programming/creating-internet-requests.md @@ -27,7 +27,7 @@ ms.author: "markl" manager: "markl" --- # Creating Internet Requests -Applications create instances through the method. This is a static method that creates a class derived from **WebRequest** based on the URI scheme passed to it. +Applications create instances through the method. This is a static method that creates a class derived from **WebRequest** based on the URI scheme passed to it. ## Web, File and FTP Requests The .NET Framework provides the class, which is derived from **WebRequest**, to handle HTTP and HTTPS requests. In most cases, the **WebRequest** class provides all the properties you need to make a request; however, if necessary, you can cast **WebRequest** objects created by the **WebRequest.Create** method to the **HttpWebRequest** type to access the HTTP-specific properties of the request. Similarly, the **HttpWebResponse** object handles the responses from HTTP and HTTPS requests. To access the HTTP-specific properties of the **HttpWebResponse** object, you need to cast **WebResponse** objects to the **HttpWebResponse** type. diff --git a/docs/framework/network-programming/deriving-from-webrequest.md b/docs/framework/network-programming/deriving-from-webrequest.md index fb4d4b4a38aed..5650e80eb8b97 100644 --- a/docs/framework/network-programming/deriving-from-webrequest.md +++ b/docs/framework/network-programming/deriving-from-webrequest.md @@ -29,12 +29,12 @@ manager: "markl" # Deriving from WebRequest The class is an abstract base class that provides the basic methods and properties for creating a protocol-specific request handler that fits the .NET Framework pluggable protocol model. Applications that use the **WebRequest** class can request data using any supported protocol without needing to specify the protocol used. - Two criteria must be met in order for a protocol-specific class to be used as a pluggable protocol: The class must implement the interface, and it must register with the method. The class must override all the abstract methods and properties of **WebRequest** to provide the pluggable interface. + Two criteria must be met in order for a protocol-specific class to be used as a pluggable protocol: The class must implement the interface, and it must register with the method. The class must override all the abstract methods and properties of **WebRequest** to provide the pluggable interface. **WebRequest** instances are intended for one-time use; if you want to make another request, create a new **WebRequest**. **WebRequest** supports the interface to enable developers to serialize a template **WebRequest** and then reconstruct the template for additional requests. ## IWebRequest Create Method - The method is responsible for initializing a new instance of the protocol-specific class. When a new **WebRequest** is created, the method matches the requested URI with the URI prefixes registered with the **RegisterPrefix** method. The **Create** method of the proper protocol-specific descendant must return an initialized instance of the descendant capable of performing a standard request/response transaction for the protocol without needing any protocol-specific fields modified. + The method is responsible for initializing a new instance of the protocol-specific class. When a new **WebRequest** is created, the method matches the requested URI with the URI prefixes registered with the **RegisterPrefix** method. The **Create** method of the proper protocol-specific descendant must return an initialized instance of the descendant capable of performing a standard request/response transaction for the protocol without needing any protocol-specific fields modified. ## ConnectionGroupName Property The property is used to name a group of connections to a resource so that multiple requests can be made over a single connection. To implement connection-sharing, you must use a protocol-specific method of pooling and assigning connections. For example, the provided class implements connection sharing for the class. The **ServicePointManager** class creates a that provides a connection to a specific server for each connection group. @@ -53,7 +53,7 @@ The class is an abstract base class that provides t ## Headers Property The property contains an arbitrary collection of name/value pairs of metadata associated with the request. Any metadata needed by the protocol that can be expressed as a name/value pair can be included in the **Headers** property. Typically this information must be set before calling the or methods; once the request has been made, the metadata is considered read-only. - You are not required to use the **Headers** property to use header metadata. Protocol-specific metadata can be exposed as properties; for example, the property exposes the **User-Agent** HTTP header. When you expose header metadata as a property, you should not allow the same property to be set using the **Headers** property. + You are not required to use the **Headers** property to use header metadata. Protocol-specific metadata can be exposed as properties; for example, the property exposes the **User-Agent** HTTP header. When you expose header metadata as a property, you should not allow the same property to be set using the **Headers** property. ## Method Property The property contains the verb or action that the request is asking the server to perform. The default for the **Method** property must enable a standard request/response action without requiring any protocol-specific properties to be set. For example, the method defaults to GET, which requests a resource from a Web server and returns the response. diff --git a/docs/framework/network-programming/deriving-from-webresponse.md b/docs/framework/network-programming/deriving-from-webresponse.md index 975b79f2f834a..cd78dd42b6754 100644 --- a/docs/framework/network-programming/deriving-from-webresponse.md +++ b/docs/framework/network-programming/deriving-from-webresponse.md @@ -23,7 +23,7 @@ manager: "markl" # Deriving from WebResponse The class is an abstract base class that provides the basic methods and properties for creating a protocol-specific response that fits the .NET Framework pluggable protocol model. Applications that use the class to request data from resources receive the responses in a **WebResponse**. Protocol-specific **WebResponse** descendants must implement the abstract members of the **WebResponse** class. - The associated **WebRequest** class must create **WebResponse** descendants. For example, instances are created only as the result of calling or . Each **WebResponse** contains the result of a request to a resource and is not intended to be reused. + The associated **WebRequest** class must create **WebResponse** descendants. For example, instances are created only as the result of calling or . Each **WebResponse** contains the result of a request to a resource and is not intended to be reused. ## ContentLength Property The property indicates the number of bytes of data that are available from the stream returned by the method. The **ContentLength** property does not indicate the number of bytes of header or metadata information returned by the server; it indicates only the number of bytes of data in the requested resource itself. @@ -34,13 +34,13 @@ The class is an abstract base class that provides ## Headers Property The property contains an arbitrary collection of name/value pairs of metadata associated with the response. Any metadata needed by the protocol that can be expressed as a name/value pair can be included in the **Headers** property. - You are not required to use the **Headers** property to use header metadata. Protocol-specific metadata can be exposed as properties; for example, the property exposes the **Last-Modified** HTTP header. When you expose header metadata as a property, you should not allow the same property to be set using the **Headers** property. + You are not required to use the **Headers** property to use header metadata. Protocol-specific metadata can be exposed as properties; for example, the property exposes the **Last-Modified** HTTP header. When you expose header metadata as a property, you should not allow the same property to be set using the **Headers** property. ## ResponseUri Property The property contains the URI of the resource that actually provided the response. For protocols that do not support redirection, **ResponseUri** will be the same as the property of the **WebRequest** that created the response. If the protocol supports redirecting the request, **ResponseUri** will contain the URI of the response. ## Close Method - The method closes any connections made by the request and response and cleans up resources used by the response. The **Close** method closes any stream instances used by the response, but it does not throw an exception if the response stream was previously closed by a call to the method. + The method closes any connections made by the request and response and cleans up resources used by the response. The **Close** method closes any stream instances used by the response, but it does not throw an exception if the response stream was previously closed by a call to the method. ## GetResponseStream Method The method returns a stream containing the response from the requested resource. The response stream contains only the data returned by the resource; any header or metadata included in the response should be stripped from the response and exposed to the application through protocol-specific properties or the **Headers** property. diff --git a/docs/framework/network-programming/enabling-and-disabling-ipv6.md b/docs/framework/network-programming/enabling-and-disabling-ipv6.md index 692bea7ef99bc..0cab2f77f81fe 100644 --- a/docs/framework/network-programming/enabling-and-disabling-ipv6.md +++ b/docs/framework/network-programming/enabling-and-disabling-ipv6.md @@ -45,9 +45,9 @@ To use the IPv6 protocol, ensure that you are running a version of the operating ``` - For .NET Framework version 1.1 and earlier, the value of the **ipv6 enabled** configuration switch specifies whether members of the class return IPv6 addresses. + For .NET Framework version 1.1 and earlier, the value of the **ipv6 enabled** configuration switch specifies whether members of the class return IPv6 addresses. - For .NET Framework version 2.0 and later, if Windows supports IPv6, then members of the class, (for example, the method), will return IPv6 addresses with one limitation. Obsolete members of the DNS (for example, the method) will read and recognize the value in the configuration file for the ipv6 enabled setting. + For .NET Framework version 2.0 and later, if Windows supports IPv6, then members of the class, (for example, the method), will return IPv6 addresses with one limitation. Obsolete members of the DNS (for example, the method) will read and recognize the value in the configuration file for the ipv6 enabled setting. ## See Also [Internet Protocol Version 6](../../../docs/framework/network-programming/internet-protocol-version-6.md) diff --git a/docs/framework/network-programming/how-to-modify-the-computer-configuration-file-to-enable-ipv6-support.md b/docs/framework/network-programming/how-to-modify-the-computer-configuration-file-to-enable-ipv6-support.md index 7587671b5c92e..279d0362436b4 100644 --- a/docs/framework/network-programming/how-to-modify-the-computer-configuration-file-to-enable-ipv6-support.md +++ b/docs/framework/network-programming/how-to-modify-the-computer-configuration-file-to-enable-ipv6-support.md @@ -23,9 +23,9 @@ The following code example shows how to modify the computer configuration file, These settings can also be made in the configuration file for the application, which has precedence over the computer configuration file. - For .NET Framework version 1.1 and earlier, the value of the **ipv6 enabled** configuration switch specifies whether members of the class return IPv6 addresses. + For .NET Framework version 1.1 and earlier, the value of the **ipv6 enabled** configuration switch specifies whether members of the class return IPv6 addresses. - For .NET Framework version 2.0 and later, if Windows supports IPv6, then all members of the class (for example, the method), will return IPv6 addresses with one limitation. Obsolete members of the class (for example, the method) will read and recognize the value in the configuration file. + For .NET Framework version 2.0 and later, if Windows supports IPv6, then all members of the class (for example, the method), will return IPv6 addresses with one limitation. Obsolete members of the class (for example, the method) will read and recognize the value in the configuration file. > [!NOTE] > For .NET Framework version 2.0 and later, IPv6 is enabled by default. For .NET Framework version 1.1 and earlier, IPv6 is disabled by default. diff --git a/docs/framework/network-programming/how-to-request-data-using-the-webrequest-class.md b/docs/framework/network-programming/how-to-request-data-using-the-webrequest-class.md index 733db9de43f97..ed3e10d799663 100644 --- a/docs/framework/network-programming/how-to-request-data-using-the-webrequest-class.md +++ b/docs/framework/network-programming/how-to-request-data-using-the-webrequest-class.md @@ -73,7 +73,7 @@ The following procedure describes the steps used to request a resource from a se ``` > [!NOTE] - > After you are finished with a object, you must close it by calling the method. Alternatively, if you have gotten the response stream from the response object, you can close the stream by calling the method. If you do not close either the response or the stream, your application can run out of connections to the server and become unable to process additional requests. + > After you are finished with a object, you must close it by calling the method. Alternatively, if you have gotten the response stream from the response object, you can close the stream by calling the method. If you do not close either the response or the stream, your application can run out of connections to the server and become unable to process additional requests. 4. You can access the properties of the **WebResponse** or cast the **WebResponse** to a protocol-specific instance to read protocol-specific properties. For example, to access the HTTP-specific properties of , cast the **WebResponse** to a **HttpWebResponse** reference. The following code example shows how to display the status information sent with a response. diff --git a/docs/framework/network-programming/how-to-send-data-using-the-webrequest-class.md b/docs/framework/network-programming/how-to-send-data-using-the-webrequest-class.md index 58c5801d7138e..49fbad6a46f86 100644 --- a/docs/framework/network-programming/how-to-send-data-using-the-webrequest-class.md +++ b/docs/framework/network-programming/how-to-send-data-using-the-webrequest-class.md @@ -130,7 +130,7 @@ The following procedure describes the steps used to send data to a server. This ``` > [!NOTE] - > After you are finished with a object, you must close it by calling the method. Alternatively, if you have gotten the response stream from the response object, you can close the stream by calling the method. If you do not close the response or the stream, your application can run out of connections to the server and become unable to process additional requests. + > After you are finished with a object, you must close it by calling the method. Alternatively, if you have gotten the response stream from the response object, you can close the stream by calling the method. If you do not close the response or the stream, your application can run out of connections to the server and become unable to process additional requests. 10. You can access the properties of the **WebResponse** or cast the **WebResponse** to a protocol-specific instance to read protocol-specific properties. For example, to access the HTTP-specific properties of , cast the **WebResponse** to an **HttpWebResponse** reference. diff --git a/docs/framework/network-programming/http.md b/docs/framework/network-programming/http.md index 9998305328f5f..694a309af3ff0 100644 --- a/docs/framework/network-programming/http.md +++ b/docs/framework/network-programming/http.md @@ -30,7 +30,7 @@ ms.author: "markl" manager: "markl" --- # HTTP -The .NET Framework provides comprehensive support for the HTTP protocol, which makes up the majority of all Internet traffic, with the and classes. These classes, derived from and , are returned by default whenever the static method encounters a URI beginning with "http" or "https". In most cases, the **WebRequest** and **WebResponse** classes provide all that is necessary to make the request, but if you need access to the HTTP-specific features exposed as properties, you can typecast these classes to **HttpWebRequest** or **HttpWebResponse**. +The .NET Framework provides comprehensive support for the HTTP protocol, which makes up the majority of all Internet traffic, with the and classes. These classes, derived from and , are returned by default whenever the static method encounters a URI beginning with "http" or "https". In most cases, the **WebRequest** and **WebResponse** classes provide all that is necessary to make the request, but if you need access to the HTTP-specific features exposed as properties, you can typecast these classes to **HttpWebRequest** or **HttpWebResponse**. **HttpWebRequest** and **HttpWebResponse** encapsulate a standard HTTP request-and-response transaction and provide access to common HTTP headers. These classes also support most HTTP 1.1 features, including pipelining, sending and receiving data in chunks, authentication, preauthentication, encryption, proxy support, server certificate validation, and connection management. Custom headers and headers not provided through properties can be stored in and accessed through the **Headers** property. diff --git a/docs/framework/network-programming/index.md b/docs/framework/network-programming/index.md index 6042f1441ff8f..7065aa05b27be 100644 --- a/docs/framework/network-programming/index.md +++ b/docs/framework/network-programming/index.md @@ -49,7 +49,7 @@ The Microsoft .NET Framework provides a layered, extensible, and managed impleme Explains how to use network tracing to get information about method invocations and network traffic generated by a managed application. [Cache Management for Network Applications](../../../docs/framework/network-programming/cache-management-for-network-applications.md) - Describes how to use caching for applications that use the , , and classes. + Describes how to use caching for applications that use the , , and classes. [Security in Network Programming](../../../docs/framework/network-programming/security-in-network-programming.md) Describes how to use standard Internet security and authentication techniques. @@ -61,31 +61,31 @@ The Microsoft .NET Framework provides a layered, extensible, and managed impleme Describes how to configure proxies. [NetworkInformation](../../../docs/framework/network-programming/networkinformation.md) - Describes how to gather information about network events, changes, statistics, and properties and also explains how to determine whether a remote host is reachable by using the class. + Describes how to gather information about network events, changes, statistics, and properties and also explains how to determine whether a remote host is reachable by using the class. [Changes to the System.Uri namespace in Version 2.0](../../../docs/framework/network-programming/changes-to-the-system-uri-namespace-in-version-2-0.md) - Describes several changes made to the class in Version 2.0 to fixed incorrect behavior, enhance usability, and enhance security. + Describes several changes made to the class in Version 2.0 to fixed incorrect behavior, enhance usability, and enhance security. [International Resource Identifier Support in System.Uri](../../../docs/framework/network-programming/international-resource-identifier-support-in-system-uri.md) - Describes enhancements to the class in Version 3.5, 3.0 SP1, and 2.0 SP1 for International Resource Identifier (IRI) and Internationalized Domain Name (IDN) support. + Describes enhancements to the class in Version 3.5, 3.0 SP1, and 2.0 SP1 for International Resource Identifier (IRI) and Internationalized Domain Name (IDN) support. [Socket Performance Enhancements in Version 3.5](../../../docs/framework/network-programming/socket-performance-enhancements-in-version-3-5.md) - Describes a set of enhancements to the class in Version 3.5, 3.0 SP1, and 2.0 SP1 that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. + Describes a set of enhancements to the class in Version 3.5, 3.0 SP1, and 2.0 SP1 that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. [Peer Name Resolution Protocol](../../../docs/framework/network-programming/peer-name-resolution-protocol.md) - Describes support added in Version 3.5 to support the Peer Name Resolution Protocol (PNRP), a serverless and dynamic name registration and name resolution protocol. These new features are supported by the namespace. + Describes support added in Version 3.5 to support the Peer Name Resolution Protocol (PNRP), a serverless and dynamic name registration and name resolution protocol. These new features are supported by the namespace. [Peer-to-Peer Collaboration](../../../docs/framework/network-programming/peer-to-peer-collaboration.md) - Describes support added in Version 3.5 to support the Peer-to-Peer Collaboration that builds on PNRP. These new features are supported by the namespace. + Describes support added in Version 3.5 to support the Peer-to-Peer Collaboration that builds on PNRP. These new features are supported by the namespace. [Changes to NTLM authentication for HttpWebRequest in Version 3.5 SP1](../../../docs/framework/network-programming/changes-to-ntlm-authentication-for-httpwebrequest-in-version-3-5-sp1.md) - Describes security changes made in Version 3.5 SP1 that affect how integrated Windows authentication is handled by the , , , and related classes in the System.Net namespace. + Describes security changes made in Version 3.5 SP1 that affect how integrated Windows authentication is handled by the , , , and related classes in the System.Net namespace. [Integrated Windows Authentication with Extended Protection](../../../docs/framework/network-programming/integrated-windows-authentication-with-extended-protection.md) - Describes enhancements for extended protection that affect how integrated Windows authentication is handled by the , , , , , and related classes in the and related namespaces. + Describes enhancements for extended protection that affect how integrated Windows authentication is handled by the , , , , , and related classes in the and related namespaces. [NAT Traversal using IPv6 and Teredo](../../../docs/framework/network-programming/nat-traversal-using-ipv6-and-teredo.md) - Describes enhancements added to the , , and namespaces to support NAT traversal using IPv6 and Teredo. + Describes enhancements added to the , , and namespaces to support NAT traversal using IPv6 and Teredo. [Network Isolation for Windows Store Apps](../../../docs/framework/network-programming/network-isolation-for-windows-store-apps.md) Describes the impact of network isolation when classes in the , , and namespaces are used in [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. @@ -94,52 +94,52 @@ The Microsoft .NET Framework provides a layered, extensible, and managed impleme Links to downloadable network programming samples that use classes in the , , , , , , , , namespaces. ## Reference - - Provides a simple programming interface for many of the protocols used on networks today. The and classes in this namespace are the basis for pluggable protocols. + + Provides a simple programming interface for many of the protocols used on networks today. The and classes in this namespace are the basis for pluggable protocols. - - Defines the types and enumerations used to define cache policies for resources obtained using the and classes. + + Defines the types and enumerations used to define cache policies for resources obtained using the and classes. - + Classes that applications use to programmatically access and update configuration settings for the System.Net namespaces. - + Classes that provides a programming interface for modern HTTP applications. - - Provides support for collections of HTTP headers used by the namespace + + Provides support for collections of HTTP headers used by the namespace - + Classes to compose and send mail using the SMTP protocol. - - Defines types that are used to represent Multipurpose Internet Mail Exchange (MIME) headers used by classes in the namespace. + + Defines types that are used to represent Multipurpose Internet Mail Exchange (MIME) headers used by classes in the namespace. - + Classes to programmatically gather information about network events, changes, statistics, and properties. - + Provides a managed implementation of the Peer Name Resolution Protocol (PNRP) for developers. - + Provides a managed implementation of the Peer-to-Peer Collaboration interface for developers. - + Classes to provide network streams for secure communications between hosts. - + Provides a managed implementation of the Windows Sockets (Winsock) interface for developers who need to help control access to the network. - + Provides a managed implementation of the WebSocket interface for developers. - + Provides an object representation of a uniform resource identifier (URI) and easy access to the parts of the URI. - + Provides support for authentication using extended protection for applications. - + Provides support for configuration of authentication using extended protection for applications. ## See Also diff --git a/docs/framework/network-programming/integrated-windows-authentication-with-extended-protection.md b/docs/framework/network-programming/integrated-windows-authentication-with-extended-protection.md index 17a0af016ea20..b3fc26b4c69d1 100644 --- a/docs/framework/network-programming/integrated-windows-authentication-with-extended-protection.md +++ b/docs/framework/network-programming/integrated-windows-authentication-with-extended-protection.md @@ -118,7 +118,7 @@ Enhancements were made that affect how integrated Windows authentication is hand ## Extended Protection for Client Applications Extended protection support for most client applications happens automatically. The and classes support extended protection whenever the underlying version of Windows supports extended protection. An instance sends an SPN constructed from the . By default, an instance sends an SPN constructed from the host name of the SMTP mail server. - For custom authentication, client applications can use the or methods in the class that allow retrieving the and the CBT using the method. + For custom authentication, client applications can use the or methods in the class that allow retrieving the and the CBT using the method. The SPN to use for integrated Windows authentication sent by an instance to a given service can be overridden by setting the property. @@ -127,7 +127,7 @@ Enhancements were made that affect how integrated Windows authentication is hand ## Extended Protection for Server Applications automatically provides mechanisms for validating service bindings when performing HTTP authentication. - The most secure scenario is to enable extended protection for HTTPS:// prefixes. In this case, set to an with set to or , and set to A value of puts in partially hardened mode, while corresponds to fully hardened mode. + The most secure scenario is to enable extended protection for HTTPS:// prefixes. In this case, set to an with set to or , and set to A value of puts in partially hardened mode, while corresponds to fully hardened mode. In this configuration when a request is made to the server through an outer secure channel, the outer channel is queried for a channel binding. This channel binding is passed to the authentication SSPI calls, which validate that the channel binding in the authentication blob matches. There are three possible outcomes: @@ -139,7 +139,7 @@ Enhancements were made that affect how integrated Windows authentication is hand If an application makes its own SSPI calls to perform authentication based on blobs passed back and forth within the body of an HTTP request and wishes to support channel binding, it needs to retrieve the expected channel binding from the outer secure channel using in order to pass it to native Win32 [AcceptSecurityContext](http://go.microsoft.com/fwlink/?LinkId=147021) function. To do this, use the property and call method to retrieve the CBT. Only endpoint bindings are supported. If anything other is specified, a will be thrown. If the underlying operating system supports channel binding, the method will return a wrapping a pointer to a channel binding suitable for passing to [AcceptSecurityContext](http://go.microsoft.com/fwlink/?LinkId=147021) function as the pvBuffer member of a SecBuffer structure passed in the `pInput` parameter. The property contains the length, in bytes, of the channel binding. If the underlying operating system does not support channel bindings, the function will return `null`. - Another possible scenario is to enable extended protection for HTTP:// prefixes when proxies are not used. In this case, set to an with set to or , and set to A value of puts in partially hardened mode, while corresponds to fully hardened mode. + Another possible scenario is to enable extended protection for HTTP:// prefixes when proxies are not used. In this case, set to an with set to or , and set to A value of puts in partially hardened mode, while corresponds to fully hardened mode. A default list of allowed service names is created based on the prefixes which have been registered with the . This default list can be examined through the property. If this list is not comprehensive, an application can specify a custom service name collection in the constructor for the class which will be used instead of the default service name list. diff --git a/docs/framework/network-programming/international-resource-identifier-support-in-system-uri.md b/docs/framework/network-programming/international-resource-identifier-support-in-system-uri.md index 8d06b5dcd5e58..3a8646b2ff14e 100644 --- a/docs/framework/network-programming/international-resource-identifier-support-in-system-uri.md +++ b/docs/framework/network-programming/international-resource-identifier-support-in-system-uri.md @@ -19,7 +19,7 @@ ms.author: "markl" manager: "markl" --- # International Resource Identifier Support in System.Uri -The class has been extended with International Resource Identifier (IRI) and Internationalized Domain Names (IDN) support. These enhancements are available in .NET Framework 3.5, 3.0 SP1, and 2.0 SP1. +The class has been extended with International Resource Identifier (IRI) and Internationalized Domain Names (IDN) support. These enhancements are available in .NET Framework 3.5, 3.0 SP1, and 2.0 SP1. ## IRI and IDN Support Web addresses are typically expressed using Uniform Resource Identifiers (URI) that consist of a very restricted set of characters: @@ -34,26 +34,26 @@ The class has been extended with Inte With the growth of the Internet, there is a growing need to identify resources using languages other than English. Identifiers which facilitate this need and allow non-ASCII characters (characters in the Unicode/ISO 10646 character set) are known as International Resource Identifiers (IRIs). The specifications for IRIs are documented in RFC 3987 published by IETF. Using IRIs allows a URL to contain Unicode characters. - The existing class has been extended to provide IRI support based on RFC 3987. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework. + The existing class has been extended to provide IRI support based on RFC 3987. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework. An application can specify whether to use Internationalized Domain Name (IDN) parsing applied to domain names and whether IRI parsing rules should be applied. This can be done in the machine.config or in the app.config file. Enabling IDN will convert all Unicode labels in a domain name to their Punycode equivalents. Punycode names contain only ASCII characters and always start with the xn-- prefix. The reason for this is to support existing DNS servers on the Internet, since most DNS servers only support ASCII characters (see RFC 3940). - Enabling IRI and IDN affects the value of the property. Enabling IRI and IDN can also change the behavior of the , , , and methods. + Enabling IRI and IDN affects the value of the property. Enabling IRI and IDN can also change the behavior of the , , , and methods. - The class has also been extended to allow creating a customizable parser that supports IRI and IDN. The behavior of a object is specified by passing a bitwise combination of the values available in the enumeration to the constructor. The type indicates the parser supports the parsing rules specified in RFC 3987 for International Resource Identifiers (IRI). Whether IRI is actually used depends on if IRI is enabled. + The class has also been extended to allow creating a customizable parser that supports IRI and IDN. The behavior of a object is specified by passing a bitwise combination of the values available in the enumeration to the constructor. The type indicates the parser supports the parsing rules specified in RFC 3987 for International Resource Identifiers (IRI). Whether IRI is actually used depends on if IRI is enabled. - The type indicates the parser supports Internationalized Domain Name (IDN) parsing (IDN) of host names. Whether IDN is actually used depends on if IDN is enabled. + The type indicates the parser supports Internationalized Domain Name (IDN) parsing (IDN) of host names. Whether IDN is actually used depends on if IDN is enabled. Enabling IRI parsing will do normalization and character checking according to the latest IRI rules in RFC 3987. The default value is for IRI parsing to be disabled so normalization and character checking are done according to RFC 2396 and RFC 3986. - IRI and IDN processing in the class can also be controlled using the and configuration setting classes. The setting enables or disables IRI processing in the class. The setting enables or disables IDN processing in the class. The setting also indirectly controls IDN. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + IRI and IDN processing in the class can also be controlled using the and configuration setting classes. The setting enables or disables IRI processing in the class. The setting enables or disables IDN processing in the class. The setting also indirectly controls IDN. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. - The configuration setting for the and configuration classes will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. + The configuration setting for the and configuration classes will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. ## See Also - - - - + + + + diff --git a/docs/framework/network-programming/internet-authentication.md b/docs/framework/network-programming/internet-authentication.md index 7cf3d2a17f924..3e48b79214793 100644 --- a/docs/framework/network-programming/internet-authentication.md +++ b/docs/framework/network-programming/internet-authentication.md @@ -40,7 +40,7 @@ The classes support a variety of client authentication mechani The **CredentialCache** class stores a collection of credentials for various Web resources. When the method is called, **CredentialCache** returns the proper set of credentials, as determined by the URI of the Web resource and the requested authentication scheme. Applications that use a variety of Internet resources with different authentication schemes benefit from using the **CredentialCache** class, since it stores all the credentials and provides them as requested. - When an Internet resource requests authentication, the method sends the to the **AuthenticationManager** along with the request for credentials. The request is then authenticated according to the following process: + When an Internet resource requests authentication, the method sends the to the **AuthenticationManager** along with the request for credentials. The request is then authenticated according to the following process: 1. The **AuthenticationManager** calls the method on each of the registered authentication modules in the order they were registered. The **AuthenticationManager** uses the first module that does not return **null** to carry out the authentication process. The details of the process vary depending on the type of authentication module involved. diff --git a/docs/framework/network-programming/introducing-pluggable-protocols.md b/docs/framework/network-programming/introducing-pluggable-protocols.md index f8bc880f411fd..db34a25c06e27 100644 --- a/docs/framework/network-programming/introducing-pluggable-protocols.md +++ b/docs/framework/network-programming/introducing-pluggable-protocols.md @@ -64,7 +64,7 @@ The Microsoft .NET Framework provides a layered, extensible, and managed impleme As an example, the class manages the details of connecting to an Internet resource using HTTP. By default, when the **WebRequest.Create** method encounters a URI that begins with "http:" or "https:" (the protocol identifiers for HTTP and secure HTTP), the **WebRequest** that is returned can be used as is, or it can be typecast to **HttpWebRequest** to access protocol-specific properties. In most cases, the **WebRequest** provides all the necessary information for making a request. - Any protocol that can be represented as a request/response transaction can be used in a **WebRequest**. You can derive protocol-specific classes from **WebRequest** and **WebResponse** and then register them for use by the application with the static method. + Any protocol that can be represented as a request/response transaction can be used in a **WebRequest**. You can derive protocol-specific classes from **WebRequest** and **WebResponse** and then register them for use by the application with the static method. When client authorization for Internet requests is required, the property of the **WebRequest** supplies the necessary credentials. These credentials can be a simple name/password pair for basic HTTP or digest authentication, or a name/password/domain set for NTLM or Kerberos authentication. One set of credentials can be stored in a instance, or multiple sets can be stored simultaneously in a instance. The **CredentialCache** uses the URI of the request and the authentication scheme that the server supports to determine which credentials to send to the server. diff --git a/docs/framework/network-programming/making-asynchronous-requests.md b/docs/framework/network-programming/making-asynchronous-requests.md index 6246c87bac881..5d6b2ba7cbf0c 100644 --- a/docs/framework/network-programming/making-asynchronous-requests.md +++ b/docs/framework/network-programming/making-asynchronous-requests.md @@ -28,7 +28,7 @@ manager: "markl" The classes use the .NET Framework's standard asynchronous programming model for asynchronous access to Internet resources. The and methods of the class start and complete asynchronous requests for an Internet resource. > [!NOTE] -> Using synchronous calls in asynchronous callback methods can result in severe performance penalties. Internet requests made with **WebRequest** and its descendants must use to read the stream returned by the method. +> Using synchronous calls in asynchronous callback methods can result in severe performance penalties. Internet requests made with **WebRequest** and its descendants must use to read the stream returned by the method. The following sample code demonstrates how to use asynchronous calls with the **WebRequest** class. The sample is a console program that takes a URI from the command line, requests the resource at the URI, and then prints data to the console as it is received from the Internet. diff --git a/docs/framework/network-programming/nat-traversal-using-ipv6-and-teredo.md b/docs/framework/network-programming/nat-traversal-using-ipv6-and-teredo.md index 32edc53049f2b..830c39e7f8762 100644 --- a/docs/framework/network-programming/nat-traversal-using-ipv6-and-teredo.md +++ b/docs/framework/network-programming/nat-traversal-using-ipv6-and-teredo.md @@ -41,24 +41,24 @@ Enhancements were made that provide support for Network Address Translation (NAT ## Enhancements to Support NAT Traversal and Teredo Enhancements are added to the , , and namespaces for supporting NAT traversal using IPv6 and Teredo. - Several methods are added to the class to get the list of unicast IP addresses on the host. The method begins an asynchronous request to retrieve the stable unicast IP address table on the local computer. The method ends a pending asynchronous request to retrieve the stable unicast IP address table on the local computer. The method is a synchronous request to retrieve the stable unicast IP address table on the local computer, waiting until the address table stabilizes if necessary. + Several methods are added to the class to get the list of unicast IP addresses on the host. The method begins an asynchronous request to retrieve the stable unicast IP address table on the local computer. The method ends a pending asynchronous request to retrieve the stable unicast IP address table on the local computer. The method is a synchronous request to retrieve the stable unicast IP address table on the local computer, waiting until the address table stabilizes if necessary. - The property can be used to determine if an is an IPv6 Teredo address. + The property can be used to determine if an is an IPv6 Teredo address. Using these new class methods in combination with the property allows an application to easily find the Teredo address. An application normally only needs to know the local Teredo address if it is communicating this information to remote applications. For example, a peer-to-peer application might send all of its IPv6 addresses to a matchmaking server which can then forward them to others peers to enable direct communication. - An application should normally set its listening service to listen on rather than on the local Teredo address. So if a remote client or peer has a direct IPv6 route to the host of the listening service, the client or peer can connect directly using IPv6 and not have to use Teredo to tunnel packets. + An application should normally set its listening service to listen on rather than on the local Teredo address. So if a remote client or peer has a direct IPv6 route to the host of the listening service, the client or peer can connect directly using IPv6 and not have to use Teredo to tunnel packets. - For TCP applications, the class has an method to enable NAT traversal. For UDP applications, the class has an method to enable NAT traversal. + For TCP applications, the class has an method to enable NAT traversal. For UDP applications, the class has an method to enable NAT traversal. - For applications that use the and related classes, the and methods can be used with the socket option to query, enable, or disable NAT traversal. + For applications that use the and related classes, the and methods can be used with the socket option to query, enable, or disable NAT traversal. ## See Also - - - - - - - - + + + + + + + + diff --git a/docs/framework/network-programming/networkinformation.md b/docs/framework/network-programming/networkinformation.md index 40b273c386ca1..ce360e8313b16 100644 --- a/docs/framework/network-programming/networkinformation.md +++ b/docs/framework/network-programming/networkinformation.md @@ -21,10 +21,10 @@ ms.author: "markl" manager: "markl" --- # NetworkInformation -The namespace enables you to gather information about network events, changes, statistics, and properties. You can also determine whether a remote host is reachable by using the class. +The namespace enables you to gather information about network events, changes, statistics, and properties. You can also determine whether a remote host is reachable by using the class. ## Network Availability and Events - The class enables you to determine whether the network address or availability has changed. To use this class, create an event handler to process the change, and associate it with a or a . For more information, see [How to: Detect Network Availability and Address Changes](../../../docs/framework/network-programming/how-to-detect-network-availability-and-address-changes.md). + The class enables you to determine whether the network address or availability has changed. To use this class, create an event handler to process the change, and associate it with a or a . For more information, see [How to: Detect Network Availability and Address Changes](../../../docs/framework/network-programming/how-to-detect-network-availability-and-address-changes.md). ## Network Statistics and Properties You can gather network statistics and properties on an interface or protocol basis. The , , and classes give information about a particular network interface, while the , , , , and classes give information about layer 3 and layer 4 packets. For more information, see [How to: Get Interface and Protocol Information](../../../docs/framework/network-programming/how-to-get-interface-and-protocol-information.md). diff --git a/docs/framework/network-programming/requesting-data.md b/docs/framework/network-programming/requesting-data.md index ce347fca0b7c1..2e8dfd64f51d9 100644 --- a/docs/framework/network-programming/requesting-data.md +++ b/docs/framework/network-programming/requesting-data.md @@ -38,15 +38,15 @@ Developing applications that run in the distributed operating environment of tod Client applications that need to make more complex transactions request data from servers using the **WebRequest** class and its descendants. **WebRequest** encapsulates the details of connecting to the server, sending the request, and receiving the response. **WebRequest** is an abstract class that defines a set of properties and methods that are available to all applications that use pluggable protocols. Descendants of **WebRequest**, such as , implement the properties and methods defined by **WebRequest** in a way that is consistent with the underlying protocol. - The **WebRequest** class creates protocol-specific instances of **WebRequest** descendants, using the value of the URI passed to its method to determine the specific derived-class instance to create. Applications indicate which **WebRequest** descendant should be used to handle a request by registering the descendant's constructor with the method. + The **WebRequest** class creates protocol-specific instances of **WebRequest** descendants, using the value of the URI passed to its method to determine the specific derived-class instance to create. Applications indicate which **WebRequest** descendant should be used to handle a request by registering the descendant's constructor with the method. - A request is made to the Internet resource by calling the method on the **WebRequest**. The **GetResponse** method constructs the protocol-specific request from the properties of the **WebRequest**, makes the TCP or UDP socket connection to the server, and sends the request. For requests that send data to the server, such as HTTP **Post** or FTP **Put** requests, the method provides a network stream in which to send the data. + A request is made to the Internet resource by calling the method on the **WebRequest**. The **GetResponse** method constructs the protocol-specific request from the properties of the **WebRequest**, makes the TCP or UDP socket connection to the server, and sends the request. For requests that send data to the server, such as HTTP **Post** or FTP **Put** requests, the method provides a network stream in which to send the data. The **GetResponse** method returns a protocol-specific **WebResponse** that matches the **WebRequest.** The **WebResponse** class is also an abstract class that defines properties and methods that are available to all applications that use pluggable protocols. **WebResponse** descendants implement these properties and methods for the underlying protocol. The class, for example, implements the **WebResponse** class for HTTP. - The data returned by the server is presented to the application in the stream returned by the method. You can use this stream like any other, as shown in the following example. + The data returned by the server is presented to the application in the stream returned by the method. You can use this stream like any other, as shown in the following example. ```csharp StreamReader sr = diff --git a/docs/framework/network-programming/socket-performance-enhancements-in-version-3-5.md b/docs/framework/network-programming/socket-performance-enhancements-in-version-3-5.md index 96881bb08bbee..0b7343666db80 100644 --- a/docs/framework/network-programming/socket-performance-enhancements-in-version-3-5.md +++ b/docs/framework/network-programming/socket-performance-enhancements-in-version-3-5.md @@ -19,12 +19,12 @@ ms.author: "markl" manager: "markl" --- # Socket Performance Enhancements in Version 3.5 -The class has been enhanced in Version 3.5 for use by applications that use asynchronous network I/O to achieve the highest performance. A series of new classes have been added as part of a set of enhancements to the class that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. These enhancements were specifically designed for network server applications that require high performance. An application can use the enhanced asynchronous pattern exclusively, or only in targeted hot areas of their application (when receiving large amounts of data, for example). +The class has been enhanced in Version 3.5 for use by applications that use asynchronous network I/O to achieve the highest performance. A series of new classes have been added as part of a set of enhancements to the class that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. These enhancements were specifically designed for network server applications that require high performance. An application can use the enhanced asynchronous pattern exclusively, or only in targeted hot areas of their application (when receiving large amounts of data, for example). ## Class Enhancements - The main feature of these enhancements is the avoidance of the repeated allocation and synchronization of objects during high-volume asynchronous socket I/O. The Begin/End design pattern currently implemented by the class for asynchronous socket I/O requires a object be allocated for each asynchronous socket operation. + The main feature of these enhancements is the avoidance of the repeated allocation and synchronization of objects during high-volume asynchronous socket I/O. The Begin/End design pattern currently implemented by the class for asynchronous socket I/O requires a object be allocated for each asynchronous socket operation. - In the new class enhancements, asynchronous socket operations are described by reusable class objects allocated and maintained by the application. High-performance socket applications know best the amount of overlapped socket operations that must be sustained. The application can create as many of the objects that it needs. For example, if a server application needs to have 15 socket accept operations outstanding at all times to support incoming client connection rates, it can allocate 15 reusable objects in advance for that purpose. + In the new class enhancements, asynchronous socket operations are described by reusable class objects allocated and maintained by the application. High-performance socket applications know best the amount of overlapped socket operations that must be sustained. The application can create as many of the objects that it needs. For example, if a server application needs to have 15 socket accept operations outstanding at all times to support incoming client connection rates, it can allocate 15 reusable objects in advance for that purpose. The pattern for performing an asynchronous socket operation with this class consists of the following steps: @@ -43,9 +43,9 @@ The class has been enh The lifetime of the new asynchronous socket operation context object is determined by references in the application code and asynchronous I/O references. It is not necessary for the application to retain a reference to an asynchronous socket operation context object after it is submitted as a parameter to one of the asynchronous socket operation methods. It will remain referenced until the completion callback returns. However it is advantageous for the application to retain the reference to the context object so that it can be reused for a future asynchronous socket operation. ## See Also - - - - + + + + [Network Programming Samples](../../../docs/framework/network-programming/network-programming-samples.md) [Socket Performance Technology Sample](http://go.microsoft.com/fwlink/?LinkID=179570) diff --git a/docs/framework/network-programming/tcp-udp.md b/docs/framework/network-programming/tcp-udp.md index 882b08956fe36..ad25fb03e4fe3 100644 --- a/docs/framework/network-programming/tcp-udp.md +++ b/docs/framework/network-programming/tcp-udp.md @@ -33,7 +33,7 @@ ms.author: "markl" manager: "markl" --- # TCP-UDP -Applications can use Transmission Control Protocol (TCP) and User Datagram Protocol (UDP) services with the , , and classes. These protocol classes are built on top of the class and take care of the details of transferring data. +Applications can use Transmission Control Protocol (TCP) and User Datagram Protocol (UDP) services with the , , and classes. These protocol classes are built on top of the class and take care of the details of transferring data. The protocol classes use the synchronous methods of the **Socket** class to provide simple and straightforward access to network services without the overhead of maintaining state information or knowing the details of setting up protocol-specific sockets. To use asynchronous **Socket** methods, you can use the asynchronous methods supplied by the class. To access features of the **Socket** class not exposed by the protocol classes, you must use the **Socket** class. diff --git a/docs/framework/network-programming/understanding-webrequest-problems-and-exceptions.md b/docs/framework/network-programming/understanding-webrequest-problems-and-exceptions.md index acc0d8edd3011..bf811c19a9127 100644 --- a/docs/framework/network-programming/understanding-webrequest-problems-and-exceptions.md +++ b/docs/framework/network-programming/understanding-webrequest-problems-and-exceptions.md @@ -26,7 +26,7 @@ manager: "markl" |Status|Details|Solution| |------------|-------------|--------------| -|

-or-

|There is a problem with the underlying socket. The connection may have been reset.|Reconnect and resend the request.

Make sure the latest service pack is installed.

Increase the value of the property.

Set to `false`.

Increase the number of maximum connections with the property.

Check the proxy configuration.

If using SSL, make sure the server process has permission to access the Certificate store.

If sending a large amount of data, set to `false`.| +|

-or-

|There is a problem with the underlying socket. The connection may have been reset.|Reconnect and resend the request.

Make sure the latest service pack is installed.

Increase the value of the property.

Set to `false`.

Increase the number of maximum connections with the property.

Check the proxy configuration.

If using SSL, make sure the server process has permission to access the Certificate store.

If sending a large amount of data, set to `false`.| ||The server certificate could not be validated.|Try to open the URI using Internet Explorer. Resolve any Security Alerts displayed by IE. If you cannot resolve the security alert, then you can create a certificate policy class that implements that returns `true`, and pass it to .

Refer to [http://support.microsoft.com/?id=823177](http://go.microsoft.com/fwlink/?LinkID=179653).

Make sure that the certificate of the Certificate Authority that signed the server certificate is added to the Trusted Certificate Authority list in Internet Explorer.

Make sure that the host name in the URL matches the common name on the server certificate.| ||An error occurred in the SSL transaction, or there is a certificate problem.|The .NET Framework version 1.1 only supports SSL version 3.0. If the server is using only TLS version 1.0 or SSL version 2.0, the exception is thrown. Upgrade to .NET Framework version 2.0, and set to match the server.

The client certificate was signed by a Certificate Authority (CA) that the server does not trust. Install the CA's certificate on the server. See [http://support.microsoft.com/?id=332077](http://go.microsoft.com/fwlink/?LinkID=179654).

Make sure you have the latest service pack installed.| ||The connection failed.|A firewall or proxy is blocking the connection. Modify the firewall or proxy to allow the connection.

Explicitly designate a in the client application by calling the constructor (WebServiceProxyClass.Proxy = new WebProxy([http://server:80](http://server/), true)).

Run Filemon or Regmon to ensure that the worker process identity has the necessary permissions to access WSPWSP.dll, HKLM\System\CurrentControlSet\Services\DnsCache or HKLM\System\CurrentControlSet\Services\WinSock2.| diff --git a/docs/framework/network-programming/using-a-synchronous-client-socket.md b/docs/framework/network-programming/using-a-synchronous-client-socket.md index ee768a89277d2..b3935336ab866 100644 --- a/docs/framework/network-programming/using-a-synchronous-client-socket.md +++ b/docs/framework/network-programming/using-a-synchronous-client-socket.md @@ -33,7 +33,7 @@ manager: "markl" # Using a Synchronous Client Socket A synchronous client socket suspends the application program while the network operation completes. Synchronous sockets are not suitable for applications that make heavy use of the network for their operation, but they can enable simple access to network services for other applications. - To send data, pass a byte array to one of the class's send-data methods ( and ). The following example encodes a string into a byte array buffer using the property and then transmits the buffer to the network device using the **Send** method. The **Send** method returns the number of bytes sent to the network device. + To send data, pass a byte array to one of the class's send-data methods ( and ). The following example encodes a string into a byte array buffer using the property and then transmits the buffer to the network device using the **Send** method. The **Send** method returns the number of bytes sent to the network device. ```vb Dim msg As Byte() = _ diff --git a/docs/framework/network-programming/using-an-asynchronous-client-socket.md b/docs/framework/network-programming/using-an-asynchronous-client-socket.md index 29f83654d2240..c3c9abc813547 100644 --- a/docs/framework/network-programming/using-an-asynchronous-client-socket.md +++ b/docs/framework/network-programming/using-an-asynchronous-client-socket.md @@ -37,9 +37,9 @@ An asynchronous client socket does not suspend the application while waiting for Asynchronous operations require a callback method to return the result of the operation. If your application does not need to know the result, then no callback method is required. The example code in this section demonstrates using a method to start connecting to a network device and a callback method to complete the connection, a method to start sending data and a callback method to complete the send, and a method to start receiving data and a callback method to end receiving data. - Asynchronous sockets use multiple threads from the system thread pool to process network connections. One thread is responsible for initiating the sending or receiving of data; other threads complete the connection to the network device and send or receive the data. In the following examples, instances of the class are used to suspend execution of the main thread and signal when execution can continue. + Asynchronous sockets use multiple threads from the system thread pool to process network connections. One thread is responsible for initiating the sending or receiving of data; other threads complete the connection to the network device and send or receive the data. In the following examples, instances of the class are used to suspend execution of the main thread and signal when execution can continue. - In the following example, to connect an asynchronous socket to a network device, the `Connect` method initializes a **Socket** and then calls the method, passing a remote endpoint that represents the network device, the connect callback method, and a state object (the client **Socket**), which is used to pass state information between asynchronous calls. The example implements the `Connect` method to connect the specified **Socket** to the specified endpoint. It assumes a global **ManualResetEvent** named `connectDone`. + In the following example, to connect an asynchronous socket to a network device, the `Connect` method initializes a **Socket** and then calls the method, passing a remote endpoint that represents the network device, the connect callback method, and a state object (the client **Socket**), which is used to pass state information between asynchronous calls. The example implements the `Connect` method to connect the specified **Socket** to the specified endpoint. It assumes a global **ManualResetEvent** named `connectDone`. ```vb Public Shared Sub Connect(remoteEP As EndPoint, client As Socket) diff --git a/docs/framework/network-programming/using-an-asynchronous-server-socket.md b/docs/framework/network-programming/using-an-asynchronous-server-socket.md index 2e79da4013a28..2e076807d4df2 100644 --- a/docs/framework/network-programming/using-an-asynchronous-server-socket.md +++ b/docs/framework/network-programming/using-an-asynchronous-server-socket.md @@ -63,7 +63,7 @@ listener.BeginAccept( listener); ``` - Asynchronous sockets use threads from the system thread pool to process incoming connections. One thread is responsible for accepting connections, another thread is used to handle each incoming connection, and another thread is responsible for receiving data from the connection. These could be the same thread, depending on which thread is assigned by the thread pool. In the following example, the class suspends execution of the main thread and signals when execution can continue. + Asynchronous sockets use threads from the system thread pool to process incoming connections. One thread is responsible for accepting connections, another thread is used to handle each incoming connection, and another thread is responsible for receiving data from the connection. These could be the same thread, depending on which thread is assigned by the thread pool. In the following example, the class suspends execution of the main thread and signals when execution can continue. The following example shows an asynchronous method that creates an asynchronous TCP/IP socket on the local computer and begins accepting connections. It assumes that there is a global **ManualResetEvent** named `allDone`, that the method is a member of a class named `SocketListener`, and that a callback method named `acceptCallback` is defined. diff --git a/docs/framework/network-programming/using-streams-on-the-network.md b/docs/framework/network-programming/using-streams-on-the-network.md index 4c78064022d63..eabfde7621c5a 100644 --- a/docs/framework/network-programming/using-streams-on-the-network.md +++ b/docs/framework/network-programming/using-streams-on-the-network.md @@ -33,7 +33,7 @@ manager: "markl" # Using Streams on the Network Network resources are represented in the .NET Framework as streams. By treating streams generically, the .NET Framework offers the following capabilities: -- A common way to send and receive Web data. Whatever the actual contents of the file — HTML, XML, or anything else — your application will use and to send and receive data. +- A common way to send and receive Web data. Whatever the actual contents of the file — HTML, XML, or anything else — your application will use and to send and receive data. - Compatibility with streams across the .NET Framework. Streams are used throughout the .NET Framework, which has a rich infrastructure for handling them. For example, you can modify an application that reads XML data from a to read data from a instead by changing only the few lines of code that initialize the stream. The major differences between the **NetworkStream** class and other streams are that **NetworkStream** is not seekable, the property always returns **false**, and the and methods throw a . diff --git a/docs/framework/performance/contention-etw-events.md b/docs/framework/performance/contention-etw-events.md index d1a72e567a5bb..aedbf02595aca 100644 --- a/docs/framework/performance/contention-etw-events.md +++ b/docs/framework/performance/contention-etw-events.md @@ -19,7 +19,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Contention ETW Events -Contention events are raised whenever there is contention for locks or native locks used by the runtime. Contention occurs when a thread is waiting for a lock while another thread possesses the lock. +Contention events are raised whenever there is contention for locks or native locks used by the runtime. Contention occurs when a thread is waiting for a lock while another thread possesses the lock. The following table shows the keyword under which contention events are raised, and the level of the events. (For more information, see [CLR ETW Keywords and Levels](../../../docs/framework/performance/clr-etw-keywords-and-levels.md).) diff --git a/docs/framework/performance/etw-events-in-task-parallel-library-and-plinq.md b/docs/framework/performance/etw-events-in-task-parallel-library-and-plinq.md index 014886d56cf54..654e6c9deb8d6 100644 --- a/docs/framework/performance/etw-events-in-task-parallel-library-and-plinq.md +++ b/docs/framework/performance/etw-events-in-task-parallel-library-and-plinq.md @@ -21,7 +21,7 @@ manager: "wpickett" Both the Task Parallel Library and PLINQ generate Event Trace for Windows (ETW) events that you can use to profile and troubleshoot applications by using tools such as the Windows Performance Analyzer. However, in most scenarios, the best way to profile parallel application code is to use the [Concurrency Visualizer](/visualstudio/profiling/concurrency-visualizer) in [!INCLUDE[vsUltShort](../../../includes/vsultshort-md.md)]. ## Task Parallel Library ETW Events - In the EVENT_HEADER structure, the ProviderId GUID for events generated by , and is: + In the EVENT_HEADER structure, the ProviderId GUID for events generated by , and is: ``` 0x2e5dba47, 0xa3d2, 0x4d16, 0x8e, 0xe0, 0x66, 0x71, 0xff, 0xdc, 0xd7, 0xb5 @@ -36,12 +36,12 @@ Both the Task Parallel Library and PLINQ generate Event Trace for Windows (ETW) |**Name**|**Type**|**Description**| |--------------|--------------|---------------------| -|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| -|OriginatingTaskID||The ID of the task that started the loop.| -|ForkJoinContextID||A unique identifier used to indicate nesting and pairs for events with fork/join semantics.| -|OperationType||Indicates the type of loop:

1 = ParallelInvoke

2 = ParallelFor

3 = ParallelForEach| -|InclusiveFrom||The starting value of the loop counter| -|ExclusiveTo||The ending value of the loop counter| +|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| +|OriginatingTaskID||The ID of the task that started the loop.| +|ForkJoinContextID||A unique identifier used to indicate nesting and pairs for events with fork/join semantics.| +|OperationType||Indicates the type of loop:

1 = ParallelInvoke

2 = ParallelFor

3 = ParallelForEach| +|InclusiveFrom||The starting value of the loop counter| +|ExclusiveTo||The ending value of the loop counter| ### Parallel Loop End EVENT_DESCRIPTOR.Task = 2 @@ -52,10 +52,10 @@ Both the Task Parallel Library and PLINQ generate Event Trace for Windows (ETW) |**Name**|**Type**|**Description**| |--------------|--------------|---------------------| -|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| -|OriginatingTaskID||The ID of the task that started the loop.| -|ForkJoinContextID||A unique identifier used to indicate nesting and pairs for events with fork/join semantics.| -|totalIterations||The total number of iterations| +|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| +|OriginatingTaskID||The ID of the task that started the loop.| +|ForkJoinContextID||A unique identifier used to indicate nesting and pairs for events with fork/join semantics.| +|totalIterations||The total number of iterations| ### Parallel Invoke Begin EVENT_DESCRIPTOR.Task = 3 @@ -66,12 +66,12 @@ Both the Task Parallel Library and PLINQ generate Event Trace for Windows (ETW) |**Name**|**Type**|**Description**| |--------------|--------------|---------------------| -|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| -|OriginatingTaskID||The ID of the task that started the loop.| -|ForkJoinContextID||A unique identifier used to indicate nesting and pairs for events with fork/join semantics.| -|totalIterations||The total number of iterations| -|operationType||Indicates the type of loop:

1 = ParallelInvoke

2 = ParallelFor

3 = ParallelForEach| -|ActionCount||The number of actions that will be executed in the parallel invoke.| +|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| +|OriginatingTaskID||The ID of the task that started the loop.| +|ForkJoinContextID||A unique identifier used to indicate nesting and pairs for events with fork/join semantics.| +|totalIterations||The total number of iterations| +|operationType||Indicates the type of loop:

1 = ParallelInvoke

2 = ParallelFor

3 = ParallelForEach| +|ActionCount||The number of actions that will be executed in the parallel invoke.| ### Parallel Invoke End EVENT_DESCRIPTOR.Task = 4 @@ -82,9 +82,9 @@ Both the Task Parallel Library and PLINQ generate Event Trace for Windows (ETW) |**Name**|**Type**|**Description**| |--------------|--------------|---------------------| -|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| -|OriginatingTaskID||The ID of the task that started the loop.| -|ForkJoinContextID||A unique identifier used to indicate nesting and pairs for events with fork/join semantics.| +|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| +|OriginatingTaskID||The ID of the task that started the loop.| +|ForkJoinContextID||A unique identifier used to indicate nesting and pairs for events with fork/join semantics.| ## PLINQ ETW Events The EVENT_HEADER.ProviderId GUID for PLINQ is: @@ -102,9 +102,9 @@ Both the Task Parallel Library and PLINQ generate Event Trace for Windows (ETW) |**Name**|**Type**|**Description**| |--------------|--------------|---------------------| -|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| -|OriginatingTaskID||The ID of the task that started the loop.| -|QueryID||A unique query identifier.| +|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| +|OriginatingTaskID||The ID of the task that started the loop.| +|QueryID||A unique query identifier.| ### Parallel Query End EVENT_DESCRIPTOR.Task = 2 @@ -115,9 +115,9 @@ Both the Task Parallel Library and PLINQ generate Event Trace for Windows (ETW) |**Name**|**Type**|**Description**| |--------------|--------------|---------------------| -|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| -|OriginatingTaskID||The ID of the task that started the loop.| -|QueryID||A unique query identifier.| +|OriginatingTaskSchedulerID||The ID of the TaskScheduler that started the loop.| +|OriginatingTaskID||The ID of the task that started the loop.| +|QueryID||A unique query identifier.| ## See Also [ETW Events in the .NET Framework](../../../docs/framework/performance/etw-events.md) diff --git a/docs/framework/performance/how-to-perform-lazy-initialization-of-objects.md b/docs/framework/performance/how-to-perform-lazy-initialization-of-objects.md index a7d37150dabdb..92b83a03b7a1e 100644 --- a/docs/framework/performance/how-to-perform-lazy-initialization-of-objects.md +++ b/docs/framework/performance/how-to-perform-lazy-initialization-of-objects.md @@ -18,7 +18,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Perform Lazy Initialization of Objects -The class simplifies the work of performing lazy initialization and instantiation of objects. By initializing objects in a lazy manner, you can avoid having to create them at all if they are never needed, or you can postpone their initialization until they are first accessed. For more information, see [Lazy Initialization](../../../docs/framework/performance/lazy-initialization.md). +The class simplifies the work of performing lazy initialization and instantiation of objects. By initializing objects in a lazy manner, you can avoid having to create them at all if they are never needed, or you can postpone their initialization until they are first accessed. For more information, see [Lazy Initialization](../../../docs/framework/performance/lazy-initialization.md). ## Example The following example shows how to initialize a value with . Assume that the lazy variable might not be needed, depending on some other code that sets the `someCondition` variable to true or false. @@ -72,11 +72,11 @@ End Sub ``` ## Example - The following example shows how to use the class to initialize a type that is visible only to the current object instance on the current thread. + The following example shows how to use the class to initialize a type that is visible only to the current object instance on the current thread. [!code-csharp[CDS#13](../../../samples/snippets/csharp/VS_Snippets_Misc/cds/cs/cds2.cs#13)] [!code-vb[CDS#13](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds/vb/lazyhowto.vb#13)] ## See Also - + [Lazy Initialization](../../../docs/framework/performance/lazy-initialization.md) diff --git a/docs/framework/performance/lazy-initialization.md b/docs/framework/performance/lazy-initialization.md index 103c6a5ee8899..cdb46bbe14fa5 100644 --- a/docs/framework/performance/lazy-initialization.md +++ b/docs/framework/performance/lazy-initialization.md @@ -35,7 +35,7 @@ manager: "wpickett" ||Provides advanced `static` (`Shared` in Visual Basic) methods for lazy initialization of objects without the overhead of a class.| ## Basic Lazy Initialization - To define a lazy-initialized type, for example, `MyType`, use `Lazy` (`Lazy(Of MyType)` in Visual Basic), as shown in the following example. If no delegate is passed in the constructor, the wrapped type is created by using when the value property is first accessed. If the type does not have a default constructor, a run-time exception is thrown. + To define a lazy-initialized type, for example, `MyType`, use `Lazy` (`Lazy(Of MyType)` in Visual Basic), as shown in the following example. If no delegate is passed in the constructor, the wrapped type is created by using when the value property is first accessed. If the type does not have a default constructor, a run-time exception is thrown. In the following example, assume that `Orders` is a class that contains an array of `Order` objects retrieved from a database. A `Customer` object contains an instance of `Orders`, but depending on user actions, the data from the `Orders` object might not be required. @@ -82,20 +82,20 @@ manager: "wpickett" |Not thread-safe.||`false`|Not applicable.| |Fully thread-safe; threads race to initialize the value.||Not applicable.|Not applicable.| - As the table shows, specifying for the `mode` parameter is the same as specifying `true` for the `isThreadSafe` parameter, and specifying is the same as specifying `false`. + As the table shows, specifying for the `mode` parameter is the same as specifying `true` for the `isThreadSafe` parameter, and specifying is the same as specifying `false`. - Specifying allows multiple threads to attempt to initialize the instance. Only one thread can win this race, and all the other threads receive the value that was initialized by the successful thread. If an exception is thrown on a thread during initialization, that thread does not receive the value set by the successful thread. Exceptions are not cached, so a subsequent attempt to access the property can result in successful initialization. This differs from the way exceptions are treated in other modes, which is described in the following section. For more information, see the enumeration. + Specifying allows multiple threads to attempt to initialize the instance. Only one thread can win this race, and all the other threads receive the value that was initialized by the successful thread. If an exception is thrown on a thread during initialization, that thread does not receive the value set by the successful thread. Exceptions are not cached, so a subsequent attempt to access the property can result in successful initialization. This differs from the way exceptions are treated in other modes, which is described in the following section. For more information, see the enumeration. ## Exceptions in Lazy Objects As stated earlier, a object always returns the same object or value that it was initialized with, and therefore the property is read-only. If you enable exception caching, this immutability also extends to exception behavior. If a lazy-initialized object has exception caching enabled and throws an exception from its initialization method when the property is first accessed, that same exception is thrown on every subsequent attempt to access the property. In other words, the constructor of the wrapped type is never re-invoked, even in multithreaded scenarios. Therefore, the object cannot throw an exception on one access and return a value on a subsequent access. - Exception caching is enabled when you use any constructor that takes an initialization method (`valueFactory` parameter); for example, it is enabled when you use the `Lazy(T)(Func(T))`constructor. If the constructor also takes a value (`mode` parameter), specify or . Specifying an initialization method enables exception caching for these two modes. The initialization method can be very simple. For example, it might call the default constructor for `T`: `new Lazy(() => new Contents(), mode)` in C#, or `New Lazy(Of Contents)(Function() New Contents())` in Visual Basic. If you use a constructor that does not specify an initialization method, exceptions that are thrown by the default constructor for `T` are not cached. For more information, see the enumeration. + Exception caching is enabled when you use any constructor that takes an initialization method (`valueFactory` parameter); for example, it is enabled when you use the `Lazy(T)(Func(T))`constructor. If the constructor also takes a value (`mode` parameter), specify or . Specifying an initialization method enables exception caching for these two modes. The initialization method can be very simple. For example, it might call the default constructor for `T`: `new Lazy(() => new Contents(), mode)` in C#, or `New Lazy(Of Contents)(Function() New Contents())` in Visual Basic. If you use a constructor that does not specify an initialization method, exceptions that are thrown by the default constructor for `T` are not cached. For more information, see the enumeration. > [!NOTE] -> If you create a object with the `isThreadSafe` constructor parameter set to `false` or the `mode` constructor parameter set to , you must access the object from a single thread or provide your own synchronization. This applies to all aspects of the object, including exception caching. +> If you create a object with the `isThreadSafe` constructor parameter set to `false` or the `mode` constructor parameter set to , you must access the object from a single thread or provide your own synchronization. This applies to all aspects of the object, including exception caching. - As noted in the previous section, objects created by specifying treat exceptions differently. With , multiple threads can compete to initialize the instance. In this case, exceptions are not cached, and attempts to access the property can continue until initialization is successful. + As noted in the previous section, objects created by specifying treat exceptions differently. With , multiple threads can compete to initialize the instance. In this case, exceptions are not cached, and attempts to access the property can continue until initialization is successful. The following table summarizes the way the constructors control exception caching. @@ -122,7 +122,7 @@ manager: "wpickett" [!code-csharp[Lazy#6](../../../samples/snippets/csharp/VS_Snippets_Misc/lazy/cs/cs_lazycodefile.cs#6)] [!code-vb[Lazy#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/lazy/vb/lazy_vb.vb#6)] - On all other threads, the variable will be initialized by using its default value (zero). As an alternative in the .NET Framework version 4, you can use the type to create an instance-based, thread-local variable that is initialized on all threads by the delegate that you provide. In the following example, all threads that access `counter` will see its starting value as 1. + On all other threads, the variable will be initialized by using its default value (zero). As an alternative in the .NET Framework version 4, you can use the type to create an instance-based, thread-local variable that is initialized on all threads by the delegate that you provide. In the following example, all threads that access `counter` will see its starting value as 1. [!code-csharp[Lazy#7](../../../samples/snippets/csharp/VS_Snippets_Misc/lazy/cs/cs_lazycodefile.cs#7)] [!code-vb[Lazy#7](../../../samples/snippets/visualbasic/VS_Snippets_Misc/lazy/vb/lazy_vb.vb#7)] @@ -131,7 +131,7 @@ manager: "wpickett" - Each thread initializes the thread-local variable by using its own private data that is not accessible from other threads. -- The property is read-write, and can be modified any number of times. This can affect exception propagation, for example, one `get` operation can raise an exception but the next one can successfully initialize the value. +- The property is read-write, and can be modified any number of times. This can affect exception propagation, for example, one `get` operation can raise an exception but the next one can successfully initialize the value. - If no initialization delegate is provided, will initialize its wrapped type by using the default value of the type. In this regard, is consistent with the attribute. @@ -141,17 +141,17 @@ manager: "wpickett" [!code-vb[Lazy#9](../../../samples/snippets/visualbasic/VS_Snippets_Misc/lazy/vb/lazy_vb.vb#9)] ## Thread-Local Variables in Parallel.For and ForEach - When you use the method or method to iterate over data sources in parallel, you can use the overloads that have built-in support for thread-local data. In these methods, the thread-locality is achieved by using local delegates to create, access, and clean up the data. For more information, see [How to: Write a Parallel.For Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md) and [How to: Write a Parallel.ForEach Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md). + When you use the method or method to iterate over data sources in parallel, you can use the overloads that have built-in support for thread-local data. In these methods, the thread-locality is achieved by using local delegates to create, access, and clean up the data. For more information, see [How to: Write a Parallel.For Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md) and [How to: Write a Parallel.ForEach Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md). ## Using Lazy Initialization for Low-Overhead Scenarios - In scenarios where you have to lazy-initialize a large number of objects, you might decide that wrapping each object in a requires too much memory or too many computing resources. Or, you might have stringent requirements about how lazy initialization is exposed. In such cases, you can use the `static` (`Shared` in Visual Basic) methods of the class to lazy-initialize each object without wrapping it in an instance of . + In scenarios where you have to lazy-initialize a large number of objects, you might decide that wrapping each object in a requires too much memory or too many computing resources. Or, you might have stringent requirements about how lazy initialization is exposed. In such cases, you can use the `static` (`Shared` in Visual Basic) methods of the class to lazy-initialize each object without wrapping it in an instance of . In the following example, assume that, instead of wrapping an entire `Orders` object in one object, you have lazy-initialized individual `Order` objects only if they are required. [!code-csharp[Lazy#10](../../../samples/snippets/csharp/VS_Snippets_Misc/lazy/cs/cs_lazycodefile.cs#10)] [!code-vb[Lazy#10](../../../samples/snippets/visualbasic/VS_Snippets_Misc/lazy/vb/lazy_vb.vb#10)] - In this example, notice that the initialization procedure is invoked on every iteration of the loop. In multi-threaded scenarios, the first thread to invoke the initialization procedure is the one whose value is seen by all threads. Later threads also invoke the initialization procedure, but their results are not used. If this kind of potential race condition is not acceptable, use the overload of that takes a Boolean argument and a synchronization object. + In this example, notice that the initialization procedure is invoked on every iteration of the loop. In multi-threaded scenarios, the first thread to invoke the initialization procedure is the one whose value is seen by all threads. Later threads also invoke the initialization procedure, but their results are not used. If this kind of potential race condition is not acceptable, use the overload of that takes a Boolean argument and a synchronization object. ## See Also [Managed Threading Basics](../../../docs/standard/threading/managed-threading-basics.md) diff --git a/docs/framework/performance/performance-tips.md b/docs/framework/performance/performance-tips.md index 6d706da4f4156..a970dc1981ea6 100644 --- a/docs/framework/performance/performance-tips.md +++ b/docs/framework/performance/performance-tips.md @@ -24,10 +24,10 @@ manager: "wpickett" The term *performance* generally refers to the execution speed of a program. You can sometimes increase execution speed by following certain basic rules in your source code. In some programs, it is important to examine code closely and use profilers to make sure that it is running as fast as possible. In other programs, you do not have to perform such optimization because the code is running acceptably fast as it is written. This article lists some common areas where performance can suffer and tips for improving it as well as links to additional performance topics. For more information about planning and measuring for performance, see [Performance](../../../docs/framework/performance/index.md) ## Boxing and Unboxing - It is best to avoid using value types in situations where they must be boxed a high number of times, for example in non-generic collections classes such as . You can avoid boxing of value types by using generic collections such as . Boxing and unboxing are computationally expensive processes. When a value type is boxed, an entirely new object must be created. This can take up to 20 times longer than a simple reference assignment. When unboxing, the casting process can take four times as long as an assignment. For more information, see [Boxing and Unboxing](~/docs/csharp/programming-guide/types/boxing-and-unboxing.md). + It is best to avoid using value types in situations where they must be boxed a high number of times, for example in non-generic collections classes such as . You can avoid boxing of value types by using generic collections such as . Boxing and unboxing are computationally expensive processes. When a value type is boxed, an entirely new object must be created. This can take up to 20 times longer than a simple reference assignment. When unboxing, the casting process can take four times as long as an assignment. For more information, see [Boxing and Unboxing](~/docs/csharp/programming-guide/types/boxing-and-unboxing.md). ## Strings - When you concatenate a large number of string variables, for example in a tight loop, use instead of the C# [+ operator](~/docs/csharp/language-reference/operators/addition-operator.md) or the Visual Basic [Concatenation Operators](~/docs/visual-basic/language-reference/operators/concatenation-operators.md). For more information, see [How to: Concatenate Multiple Strings](~/docs/csharp/programming-guide/strings/how-to-concatenate-multiple-strings.md) and [Concatenation Operators in Visual Basic](~/docs/visual-basic/programming-guide/language-features/operators-and-expressions/concatenation-operators.md). + When you concatenate a large number of string variables, for example in a tight loop, use instead of the C# [+ operator](~/docs/csharp/language-reference/operators/addition-operator.md) or the Visual Basic [Concatenation Operators](~/docs/visual-basic/language-reference/operators/concatenation-operators.md). For more information, see [How to: Concatenate Multiple Strings](~/docs/csharp/programming-guide/strings/how-to-concatenate-multiple-strings.md) and [Concatenation Operators in Visual Basic](~/docs/visual-basic/programming-guide/language-features/operators-and-expressions/concatenation-operators.md). ## Destructors Empty destructors should not be used. When a class contains a destructor, an entry is created in the Finalize queue. When the destructor is called, the garbage collector is invoked to process the queue. If the destructor is empty, this simply results in a loss of performance. For more information, see [Destructors](~/docs/csharp/programming-guide/classes-and-structs/destructors.md) and [Object Lifetime: How Objects Are Created and Destroyed](~/docs/visual-basic/programming-guide/language-features/objects-and-classes/object-lifetime-how-objects-are-created-and-destroyed.md). diff --git a/docs/framework/performance/reliability-best-practices.md b/docs/framework/performance/reliability-best-practices.md index 7d0bdc0ddc831..52cfb4bb0f0a5 100644 --- a/docs/framework/performance/reliability-best-practices.md +++ b/docs/framework/performance/reliability-best-practices.md @@ -90,7 +90,7 @@ The following reliability rules are oriented to SQL Server; however, they also a Most classes that currently have a finalizer to simply clean up an operating system handle will not need the finalizer anymore. Instead, the finalizer will be on the derived class. - Note that is not a replacement for . There are still potential resource contention and performance advantages to explicitly dispose operating system resources. Just realize that `finally` blocks that do explicitly dispose of resources may not execute to completion. + Note that is not a replacement for . There are still potential resource contention and performance advantages to explicitly dispose operating system resources. Just realize that `finally` blocks that do explicitly dispose of resources may not execute to completion. allows you to implement your own method that performs the work to free the handle, such as passing state to an operating system handle freeing routine or freeing a set of handles in a loop. The CLR guarantees that this method is run. It is the responsibility of the author of the implementation to ensure that the handle is released in all circumstances. Failure to do so will cause the handle to be leaked, which often results in the leakage of native resources associated with the handle. Therefore it is critical to structure derived classes such that the implementation does not require the allocation of any resources that may not be available at invocation time. Note that it is permissible to call methods that may fail within the implementation of provided that your code can handle such failures and complete the contract to release the native handle. For debugging purposes, has a return value which may be set to `false` if a catastrophic error is encountered which prevents release of the resource. Doing so will activate the [releaseHandleFailed](../../../docs/framework/debug-trace-profile/releasehandlefailed-mda.md) MDA, if enabled, to aid in identifying the problem. It does not affect the runtime in any other way; will not be called again for the same resource and consequently the handle will be leaked. diff --git a/docs/framework/performance/sql-server-programming-and-host-protection-attributes.md b/docs/framework/performance/sql-server-programming-and-host-protection-attributes.md index c63b71c19ec45..0ec9607a1e6eb 100644 --- a/docs/framework/performance/sql-server-programming-and-host-protection-attributes.md +++ b/docs/framework/performance/sql-server-programming-and-host-protection-attributes.md @@ -45,16 +45,16 @@ The ability to load and execute managed code in a SQL Server host requires meeti |Namespace|Type or member| |---------------|--------------------| |`Microsoft.Win32`| class

delegate

class

delegate

class

delegate

class

delegate

class

class

delegate

class

class| -|`System.Collections`| method

method

method

method

method| +|`System.Collections`| method

method

method

method

method| |`System.ComponentModel`| class

delegate

class

class

delegate

class

class

class

class

class

class

class

class

class

delegate

class

class

delegate

class

class

class

class

class

class

class

class

class

class

class

class

delegate

class

class

class

delegate

class

delegate

class

delegate

class

delegate

class

class

delegate

class

class

class

delegate

class

class

class

class

class

class

class

class

class

class

class

delegate

class

class

delegate

class

class

class

class

delegate

class

class

class

class

class

class

delegate

class

class

class

class

class

class

method

class

class

class

class

class

class

class

delegate

class

class

class

class

class

class

class

class

delegate

class

delegate

class

class

class

class

delegate

class

delegate

class

class

class

class

class

class

class

class

class

class

class

class

class

class| -|`System.Diagnostics`| property

property

property

class

class

class

class

class

class

class

class

class

class

class

property| -|`System.IO`| method

method

method| +|`System.Diagnostics`| property

property

property

class

class

class

class

class

class

class

class

class

class

class

property| +|`System.IO`| method

method

method| |`System.Reflection.Emit`| class

class

class

class

class

class

class

class

class

class| -|`System.Text`| method

method| -|`System.Threading`| class

class

class

class

class

class

class

method

method

method

method

method

method

method

method

method

method

method

class

class| +|`System.Text`| method

method| +|`System.Threading`| class

class

class

class

class

class

class

method

method

method

method

method

method

method

method

method

method

method

class

class| |`System.Timers`| class| |`System.Web.Configuration`| class| -|`System.Windows.Forms`| property| +|`System.Windows.Forms`| property| ## SQL Server Permission Sets SQL Server allows users to specify the reliability requirements for code deployed into a database. When assemblies are uploaded into the database, the author of the assembly can specify one of three permission sets for that assembly: SAFE, EXTERNAL-ACCESS, or UNSAFE. diff --git a/docs/framework/performance/writing-large-responsive-apps.md b/docs/framework/performance/writing-large-responsive-apps.md index 1c166db37d280..a1f605ec56153 100644 --- a/docs/framework/performance/writing-large-responsive-apps.md +++ b/docs/framework/performance/writing-large-responsive-apps.md @@ -56,7 +56,7 @@ This article provides tips for improving the performance of large .NET Framework ### Boxing [Boxing](~/docs/csharp/programming-guide/types/boxing-and-unboxing.md) occurs when value types that normally live on the stack or in data structures are wrapped in an object. That is, you allocate an object to hold the data, and then return a pointer to the object. The .NET Framework sometimes boxes values due to the signature of a method or the type of a storage location. Wrapping a value type in an object causes memory allocation. Many boxing operations can contribute megabytes or gigabytes of allocations to your app, which means that your app will cause more GCs. The .NET Framework and the language compilers avoid boxing when possible, but sometimes it happens when you least expect it. - To see boxing in PerfView, open a trace and look at GC Heap Alloc Stacks under your app’s process name (remember, PerfView reports on all processes). If you see types like and under allocations, you are boxing value types. Choosing one of these types will show the stacks and functions in which they are boxed. + To see boxing in PerfView, open a trace and look at GC Heap Alloc Stacks under your app’s process name (remember, PerfView reports on all processes). If you see types like and under allocations, you are boxing value types. Choosing one of these types will show the stacks and functions in which they are boxed. **Example 1: string methods and value type arguments** @@ -129,7 +129,7 @@ public class BoxingExample ((int)color).GetHashCode() ``` - Another common source of boxing on enumeration types is the method. The argument passed to has to be boxed. In most cases, replacing calls to with a bitwise test is simpler and allocation-free. + Another common source of boxing on enumeration types is the method. The argument passed to has to be boxed. In most cases, replacing calls to with a bitwise test is simpler and allocation-free. Keep the first performance fact in mind (that is, don’t prematurely optimize) and don’t start rewriting all your code in this way. Be aware of these boxing costs, but change your code only after profiling your app and finding the hot spots. @@ -328,7 +328,7 @@ var predicate = new Func(l.Evaluate); The two `new` allocations (one for the environment class and one for the delegate) are explicit now. - Now look at the call to `FirstOrDefault`. This extension method on the type incurs an allocation too. Because `FirstOrDefault` takes an object as its first argument, you can expand the call to the following code (simplified a bit for discussion): + Now look at the call to `FirstOrDefault`. This extension method on the type incurs an allocation too. Because `FirstOrDefault` takes an object as its first argument, you can expand the call to the following code (simplified a bit for discussion): ```csharp // Expanded return symbols.FirstOrDefault(predicate) ... diff --git a/docs/framework/reflection-and-codedom/accessing-custom-attributes.md b/docs/framework/reflection-and-codedom/accessing-custom-attributes.md index 8294932cb0a4e..77ebfc4949dd7 100644 --- a/docs/framework/reflection-and-codedom/accessing-custom-attributes.md +++ b/docs/framework/reflection-and-codedom/accessing-custom-attributes.md @@ -23,14 +23,14 @@ manager: "wpickett" After attributes have been associated with program elements, reflection can be used to query their existence and values. In the .NET Framework version 1.0 and 1.1, custom attributes are examined in the execution context. The .NET Framework version 2.0 provides a new load context, the reflection-only context, which can be used to examine code that cannot be loaded for execution. ## The Reflection-Only Context - Code loaded into the reflection-only context cannot be executed. This means that instances of custom attributes cannot be created, because that would require executing their constructors. To load and examine custom attributes in the reflection-only context, use the class. You can obtain instances of this class by using the appropriate overload of the static method. See [How to: Load Assemblies into the Reflection-Only Context](../../../docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md). + Code loaded into the reflection-only context cannot be executed. This means that instances of custom attributes cannot be created, because that would require executing their constructors. To load and examine custom attributes in the reflection-only context, use the class. You can obtain instances of this class by using the appropriate overload of the static method. See [How to: Load Assemblies into the Reflection-Only Context](../../../docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md). ## The Execution Context - The main reflection methods to query attributes in the execution context are and . + The main reflection methods to query attributes in the execution context are and . The accessibility of a custom attribute is checked with respect to the assembly in which it is attached. This is equivalent to checking whether a method on a type in the assembly in which the custom attribute is attached can call the constructor of the custom attribute. - Methods such as check the visibility and accessibility of the type argument. Only code in the assembly that contains the user-defined type can retrieve a custom attribute of that type using **GetCustomAttributes**. + Methods such as check the visibility and accessibility of the type argument. Only code in the assembly that contains the user-defined type can retrieve a custom attribute of that type using **GetCustomAttributes**. The following C# example is a typical custom attribute design pattern. It illustrates the runtime custom attribute reflection model. @@ -64,7 +64,7 @@ public class LocalizationExtenderProvider 4. The runtime calls the constructor of **MyDescriptionAttribute** with the custom attribute parameters and returns the new object to the caller. - The custom attribute reflection model could leak instances of user-defined types outside the assembly in which the type is defined. This is no different from the members in the runtime system library that return instances of user-defined types, such as returning an array of **RuntimeMethodInfo** objects. To prevent a client from discovering information about a user-defined custom attribute type, define the type's members to be nonpublic. + The custom attribute reflection model could leak instances of user-defined types outside the assembly in which the type is defined. This is no different from the members in the runtime system library that return instances of user-defined types, such as returning an array of **RuntimeMethodInfo** objects. To prevent a client from discovering information about a user-defined custom attribute type, define the type's members to be nonpublic. The following example demonstrates the basic way of using reflection to get access to custom attributes. @@ -73,7 +73,7 @@ public class LocalizationExtenderProvider [!code-vb[CustomAttributeData#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/CustomAttributeData/VB/source2.vb#2)] ## See Also - - + + [Viewing Type Information](../../../docs/framework/reflection-and-codedom/viewing-type-information.md) [Security Considerations for Reflection](../../../docs/framework/reflection-and-codedom/security-considerations-for-reflection.md) diff --git a/docs/framework/reflection-and-codedom/collectible-assemblies.md b/docs/framework/reflection-and-codedom/collectible-assemblies.md index 63faf347485ff..0a052a3ed6561 100644 --- a/docs/framework/reflection-and-codedom/collectible-assemblies.md +++ b/docs/framework/reflection-and-codedom/collectible-assemblies.md @@ -19,7 +19,7 @@ manager: "wpickett" *Collectible assemblies* are dynamic assemblies that can be unloaded without unloading the application domain in which they were created. All managed and unmanaged memory used by a collectible assembly and the types it contains can be reclaimed. Information such as the assembly name is removed from internal tables. -To enable unloading, use the flag when you create a dynamic assembly. The assembly is transient (that is, it cannot be saved) and is subject to limitations described in the [Restrictions on Collectible Assemblies](#restrictions-on-collectible-assemblies) section. The common language runtime (CLR) unloads a collectible assembly automatically when you release all objects associated with the assembly. In all other respects, collectible assemblies are created and used in the same way as other dynamic assemblies. +To enable unloading, use the flag when you create a dynamic assembly. The assembly is transient (that is, it cannot be saved) and is subject to limitations described in the [Restrictions on Collectible Assemblies](#restrictions-on-collectible-assemblies) section. The common language runtime (CLR) unloads a collectible assembly automatically when you release all objects associated with the assembly. In all other respects, collectible assemblies are created and used in the same way as other dynamic assemblies. ## Lifetime of collectible assemblies @@ -66,7 +66,7 @@ The following restrictions apply to collectible assemblies: No COM interfaces can be defined within a collectible assembly, and no instances of types within a collectible assembly can be converted into COM objects. A type in a collectible assembly cannot serve as a COM callable wrapper (CCW) or runtime callable wrapper (RCW). However, types in collectible assemblies can use objects that implement COM interfaces. - **Platform invoke** - Methods that have the attribute will not compile when they are declared in a collectible assembly. The instruction cannot be used in the implementation of a type in a collectible assembly, and such types cannot be marshaled to unmanaged code. However, you can call into native code by using an entry point that is declared in a non-collectible assembly. + Methods that have the attribute will not compile when they are declared in a collectible assembly. The instruction cannot be used in the implementation of a type in a collectible assembly, and such types cannot be marshaled to unmanaged code. However, you can call into native code by using an entry point that is declared in a non-collectible assembly. - **Marshaling** Objects (in particular, delegates) that are defined in collectible assemblies cannot be marshaled. This is a restriction on all transient emitted types. diff --git a/docs/framework/reflection-and-codedom/dynamically-loading-and-using-types.md b/docs/framework/reflection-and-codedom/dynamically-loading-and-using-types.md index 7bbb89659e565..18134f245ab73 100644 --- a/docs/framework/reflection-and-codedom/dynamically-loading-and-using-types.md +++ b/docs/framework/reflection-and-codedom/dynamically-loading-and-using-types.md @@ -24,7 +24,7 @@ manager: "wpickett" # Dynamically Loading and Using Types Reflection provides infrastructure used by language compilers such as [!INCLUDE[vbprvbext](../../../includes/vbprvbext-md.md)] and JScript to implement implicit late binding. Binding is the process of locating the declaration (that is, the implementation) that corresponds to a uniquely specified type. When this process occurs at run time rather than at compile time, it is called late binding. [!INCLUDE[vbprvblong](../../../includes/vbprvblong-md.md)] allows you to use implicit late binding in your code; the Visual Basic compiler calls a helper method that uses reflection to obtain the object type. The arguments passed to the helper method cause the appropriate method to be invoked at run time. These arguments are the instance (an object) on which to invoke the method, the name of the invoked method (a string), and the arguments passed to the invoked method (an array of objects). - In the following example, the Visual Basic compiler uses reflection implicitly to call a method on an object whose type is not known at compile time. A **HelloWorld** class has a **PrintHello** method that prints out "Hello World" concatenated with some text that is passed to the **PrintHello** method. The **PrintHello** method called in this example is actually a ; the Visual Basic code allows the **PrintHello** method to be invoked as if the type of the object (helloObj) were known at compile time (early binding) rather than at run time (late binding). + In the following example, the Visual Basic compiler uses reflection implicitly to call a method on an object whose type is not known at compile time. A **HelloWorld** class has a **PrintHello** method that prints out "Hello World" concatenated with some text that is passed to the **PrintHello** method. The **PrintHello** method called in this example is actually a ; the Visual Basic code allows the **PrintHello** method to be invoked as if the type of the object (helloObj) were known at compile time (early binding) rather than at run time (late binding). ``` Imports System @@ -55,7 +55,7 @@ End Module [!code-vb[Conceptual.Types.Dynamic#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.types.dynamic/vb/source1.vb#1)] ### InvokeMember and CreateInstance - Use to invoke a member of a type. The **CreateInstance** methods of various classes, such as and , are specialized forms of **InvokeMember** that create new instances of the specified type. The **Binder** class is used for overload resolution and argument coercion in these methods. + Use to invoke a member of a type. The **CreateInstance** methods of various classes, such as and , are specialized forms of **InvokeMember** that create new instances of the specified type. The **Binder** class is used for overload resolution and argument coercion in these methods. The following example shows the three possible combinations of argument coercion (type conversion) and member selection. In Case 1, no argument coercion or member selection is needed. In Case 2, only member selection is needed. In Case 3, only argument coercion is needed. @@ -63,11 +63,11 @@ End Module [!code-csharp[Conceptual.Types.Dynamic#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.types.dynamic/cs/source2.cs#2)] [!code-vb[Conceptual.Types.Dynamic#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.types.dynamic/vb/source2.vb#2)] - Overload resolution is needed when more than one member with the same name is available. The and methods are used to resolve binding to a single member. **Binder.BindToMethod** also provides property resolution through the **get** and **set** property accessors. + Overload resolution is needed when more than one member with the same name is available. The and methods are used to resolve binding to a single member. **Binder.BindToMethod** also provides property resolution through the **get** and **set** property accessors. **BindToMethod** returns the to invoke, or a null reference (**Nothing** in Visual Basic) if no such invocation is possible. The **MethodBase** return value need not be one of those contained in the *match* parameter, although that is the usual case. - When ByRef arguments are present, the caller might want to get them back. Therefore, **Binder** allows a client to map the array of arguments back to its original form if **BindToMethod** has manipulated the argument array. In order to do this, the caller must be guaranteed that the order of the arguments is unchanged. When arguments are passed by name, **Binder** reorders the argument array, and that is what the caller sees. For more information, see . + When ByRef arguments are present, the caller might want to get them back. Therefore, **Binder** allows a client to map the array of arguments back to its original form if **BindToMethod** has manipulated the argument array. In order to do this, the caller must be guaranteed that the order of the arguments is unchanged. When arguments are passed by name, **Binder** reorders the argument array, and that is what the caller sees. For more information, see . The set of available members are those members defined in the type or any base type. If is specified, members of any accessibility will be returned in the set. If **BindingFlags.NonPublic** is not specified, the binder must enforce accessibility rules. When specifying the **Public** or **NonPublic** binding flag, you must also specify the **Instance** or **Static** binding flag, or no members will be returned. @@ -97,10 +97,10 @@ End Module |Single|Double| |Nonreference type|Reference type| - The class has **Get** methods that use parameters of type **Binder** to resolve references to a particular member. , , and search for a particular member of the current type by providing signature information for that member. and are called back on to select the given signature information of the appropriate methods. + The class has **Get** methods that use parameters of type **Binder** to resolve references to a particular member. , , and search for a particular member of the current type by providing signature information for that member. and are called back on to select the given signature information of the appropriate methods. ## See Also - - + + [Viewing Type Information](../../../docs/framework/reflection-and-codedom/viewing-type-information.md) [Type Conversion in the .NET Framework](../../../docs/standard/base-types/type-conversion.md) diff --git a/docs/framework/reflection-and-codedom/how-to-define-a-generic-method-with-reflection-emit.md b/docs/framework/reflection-and-codedom/how-to-define-a-generic-method-with-reflection-emit.md index 34b146133c67f..321a9af9ee375 100644 --- a/docs/framework/reflection-and-codedom/how-to-define-a-generic-method-with-reflection-emit.md +++ b/docs/framework/reflection-and-codedom/how-to-define-a-generic-method-with-reflection-emit.md @@ -31,12 +31,12 @@ The first procedure shows how to create a simple generic method with two type pa ### To define a generic method -1. Before beginning, it is useful to look at how the generic method appears when written using a high-level language. The following code is included in the example code for this topic, along with code to call the generic method. The method has two type parameters, `TInput` and `TOutput`, the second of which must be a reference type (`class`), must have a parameterless constructor (`new`), and must implement `ICollection(Of TInput)` (`ICollection` in C#). This interface constraint ensures that the method can be used to add elements to the `TOutput` collection that the method creates. The method has one formal parameter, `input`, which is an array of `TInput`. The method creates a collection of type `TOutput` and copies the elements of `input` to the collection. +1. Before beginning, it is useful to look at how the generic method appears when written using a high-level language. The following code is included in the example code for this topic, along with code to call the generic method. The method has two type parameters, `TInput` and `TOutput`, the second of which must be a reference type (`class`), must have a parameterless constructor (`new`), and must implement `ICollection(Of TInput)` (`ICollection` in C#). This interface constraint ensures that the method can be used to add elements to the `TOutput` collection that the method creates. The method has one formal parameter, `input`, which is an array of `TInput`. The method creates a collection of type `TOutput` and copies the elements of `input` to the collection. [!code-csharp[GenericMethodHowTo#20](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#20)] [!code-vb[GenericMethodHowTo#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#20)] -2. Define a dynamic assembly and a dynamic module to contain the type the generic method belongs to. In this case, the assembly has only one module, named `DemoMethodBuilder1`, and the module name is the same as the assembly name plus an extension. In this example, the assembly is saved to disk and also executed, so is specified. You can use the [Ildasm.exe (IL Disassembler)](../../../docs/framework/tools/ildasm-exe-il-disassembler.md) to examine DemoMethodBuilder1.dll and to compare it to the Microsoft intermediate language (MSIL) for the method shown in step 1. +2. Define a dynamic assembly and a dynamic module to contain the type the generic method belongs to. In this case, the assembly has only one module, named `DemoMethodBuilder1`, and the module name is the same as the assembly name plus an extension. In this example, the assembly is saved to disk and also executed, so is specified. You can use the [Ildasm.exe (IL Disassembler)](../../../docs/framework/tools/ildasm-exe-il-disassembler.md) to examine DemoMethodBuilder1.dll and to compare it to the Microsoft intermediate language (MSIL) for the method shown in step 1. [!code-csharp[GenericMethodHowTo#2](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#2)] [!code-vb[GenericMethodHowTo#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#2)] @@ -51,7 +51,7 @@ The first procedure shows how to create a simple generic method with two type pa [!code-csharp[GenericMethodHowTo#4](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#4)] [!code-vb[GenericMethodHowTo#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#4)] -5. Define the generic type parameters of `DemoMethod` by passing an array of strings containing the names of the parameters to the method. This makes the method a generic method. The following code makes `Factory` a generic method with type parameters `TInput` and `TOutput`. To make the code easier to read, variables with these names are created to hold the objects representing the two type parameters. +5. Define the generic type parameters of `DemoMethod` by passing an array of strings containing the names of the parameters to the method. This makes the method a generic method. The following code makes `Factory` a generic method with type parameters `TInput` and `TOutput`. To make the code easier to read, variables with these names are created to hold the objects representing the two type parameters. [!code-csharp[GenericMethodHowTo#5](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#5)] [!code-vb[GenericMethodHowTo#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#5)] @@ -96,7 +96,7 @@ The first procedure shows how to create a simple generic method with two type pa [!code-csharp[GenericMethodHowTo#10](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#10)] [!code-vb[GenericMethodHowTo#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#10)] -2. Emit code to create an instance of `TOutput`, using the generic method overload of the method. Using this overload requires the specified type to have a parameterless constructor, which is the reason for adding that constraint to `TOutput`. Create the constructed generic method by passing `TOutput` to . After emitting code to call the method, emit code to store it in the local variable `retVal` using +2. Emit code to create an instance of `TOutput`, using the generic method overload of the method. Using this overload requires the specified type to have a parameterless constructor, which is the reason for adding that constraint to `TOutput`. Create the constructed generic method by passing `TOutput` to . After emitting code to call the method, emit code to store it in the local variable `retVal` using [!code-csharp[GenericMethodHowTo#11](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#11)] [!code-vb[GenericMethodHowTo#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#11)] @@ -106,7 +106,7 @@ The first procedure shows how to create a simple generic method with two type pa [!code-csharp[GenericMethodHowTo#31](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#31)] [!code-vb[GenericMethodHowTo#31](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#31)] -4. Get a representing the method. The method is acting on an `ICollection(Of TInput)` (`ICollection` in C#), so it is necessary to get the `Add` method specific to that constructed type. You cannot use the method to get this directly from `icollOfTInput`, because is not supported on a type that has been constructed with a . Instead, call on `icoll`, which contains the generic type definition for the generic interface. Then use the `static` method to produce the for the constructed type. The following code demonstrates this. +4. Get a representing the method. The method is acting on an `ICollection(Of TInput)` (`ICollection` in C#), so it is necessary to get the `Add` method specific to that constructed type. You cannot use the method to get this directly from `icollOfTInput`, because is not supported on a type that has been constructed with a . Instead, call on `icoll`, which contains the generic type definition for the generic interface. Then use the `static` method to produce the for the constructed type. The following code demonstrates this. [!code-csharp[GenericMethodHowTo#12](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#12)] [!code-vb[GenericMethodHowTo#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#12)] @@ -116,14 +116,14 @@ The first procedure shows how to create a simple generic method with two type pa [!code-csharp[GenericMethodHowTo#32](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#32)] [!code-vb[GenericMethodHowTo#32](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#32)] -6. Emit code for the loop. The first step is to mark the top of the loop, by calling with the `loopAgain` label. Branch statements that use the label will now branch to this point in the code. The next step is to push the `TOutput` object, cast to `ICollection(Of TInput)`, onto the stack. It is not needed immediately, but needs to be in position for calling the `Add` method. Next the input array is pushed onto the stack, then the `index` variable containing the current index into the array. The opcode pops the index and the array off the stack and pushes the indexed array element onto the stack. The stack is now ready for the call to the method, which pops the collection and the new element off the stack and adds the element to the collection. +6. Emit code for the loop. The first step is to mark the top of the loop, by calling with the `loopAgain` label. Branch statements that use the label will now branch to this point in the code. The next step is to push the `TOutput` object, cast to `ICollection(Of TInput)`, onto the stack. It is not needed immediately, but needs to be in position for calling the `Add` method. Next the input array is pushed onto the stack, then the `index` variable containing the current index into the array. The opcode pops the index and the array off the stack and pushes the indexed array element onto the stack. The stack is now ready for the call to the method, which pops the collection and the new element off the stack and adds the element to the collection. The rest of the code in the loop increments the index and tests to see whether the loop is finished: The index and a 32-bit integer 1 are pushed onto the stack and added, leaving the sum on the stack; the sum is stored in `index`. is called to set this point as the entry point for the loop. The index is loaded again. The input array is pushed on the stack, and is emitted to get its length. The index and the length are now on the stack, and is emitted to compare them. If the index is less than the length, branches back to the beginning of the loop. [!code-csharp[GenericMethodHowTo#13](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#13)] [!code-vb[GenericMethodHowTo#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#13)] -7. Emit code to push the `TOutput` object onto the stack and return from the method. The local variables `retVal` and `ic` both contain references to the new `TOutput`; `ic` is used only to access the method. +7. Emit code to push the `TOutput` object onto the stack and return from the method. The local variables `retVal` and `ic` both contain references to the new `TOutput`; `ic` is used only to access the method. [!code-csharp[GenericMethodHowTo#33](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#33)] [!code-vb[GenericMethodHowTo#33](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#33)] @@ -141,7 +141,7 @@ The first procedure shows how to create a simple generic method with two type pa [!code-csharp[GenericMethodHowTo#22](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#22)] [!code-vb[GenericMethodHowTo#22](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#22)] -3. To invoke the method using a delegate, you must have a delegate that matches the signature of the constructed generic method. An easy way to do this is to create a generic delegate. The following code creates an instance of the generic delegate `D` defined in the example code, using the method overload, and invokes the delegate. Delegates perform better than late-bound calls. +3. To invoke the method using a delegate, you must have a delegate that matches the signature of the constructed generic method. An easy way to do this is to create a generic delegate. The following code creates an instance of the generic delegate `D` defined in the example code, using the method overload, and invokes the delegate. Delegates perform better than late-bound calls. [!code-csharp[GenericMethodHowTo#23](../../../samples/snippets/csharp/VS_Snippets_CLR/GenericMethodHowTo/CS/source.cs#23)] [!code-vb[GenericMethodHowTo#23](../../../samples/snippets/visualbasic/VS_Snippets_CLR/GenericMethodHowTo/VB/source.vb#23)] diff --git a/docs/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit.md b/docs/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit.md index 96e83e696672d..f8cab020ae7e2 100644 --- a/docs/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit.md +++ b/docs/framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit.md @@ -27,7 +27,7 @@ This topic shows how to create a simple generic type with two type parameters, h ### To define a generic type -1. Define a dynamic assembly named `GenericEmitExample1`. In this example, the assembly is executed and saved to disk, so is specified. +1. Define a dynamic assembly named `GenericEmitExample1`. In this example, the assembly is executed and saved to disk, so is specified. [!code-cpp[EmitGenericType#2](../../../samples/snippets/cpp/VS_Snippets_CLR/EmitGenericType/CPP/source.cpp#2)] [!code-csharp[EmitGenericType#2](../../../samples/snippets/csharp/VS_Snippets_CLR/EmitGenericType/CS/source.cs#2)] @@ -45,7 +45,7 @@ This topic shows how to create a simple generic type with two type parameters, h [!code-csharp[EmitGenericType#4](../../../samples/snippets/csharp/VS_Snippets_CLR/EmitGenericType/CS/source.cs#4)] [!code-vb[EmitGenericType#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/EmitGenericType/VB/source.vb#4)] -4. Define the generic type parameters of `Sample` by passing an array of strings containing the names of the parameters to the method. This makes the class a generic type. The return value is an array of objects representing the type parameters, which can be used in your emitted code. +4. Define the generic type parameters of `Sample` by passing an array of strings containing the names of the parameters to the method. This makes the class a generic type. The return value is an array of objects representing the type parameters, which can be used in your emitted code. In the following code, `Sample` becomes a generic type with type parameters `TFirst` and `TSecond`. To make the code easier to read, each is placed in a variable with the same name as the type parameter. @@ -86,7 +86,7 @@ This topic shows how to create a simple generic type with two type parameters, h > [!NOTE] > The generic type definition is expressed as `IEnumerable<>` when you use the `typeof` operator in C#, or `IEnumerable(Of )` when you use the `GetType` operator in Visual Basic. - Now it is possible to get the constructor of `List` by calling on the generic type definition. To convert this constructor to the corresponding constructor of `List`, pass `List` and the constructor from `List` to the static method. + Now it is possible to get the constructor of `List` by calling on the generic type definition. To convert this constructor to the corresponding constructor of `List`, pass `List` and the constructor from `List` to the static method. [!code-cpp[EmitGenericType#23](../../../samples/snippets/cpp/VS_Snippets_CLR/EmitGenericType/CPP/source.cpp#23)] [!code-csharp[EmitGenericType#23](../../../samples/snippets/csharp/VS_Snippets_CLR/EmitGenericType/CS/source.cs#23)] diff --git a/docs/framework/reflection-and-codedom/how-to-examine-and-instantiate-generic-types-with-reflection.md b/docs/framework/reflection-and-codedom/how-to-examine-and-instantiate-generic-types-with-reflection.md index 3d9faa22ffafa..0dd80d70449a4 100644 --- a/docs/framework/reflection-and-codedom/how-to-examine-and-instantiate-generic-types-with-reflection.md +++ b/docs/framework/reflection-and-codedom/how-to-examine-and-instantiate-generic-types-with-reflection.md @@ -67,7 +67,7 @@ Information about generic types is obtained in the same way as information about [!code-csharp[HowToGeneric#8](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToGeneric/CS/ur.cs#8)] [!code-vb[HowToGeneric#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToGeneric/VB/ur.vb#8)] -8. The special constraint attributes are flags, and the same flag () that represents no special constraints also represents no covariance or contravariance. Thus, to test for either of these conditions you must use the appropriate mask. In this case, use to isolate the special constraint flags. +8. The special constraint attributes are flags, and the same flag () that represents no special constraints also represents no covariance or contravariance. Thus, to test for either of these conditions you must use the appropriate mask. In this case, use to isolate the special constraint flags. [!code-cpp[HowToGeneric#9](../../../samples/snippets/cpp/VS_Snippets_CLR/HowToGeneric/cpp/ur.cpp#9)] [!code-csharp[HowToGeneric#9](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToGeneric/CS/ur.cs#9)] @@ -78,7 +78,7 @@ Information about generic types is obtained in the same way as information about #### To construct an instance of a generic type -1. Get a object that represents the generic type. The following code gets the generic type in two different ways: by using the method overload with a string describing the type, and by calling the method on the constructed type `Dictionary\` (`Dictionary(Of String, Example)` in Visual Basic). The method requires a generic type definition. +1. Get a object that represents the generic type. The following code gets the generic type in two different ways: by using the method overload with a string describing the type, and by calling the method on the constructed type `Dictionary\` (`Dictionary(Of String, Example)` in Visual Basic). The method requires a generic type definition. [!code-cpp[HowToGeneric#10](../../../samples/snippets/cpp/VS_Snippets_CLR/HowToGeneric/cpp/ur.cpp#10)] [!code-csharp[HowToGeneric#10](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToGeneric/CS/ur.cs#10)] diff --git a/docs/framework/reflection-and-codedom/how-to-hook-up-a-delegate-using-reflection.md b/docs/framework/reflection-and-codedom/how-to-hook-up-a-delegate-using-reflection.md index 5442aca132c42..66b1bb7810e4a 100644 --- a/docs/framework/reflection-and-codedom/how-to-hook-up-a-delegate-using-reflection.md +++ b/docs/framework/reflection-and-codedom/how-to-hook-up-a-delegate-using-reflection.md @@ -27,7 +27,7 @@ When you use reflection to load and run assemblies, you cannot use language feat ### To hook up a delegate using reflection -1. Load an assembly that contains a type that raises events. Assemblies are usually loaded with the method. To keep this example simple, a derived form in the current assembly is used, so the method is used to load the current assembly. +1. Load an assembly that contains a type that raises events. Assemblies are usually loaded with the method. To keep this example simple, a derived form in the current assembly is used, so the method is used to load the current assembly. [!code-cpp[HookUpDelegate#3](../../../samples/snippets/cpp/VS_Snippets_CLR/HookUpDelegate/cpp/source.cpp#3)] [!code-csharp[HookUpDelegate#3](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#3)] @@ -80,7 +80,7 @@ When you use reflection to load and run assemblies, you cannot use language feat [!code-csharp[HookUpDelegate#9](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#9)] [!code-vb[HookUpDelegate#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HookUpDelegate/vb/source.vb#9)] -2. Generate a method body. This method loads a string, calls the overload of the method that takes a string, pops the return value off the stack (because the handler has no return type), and returns. To learn more about emitting dynamic methods, see [How to: Define and Execute Dynamic Methods](../../../docs/framework/reflection-and-codedom/how-to-define-and-execute-dynamic-methods.md). +2. Generate a method body. This method loads a string, calls the overload of the method that takes a string, pops the return value off the stack (because the handler has no return type), and returns. To learn more about emitting dynamic methods, see [How to: Define and Execute Dynamic Methods](../../../docs/framework/reflection-and-codedom/how-to-define-and-execute-dynamic-methods.md). [!code-cpp[HookUpDelegate#10](../../../samples/snippets/cpp/VS_Snippets_CLR/HookUpDelegate/cpp/source.cpp#10)] [!code-csharp[HookUpDelegate#10](../../../samples/snippets/csharp/VS_Snippets_CLR/HookUpDelegate/cs/source.cs#10)] @@ -114,7 +114,7 @@ When you use reflection to load and run assemblies, you cannot use language feat - Compile the code at the command line using csc.exe, vbc.exe, or cl.exe. To compile the code in Visual Studio, place it in a console application project template. ## See Also - + diff --git a/docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md b/docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md index 955124bffa6a0..0fbba1ffa4ac5 100644 --- a/docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md +++ b/docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md @@ -35,7 +35,7 @@ The reflection-only load context allows you to examine assemblies compiled for o 3. Determine whether an assembly is loaded into the reflection-only context by using the assembly's property. -4. If attributes have been applied to the assembly or to types in the assembly, examine those attributes by using the class to ensure that no attempt is made to execute code in the reflection-only context. Use the appropriate overload of the method to obtain objects representing the attributes applied to an assembly, member, module, or parameter. +4. If attributes have been applied to the assembly or to types in the assembly, examine those attributes by using the class to ensure that no attempt is made to execute code in the reflection-only context. Use the appropriate overload of the method to obtain objects representing the attributes applied to an assembly, member, module, or parameter. > [!NOTE] > Attributes applied to the assembly or to its contents might be defined in the assembly, or they might be defined in another assembly loaded into the reflection-only context. There is no way to tell in advance where the attributes are defined. diff --git a/docs/framework/reflection-and-codedom/reflection-and-generic-types.md b/docs/framework/reflection-and-codedom/reflection-and-generic-types.md index 443ed8a164849..ae2f73df77412 100644 --- a/docs/framework/reflection-and-codedom/reflection-and-generic-types.md +++ b/docs/framework/reflection-and-codedom/reflection-and-generic-types.md @@ -65,7 +65,7 @@ manager: "wpickett" Generic type and method definitions are the templates from which instantiable types are created. Generic types in the .NET Framework class library, such as , are generic type definitions. ### Is the Type or Method Open or Closed? - A generic type or method is closed if instantiable types have been substituted for all its type parameters, including all the type parameters of all enclosing types. You can only create an instance of a generic type if it is closed. The property returns `true` if a type is open. For methods, the method performs the same function. + A generic type or method is closed if instantiable types have been substituted for all its type parameters, including all the type parameters of all enclosing types. You can only create an instance of a generic type if it is closed. The property returns `true` if a type is open. For methods, the method performs the same function. [Back to top](#top) @@ -84,7 +84,7 @@ manager: "wpickett" ## Examining Type Arguments and Type Parameters - Use the method to obtain an array of objects that represent the type parameters or type arguments of a generic type, and use the method to do the same for a generic method. + Use the method to obtain an array of objects that represent the type parameters or type arguments of a generic type, and use the method to do the same for a generic method. Once you know that a object represents a type parameter, there are many additional questions reflection can answer. You can determine the type parameter's source, its position, and its constraints. @@ -132,16 +132,16 @@ generic ref class D : B {}; The property gets a value that indicates the variance (covariance or contravariance) and the special constraints of a type parameter. #### Covariance and Contravariance - To determine whether a type parameter is covariant or contravariant, apply the mask to the value that is returned by the property. If the result is , the type parameter is invariant. See [Covariance and Contravariance](../../../docs/standard/generics/covariance-and-contravariance.md). + To determine whether a type parameter is covariant or contravariant, apply the mask to the value that is returned by the property. If the result is , the type parameter is invariant. See [Covariance and Contravariance](../../../docs/standard/generics/covariance-and-contravariance.md). #### Special Constraints - To determine the special constraints of a type parameter, apply the mask to the value that is returned by the property. If the result is , there are no special constraints. A type parameter can be constrained to be a reference type, to be a non-nullable value type, and to have a default constructor. + To determine the special constraints of a type parameter, apply the mask to the value that is returned by the property. If the result is , there are no special constraints. A type parameter can be constrained to be a reference type, to be a non-nullable value type, and to have a default constructor. [Back to top](#top) ## Invariants - For a table of the invariant conditions for common terms in reflection for generic types, see . For additional terms relating to generic methods, see . + For a table of the invariant conditions for common terms in reflection for generic types, see . For additional terms relating to generic methods, see . [Back to top](#top) diff --git a/docs/framework/reflection-and-codedom/reflection.md b/docs/framework/reflection-and-codedom/reflection.md index 1b70f245332b4..6bc554b9ddbc4 100644 --- a/docs/framework/reflection-and-codedom/reflection.md +++ b/docs/framework/reflection-and-codedom/reflection.md @@ -35,7 +35,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Reflection in the .NET Framework -The classes in the namespace, together with , enable you to obtain information about loaded [assemblies](../../../docs/framework/app-domains/assemblies-in-the-common-language-runtime.md) and the types defined within them, such as [classes](http://msdn.microsoft.com/en-us/ad7d3561-271e-4546-82fc-e00b059f27a9), [interfaces](http://msdn.microsoft.com/en-us/fd9d5975-5363-4bc9-b883-609f887895e5), and [value types](http://msdn.microsoft.com/en-us/c9c567f8-8ab1-4d88-834d-00f7d92418de). You can also use reflection to create type instances at run time, and to invoke and access them. For topics about specific aspects of reflection, see [Related Topics](#related_topics) at the end of this overview. +The classes in the namespace, together with , enable you to obtain information about loaded [assemblies](../../../docs/framework/app-domains/assemblies-in-the-common-language-runtime.md) and the types defined within them, such as [classes](http://msdn.microsoft.com/en-us/ad7d3561-271e-4546-82fc-e00b059f27a9), [interfaces](http://msdn.microsoft.com/en-us/fd9d5975-5363-4bc9-b883-609f887895e5), and [value types](http://msdn.microsoft.com/en-us/c9c567f8-8ab1-4d88-834d-00f7d92418de). You can also use reflection to create type instances at run time, and to invoke and access them. For topics about specific aspects of reflection, see [Related Topics](#related_topics) at the end of this overview. The [common language runtime](../../../docs/standard/clr.md) loader manages [application domains](../../../docs/framework/app-domains/application-domains.md), which constitute defined boundaries around objects that have the same application scope. This management includes loading each assembly into the appropriate application domain and controlling the memory layout of the type hierarchy within each assembly. @@ -88,7 +88,7 @@ The classes in the namespace, together with + diff --git a/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md b/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md index ed708624524e7..3f109b997a05f 100644 --- a/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md +++ b/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md @@ -46,9 +46,9 @@ Reflection provides the ability to obtain information about types and members, a For example, code that is run in a sandboxed application domain is limited to the access described in this list, unless the application domain grants additional permissions. - Starting with the [!INCLUDE[net_v20SP1_long](../../../includes/net-v20sp1-long-md.md)], attempting to access members that are normally inaccessible generates a demand for the grant set of the target object plus with the flag. Code that is running with full trust (for example, code in an application that is launched from the command line) can always satisfy these permissions. (This is subject to limitations in accessing security-critical members, as described later in this article.) + Starting with the [!INCLUDE[net_v20SP1_long](../../../includes/net-v20sp1-long-md.md)], attempting to access members that are normally inaccessible generates a demand for the grant set of the target object plus with the flag. Code that is running with full trust (for example, code in an application that is launched from the command line) can always satisfy these permissions. (This is subject to limitations in accessing security-critical members, as described later in this article.) - Optionally, a sandboxed application domain can grant with the flag, as described in the section [Accessing Members That Are Normally Inaccessible](#accessingNormallyInaccessible), later in this article. + Optionally, a sandboxed application domain can grant with the flag, as described in the section [Accessing Members That Are Normally Inaccessible](#accessingNormallyInaccessible), later in this article. ## Accessing Security-Critical Members @@ -81,21 +81,21 @@ Reflection provides the ability to obtain information about types and members, a ## Accessing Members That Are Normally Inaccessible To use reflection to invoke members that are inaccessible according to the accessibility rules of the common language runtime, your code must be granted one of two permissions: -- To allow code to invoke any nonpublic member:Your code must be granted with the flag. +- To allow code to invoke any nonpublic member:Your code must be granted with the flag. > [!NOTE] > By default, security policy denies this permission to code that originates from the Internet. This permission should never be granted to code that originates from the Internet. -- To allow code to invoke any nonpublic member, as long as the grant set of the assembly that contains the invoked member is the same as, or a subset of, the grant set of the assembly that contains the invoking code: Your code must be granted with the flag. +- To allow code to invoke any nonpublic member, as long as the grant set of the assembly that contains the invoked member is the same as, or a subset of, the grant set of the assembly that contains the invoking code: Your code must be granted with the flag. - For example, suppose you grant an application domain Internet permissions plus with the flag, and then run an Internet application with two assemblies, A and B. + For example, suppose you grant an application domain Internet permissions plus with the flag, and then run an Internet application with two assemblies, A and B. - Assembly A can use reflection to access private members of assembly B, because the grant set of assembly B does not include any permissions that A has not been granted. - Assembly A cannot use reflection to access private members of [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] assemblies such as mscorlib.dll, because mscorlib.dll is fully trusted and therefore has permissions that have not been granted to assembly A. A is thrown when code access security walks the stack at run time. ## Serialization - For serialization, with the flag provides the ability to get and set members of serializable types, regardless of accessibility. This permission enables code to discover and change the private state of an instance. (In addition to being granted the appropriate permissions, the type must be [marked](../../../docs/standard/attributes/applying-attributes.md) as serializable in metadata.) + For serialization, with the flag provides the ability to get and set members of serializable types, regardless of accessibility. This permission enables code to discover and change the private state of an instance. (In addition to being granted the appropriate permissions, the type must be [marked](../../../docs/standard/attributes/applying-attributes.md) as serializable in metadata.) ## Parameters of Type MethodInfo Avoid writing public members that take parameters, especially for trusted code. Such members might be more vulnerable to malicious code. For example, consider a public member in highly trusted code that takes a parameter. Assume that the public member indirectly calls the method on the supplied parameter. If the public member does not perform the necessary permission checks, the call to the method will always succeed, because the security system determines that the caller is highly trusted. Even if malicious code does not have the permission to directly invoke the method, it can still do so indirectly by calling the public member. @@ -104,9 +104,9 @@ Reflection provides the ability to obtain information about types and members, a - Beginning with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], transparent code cannot use reflection to access security-critical members. -- The flag is introduced in the [!INCLUDE[net_v20SP1_long](../../../includes/net-v20sp1-long-md.md)]. Earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] require the flag for code that uses reflection to access nonpublic members. This is a permission that should never be granted to partially trusted code. +- The flag is introduced in the [!INCLUDE[net_v20SP1_long](../../../includes/net-v20sp1-long-md.md)]. Earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] require the flag for code that uses reflection to access nonpublic members. This is a permission that should never be granted to partially trusted code. -- Beginning with the [!INCLUDE[dnprdnlong](../../../includes/dnprdnlong-md.md)], using reflection to obtain information about nonpublic types and members does not require any permissions. In earlier versions, with the flag is required. +- Beginning with the [!INCLUDE[dnprdnlong](../../../includes/dnprdnlong-md.md)], using reflection to obtain information about nonpublic types and members does not require any permissions. In earlier versions, with the flag is required. ## See Also diff --git a/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md b/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md index 2e9ce353887b9..c81ee04193bcd 100644 --- a/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md +++ b/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md @@ -40,7 +40,7 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] provides three ## Dynamic Assemblies - Dynamic assemblies are created by using overloads of the method. Most overloads of this method are deprecated in the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], because of the elimination of machine-wide security policy. (See [Security Changes](../../../docs/framework/security/security-changes.md).) The remaining overloads can be executed by any code, regardless of trust level. These overloads fall into two groups: those that specify a list of attributes to apply to the dynamic assembly when it is created, and those that do not. If you do not specify the transparency model for the assembly, by applying the attribute when you create it, the transparency model is inherited from the emitting assembly. + Dynamic assemblies are created by using overloads of the method. Most overloads of this method are deprecated in the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], because of the elimination of machine-wide security policy. (See [Security Changes](../../../docs/framework/security/security-changes.md).) The remaining overloads can be executed by any code, regardless of trust level. These overloads fall into two groups: those that specify a list of attributes to apply to the dynamic assembly when it is created, and those that do not. If you do not specify the transparency model for the assembly, by applying the attribute when you create it, the transparency model is inherited from the emitting assembly. > [!NOTE] > Attributes that you apply to the dynamic assembly after it is created, by using the method, do not take effect until the assembly has been saved to disk and loaded into memory again. @@ -48,7 +48,7 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] provides three Code in a dynamic assembly can access visible types and members in other assemblies. > [!NOTE] -> Dynamic assemblies do not use the and flags that allow dynamic methods to access nonpublic types and members. +> Dynamic assemblies do not use the and flags that allow dynamic methods to access nonpublic types and members. Transient dynamic assemblies are created in memory and never saved to disk, so they require no file access permissions. Saving a dynamic assembly to disk requires with the appropriate flags. @@ -70,26 +70,26 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] provides three Instead, when an anonymously hosted dynamic method is created, the call stack is captured. When the method is constructed, security demands are made against the captured call stack. > [!NOTE] -> Conceptually, demands are made during the construction of the method. That is, demands could be made as each MSIL instruction is emitted. In the current implementation, all demands are made when the method is called or when the just-in-time (JIT) compiler is invoked, if the method is invoked without calling . +> Conceptually, demands are made during the construction of the method. That is, demands could be made as each MSIL instruction is emitted. In the current implementation, all demands are made when the method is called or when the just-in-time (JIT) compiler is invoked, if the method is invoked without calling . - If the application domain permits it, anonymously hosted dynamic methods can skip JIT visibility checks, subject to the following restriction: The nonpublic types and members accessed by an anonymously hosted dynamic method must be in assemblies whose grant sets are equal to, or subsets of, the grant set of the emitting call stack. This restricted ability to skip JIT visibility checks is enabled if the application domain grants with the flag. + If the application domain permits it, anonymously hosted dynamic methods can skip JIT visibility checks, subject to the following restriction: The nonpublic types and members accessed by an anonymously hosted dynamic method must be in assemblies whose grant sets are equal to, or subsets of, the grant set of the emitting call stack. This restricted ability to skip JIT visibility checks is enabled if the application domain grants with the flag. - If your method uses only public types and members, no permissions are required during construction. -- If you specify that JIT visibility checks should be skipped, the demand that is made when the method is constructed includes with the flag and the grant set of the assembly that contains the nonpublic member that is being accessed. +- If you specify that JIT visibility checks should be skipped, the demand that is made when the method is constructed includes with the flag and the grant set of the assembly that contains the nonpublic member that is being accessed. - Because the grant set of the nonpublic member is taken into consideration, partially trusted code that has been granted cannot elevate its privileges by executing nonpublic members of trusted assemblies. + Because the grant set of the nonpublic member is taken into consideration, partially trusted code that has been granted cannot elevate its privileges by executing nonpublic members of trusted assemblies. As with any other emitted code, executing the dynamic method requires whatever permissions are demanded by the methods the dynamic method uses. - The system assembly that hosts anonymously-hosted dynamic methods uses the transparency model, which is the transparency model that was used in the .NET Framework before the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)]. + The system assembly that hosts anonymously-hosted dynamic methods uses the transparency model, which is the transparency model that was used in the .NET Framework before the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)]. For more information, see the class. ### Generating Anonymously Hosted Dynamic Methods from Partially Trusted Code Consider the conditions in which an assembly with Internet permissions can generate an anonymously hosted dynamic method and execute it: -- The dynamic method uses only public types and members. If its grant set includes , it can use nonpublic types and members of any assembly whose grant set is equal to, or a subset of, the grant set of the emitting assembly. +- The dynamic method uses only public types and members. If its grant set includes , it can use nonpublic types and members of any assembly whose grant set is equal to, or a subset of, the grant set of the emitting assembly. - The permissions that are required by all the types and members used by the dynamic method are included in the grant set of the partially trusted assembly. @@ -110,14 +110,14 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] provides three - If your method uses only public types and members, and you associate it with your own type or your own module, no permissions are required. -- If you specify that JIT visibility checks should be skipped, the constructor demands with the flag. +- If you specify that JIT visibility checks should be skipped, the constructor demands with the flag. -- If you associate the dynamic method with another type, even another type in your own assembly, the constructor demands with the flag and with the flag. +- If you associate the dynamic method with another type, even another type in your own assembly, the constructor demands with the flag and with the flag. -- If you associate the dynamic method with a type or module in another assembly, the constructor demands two things: with the flag, and the grant set of the assembly that contains the other module. That is, your call stack must include all the permissions in the grant set of the target module, plus . +- If you associate the dynamic method with a type or module in another assembly, the constructor demands two things: with the flag, and the grant set of the assembly that contains the other module. That is, your call stack must include all the permissions in the grant set of the target module, plus . > [!NOTE] - > For backward compatibility, if the demand for the target grant set plus fails, the constructor demands with the flag. + > For backward compatibility, if the demand for the target grant set plus fails, the constructor demands with the flag. Although the items in this list are described in terms of the grant set of the emitting assembly, remember that the demands are made against the full call stack, including the application domain boundary. @@ -130,9 +130,9 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] provides three Consider the conditions in which an assembly with Internet permissions can generate a dynamic method and execute it: -- Either the dynamic method is associated with the module or type that emits it, or its grant set includes and it is associated with a module in an assembly whose grant set is equal to, or a subset of, the grant set of the emitting assembly. +- Either the dynamic method is associated with the module or type that emits it, or its grant set includes and it is associated with a module in an assembly whose grant set is equal to, or a subset of, the grant set of the emitting assembly. -- The dynamic method uses only public types and members. If its grant set includes and it is associated with a module in an assembly whose grant set is equal to, or a subset of, the grant set of the emitting assembly, it can use types and members marked `internal` (`Friend` in Visual Basic, `assembly` in common language runtime metadata) in the associated module. +- The dynamic method uses only public types and members. If its grant set includes and it is associated with a module in an assembly whose grant set is equal to, or a subset of, the grant set of the emitting assembly, it can use types and members marked `internal` (`Friend` in Visual Basic, `assembly` in common language runtime metadata) in the associated module. - The permissions demanded by all the types and members used by the dynamic method are included in the grant set of the partially trusted assembly. @@ -145,17 +145,17 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] provides three ## Version Information Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], machine-wide security policy is eliminated and security transparency becomes the default enforcement mechanism. See [Security Changes](../../../docs/framework/security/security-changes.md). - Starting with the [!INCLUDE[net_v20SP1_long](../../../includes/net-v20sp1-long-md.md)], with the flag is no longer required when emitting dynamic assemblies and dynamic methods. This flag is required in all earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)]. + Starting with the [!INCLUDE[net_v20SP1_long](../../../includes/net-v20sp1-long-md.md)], with the flag is no longer required when emitting dynamic assemblies and dynamic methods. This flag is required in all earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)]. > [!NOTE] -> with the flag is included by default in the `FullTrust` and `LocalIntranet` named permission sets, but not in the `Internet` permission set. Therefore, in earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)], a library can be used with Internet permissions only if it executes an for . Such libraries require careful security review because coding errors could result in security holes. The [!INCLUDE[net_v20SP1_short](../../../includes/net-v20sp1-short-md.md)] allows code to be emitted in partial trust scenarios without issuing any security demands, because generating code is not inherently a privileged operation. That is, the generated code has no more permissions than the assembly that emits it. This allows libraries that emit code to be security transparent and removes the need to assert , which simplifies the task of writing a secure library. +> with the flag is included by default in the `FullTrust` and `LocalIntranet` named permission sets, but not in the `Internet` permission set. Therefore, in earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)], a library can be used with Internet permissions only if it executes an for . Such libraries require careful security review because coding errors could result in security holes. The [!INCLUDE[net_v20SP1_short](../../../includes/net-v20sp1-short-md.md)] allows code to be emitted in partial trust scenarios without issuing any security demands, because generating code is not inherently a privileged operation. That is, the generated code has no more permissions than the assembly that emits it. This allows libraries that emit code to be security transparent and removes the need to assert , which simplifies the task of writing a secure library. - In addition, the [!INCLUDE[net_v20SP1_short](../../../includes/net-v20sp1-short-md.md)] introduces the flag for accessing nonpublic types and members from partially trusted dynamic methods. Earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] require the flag for dynamic methods that access nonpublic types and members; this is a permission that should never be granted to partially trusted code. + In addition, the [!INCLUDE[net_v20SP1_short](../../../includes/net-v20sp1-short-md.md)] introduces the flag for accessing nonpublic types and members from partially trusted dynamic methods. Earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] require the flag for dynamic methods that access nonpublic types and members; this is a permission that should never be granted to partially trusted code. Finally, the [!INCLUDE[net_v20SP1_short](../../../includes/net-v20sp1-short-md.md)] introduces anonymously hosted methods. ### Obtaining Information on Types and Members - Starting with the [!INCLUDE[dnprdnlong](../../../includes/dnprdnlong-md.md)], no permissions are required to obtain information about nonpublic types and members. Reflection is used to obtain information needed to emit dynamic methods. For example, objects are used to emit method calls. Earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] require with the flag. For more information, see [Security Considerations for Reflection](../../../docs/framework/reflection-and-codedom/security-considerations-for-reflection.md). + Starting with the [!INCLUDE[dnprdnlong](../../../includes/dnprdnlong-md.md)], no permissions are required to obtain information about nonpublic types and members. Reflection is used to obtain information needed to emit dynamic methods. For example, objects are used to emit method calls. Earlier versions of the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] require with the flag. For more information, see [Security Considerations for Reflection](../../../docs/framework/reflection-and-codedom/security-considerations-for-reflection.md). ## See Also [Security Considerations for Reflection](../../../docs/framework/reflection-and-codedom/security-considerations-for-reflection.md) diff --git a/docs/framework/reflection-and-codedom/specifying-fully-qualified-type-names.md b/docs/framework/reflection-and-codedom/specifying-fully-qualified-type-names.md index 623f502c0aaae..41099de753278 100644 --- a/docs/framework/reflection-and-codedom/specifying-fully-qualified-type-names.md +++ b/docs/framework/reflection-and-codedom/specifying-fully-qualified-type-names.md @@ -29,7 +29,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Specifying Fully Qualified Type Names -You must specify type names to have valid input to various reflection operations. A fully qualified type name consists of an assembly name specification, a namespace specification, and a type name. Type name specifications are used by methods such as , , , and . +You must specify type names to have valid input to various reflection operations. A fully qualified type name consists of an assembly name specification, a namespace specification, and a type name. Type name specifications are used by methods such as , , , and . ## Backus-Naur Form Grammar for Type Names The Backus-Naur form (BNF) defines the syntax of formal languages. The following table lists BNF lexical rules that describe how to recognize a valid input. Terminals (those elements that are not further reducible) are shown in all uppercase letters. Nonterminals (those elements that are further reducible) are shown in mixed-case or singly quoted strings, but the single quote (') is not a part of the syntax itself. The pipe character (|) denotes rules that have subrules. @@ -70,7 +70,7 @@ You must specify type names to have valid input to various reflection operations Note that in all TypeSpec components except AssemblyNameSpec, spaces are relevant. In the AssemblyNameSpec, spaces before the ',' separator are relevant, but spaces after the ',' separator are ignored. - Reflection classes, such as , return the mangled name so that the returned name can be used in a call to , as in `MyType.GetType(myType.FullName)`. + Reflection classes, such as , return the mangled name so that the returned name can be used in a call to , as in `MyType.GetType(myType.FullName)`. For example, the fully qualified name for a type might be `Ozzy.OutBack.Kangaroo+Wallaby,MyAssembly`. @@ -130,7 +130,7 @@ com.microsoft.crypto, Culture=en, PublicKeyToken=a5d015c7d5a0b012, SimpleTypeSpec & represents a managed pointer or reference. For example, to get a reference to type MyType, use `Type.GetType("MyType &")`. Note that unlike pointers, references are limited to one level. ## Specifying Arrays - In the BNF Grammar, ReflectionEmitDimension only applies to incomplete type definitions retrieved using . Incomplete type definitions are objects constructed using but on which has not been called. ReflectionDimension can be used to retrieve any type definition that has been completed, that is, a type that has been loaded. + In the BNF Grammar, ReflectionEmitDimension only applies to incomplete type definitions retrieved using . Incomplete type definitions are objects constructed using but on which has not been called. ReflectionDimension can be used to retrieve any type definition that has been completed, that is, a type that has been loaded. Arrays are accessed in reflection by specifying the rank of the array: @@ -150,7 +150,7 @@ com.microsoft.crypto, Culture=en, PublicKeyToken=a5d015c7d5a0b012, - - - + + + [Viewing Type Information](../../../docs/framework/reflection-and-codedom/viewing-type-information.md) diff --git a/docs/framework/reflection-and-codedom/using-the-codedom.md b/docs/framework/reflection-and-codedom/using-the-codedom.md index 12467bae57bd5..717ee0b91bd8b 100644 --- a/docs/framework/reflection-and-codedom/using-the-codedom.md +++ b/docs/framework/reflection-and-codedom/using-the-codedom.md @@ -45,7 +45,7 @@ The CodeDOM provides types that represent many common types of source code eleme The structure of a CodeDOM graph is like a tree of containers. The top-most, or root, container of each compilable CodeDOM graph is a . Every element of your source code model must be linked into the graph through a property of a in the graph. ### Building a Source Code Model for a Sample Hello World Program - The following walkthrough provides an example of how to build a CodeDOM object graph that represents the code for a simple Hello World application. For the complete source code for this code example, see the topic. + The following walkthrough provides an example of how to build a CodeDOM object graph that represents the code for a simple Hello World application. For the complete source code for this code example, see the topic. #### Creating a compile unit The CodeDOM defines an object called a , which can reference a CodeDOM object graph that models the source code to compile. A **CodeCompileUnit** has properties for storing references to attributes, namespaces, and assemblies. diff --git a/docs/framework/reflection-and-codedom/viewing-type-information.md b/docs/framework/reflection-and-codedom/viewing-type-information.md index 41e2d34d12a04..90eb5c6826335 100644 --- a/docs/framework/reflection-and-codedom/viewing-type-information.md +++ b/docs/framework/reflection-and-codedom/viewing-type-information.md @@ -24,9 +24,9 @@ ms.author: "ronpet" manager: "wpickett" --- # Viewing Type Information -The class is central to reflection. The common language runtime creates the **Type** for a loaded type when reflection requests it. You can use a **Type** object's methods, fields, properties, and nested classes to find out everything about that type. +The class is central to reflection. The common language runtime creates the **Type** for a loaded type when reflection requests it. You can use a **Type** object's methods, fields, properties, and nested classes to find out everything about that type. - Use or to obtain **Type** objects from assemblies that have not been loaded, passing in the name of the type or types you want. Use to get the **Type** objects from an assembly that is already loaded. Use and to obtain module **Type** objects. + Use or to obtain **Type** objects from assemblies that have not been loaded, passing in the name of the type or types you want. Use to get the **Type** objects from an assembly that is already loaded. Use and to obtain module **Type** objects. > [!NOTE] > If you want to examine and manipulate generic types and methods, please see the additional information provided in [Reflection and Generic Types](../../../docs/framework/reflection-and-codedom/reflection-and-generic-types.md) and [How to: Examine and Instantiate Generic Types with Reflection](../../../docs/framework/reflection-and-codedom/how-to-examine-and-instantiate-generic-types-with-reflection.md). @@ -43,11 +43,11 @@ The class is central to reflection. [!code-csharp[Conceptual.Types.ViewInfo#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.types.viewinfo/cs/source5.cs#7)] [!code-vb[Conceptual.Types.ViewInfo#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.types.viewinfo/vb/source5.vb#7)] - Once you obtain a **Type**, there are many ways you can discover information about the members of that type. For example, you can find out about all the type's members by calling the method, which obtains an array of objects describing each of the members of the current type. + Once you obtain a **Type**, there are many ways you can discover information about the members of that type. For example, you can find out about all the type's members by calling the method, which obtains an array of objects describing each of the members of the current type. - You can also use methods on the **Type** class to retrieve information about one or more constructors, methods, events, fields, or properties that you specify by name. For example, encapsulates a specific constructor of the current class. + You can also use methods on the **Type** class to retrieve information about one or more constructors, methods, events, fields, or properties that you specify by name. For example, encapsulates a specific constructor of the current class. - If you have a **Type**, you can use the property to obtain an object that encapsulates the module containing that type. Use the property to locate an object that encapsulates the assembly containing the module. You can obtain the assembly that encapsulates the type directly by using the property. + If you have a **Type**, you can use the property to obtain an object that encapsulates the module containing that type. Use the property to locate an object that encapsulates the assembly containing the module. You can obtain the assembly that encapsulates the type directly by using the property. ## System.Type and ConstructorInfo The following example shows how to list the constructors for a class, in this case, the class. @@ -79,13 +79,13 @@ The class is central to reflection. ## See Also - - - - - - - + + + + + + + diff --git a/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md b/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md index dacd7d5ab1f94..1d4b5f6810ca8 100644 --- a/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md +++ b/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md @@ -28,7 +28,7 @@ manager: "wpickett" Reflection emit uses the same API set in full or partial trust, but some features require special permissions in partially trusted code. In addition, reflection emit has a feature, anonymously hosted dynamic methods, that is designed to be used with partial trust and by security-transparent assemblies. > [!NOTE] -> Before [!INCLUDE[net_v35_long](../../../includes/net-v35-long-md.md)], emitting code required with the flag. This permission is included by default in the `FullTrust` and `Intranet` named permission sets, but not in the `Internet` permission set. Therefore, a library could be used from partial trust only if it had the attribute and also executed an method for . Such libraries require careful security review because coding errors could result in security holes. The [!INCLUDE[net_v35_short](../../../includes/net-v35-short-md.md)] allows code to be emitted in partial trust scenarios without issuing any security demands, because generating code is not inherently a privileged operation. That is, the generated code has no more permissions than the assembly that emits it. This enables libraries that emit code to be security-transparent and removes the need to assert , so that writing a secure library does not require such a thorough security review. +> Before [!INCLUDE[net_v35_long](../../../includes/net-v35-long-md.md)], emitting code required with the flag. This permission is included by default in the `FullTrust` and `Intranet` named permission sets, but not in the `Internet` permission set. Therefore, a library could be used from partial trust only if it had the attribute and also executed an method for . Such libraries require careful security review because coding errors could result in security holes. The [!INCLUDE[net_v35_short](../../../includes/net-v35-short-md.md)] allows code to be emitted in partial trust scenarios without issuing any security demands, because generating code is not inherently a privileged operation. That is, the generated code has no more permissions than the assembly that emits it. This enables libraries that emit code to be security-transparent and removes the need to assert , so that writing a secure library does not require such a thorough security review. This walkthrough illustrates the following tasks: @@ -51,10 +51,10 @@ Reflection emit uses the same API set in full or partial trust, but some feature - The first procedure shows how to create a sandboxed application domain in which code is granted Internet permissions. -- The second procedure shows how to add with the flag to a partially trusted application domain, to enable access to private data in assemblies of equal or lesser trust. +- The second procedure shows how to add with the flag to a partially trusted application domain, to enable access to private data in assemblies of equal or lesser trust. ### Creating Sandboxed Application Domains - To create an application domain in which your assemblies run with partial trust, you must specify the set of permissions to be granted to the assemblies by using the method overload to create the application domain. The easiest way to specify the grant set is to retrieve a named permission set from security policy. + To create an application domain in which your assemblies run with partial trust, you must specify the set of permissions to be granted to the assemblies by using the method overload to create the application domain. The easiest way to specify the grant set is to retrieve a named permission set from security policy. The following procedure creates a sandboxed application domain that runs your code with partial trust, to test scenarios in which emitted code can access only public members of public types. A subsequent procedure shows how to add , to test scenarios in which emitted code can access nonpublic types and members in assemblies that are granted equal or lesser permissions. @@ -78,10 +78,10 @@ Reflection emit uses the same API set in full or partial trust, but some feature [!code-csharp[HowToEmitCodeInPartialTrust#5](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEmitCodeInPartialTrust/cs/source.cs#5)] [!code-vb[HowToEmitCodeInPartialTrust#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEmitCodeInPartialTrust/vb/source.vb#5)] - The last parameter of the method overload enables you to specify a set of assemblies that are to be granted full trust, instead of the grant set of the application domain. You do not have to specify the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] assemblies that your application uses, because those assemblies are in the global assembly cache. Assemblies in the global assembly cache are always fully trusted. You can use this parameter to specify strong-named assemblies that are not in the global assembly cache. + The last parameter of the method overload enables you to specify a set of assemblies that are to be granted full trust, instead of the grant set of the application domain. You do not have to specify the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] assemblies that your application uses, because those assemblies are in the global assembly cache. Assemblies in the global assembly cache are always fully trusted. You can use this parameter to specify strong-named assemblies that are not in the global assembly cache. ### Adding RestrictedMemberAccess to Sandboxed Domains - Host applications can allow anonymously hosted dynamic methods to have access to private data in assemblies that have trust levels equal to or less than the trust level of the assembly that emits the code. To enable this restricted ability to skip just-in-time (JIT) visibility checks, the host application adds a object with the (RMA) flag to the grant set. + Host applications can allow anonymously hosted dynamic methods to have access to private data in assemblies that have trust levels equal to or less than the trust level of the assembly that emits the code. To enable this restricted ability to skip just-in-time (JIT) visibility checks, the host application adds a object with the (RMA) flag to the grant set. For example, a host might grant Internet applications Internet permissions plus RMA, so that an Internet application can emit code that accesses private data in its own assemblies. Because the access is limited to assemblies of equal or lesser trust, an Internet application cannot access members of fully trusted assemblies such as [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] assemblies. @@ -90,7 +90,7 @@ Reflection emit uses the same API set in full or partial trust, but some feature ##### To create an application domain with partial trust plus RMA -1. Create a new object with the (RMA) flag, and use the method to add the permission to the grant set. +1. Create a new object with the (RMA) flag, and use the method to add the permission to the grant set. [!code-csharp[HowToEmitCodeInPartialTrust#7](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEmitCodeInPartialTrust/cs/source.cs#7)] [!code-vb[HowToEmitCodeInPartialTrust#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/HowToEmitCodeInPartialTrust/vb/source.vb#7)] @@ -163,7 +163,7 @@ Reflection emit uses the same API set in full or partial trust, but some feature If an anonymously hosted dynamic method uses only public types and methods, it does not require restricted member access and does not have to skip JIT visibility checks. - No special permissions are required to emit a dynamic method, but the emitted code requires the permissions that are demanded by the types and methods it uses. For example, if the emitted code calls a method that accesses a file, it requires . If the trust level does not include that permission, a security exception is thrown when the emitted code is executed. The code shown here emits a dynamic method that uses only the method. Therefore, the code can be executed from partially trusted locations. + No special permissions are required to emit a dynamic method, but the emitted code requires the permissions that are demanded by the types and methods it uses. For example, if the emitted code calls a method that accesses a file, it requires . If the trust level does not include that permission, a security exception is thrown when the emitted code is executed. The code shown here emits a dynamic method that uses only the method. Therefore, the code can be executed from partially trusted locations. - Alternatively, create an anonymously hosted dynamic method with restricted ability to skip JIT visibility checks, by using the constructor and specifying `true` for the `restrictedSkipVisibility` parameter. @@ -172,7 +172,7 @@ Reflection emit uses the same API set in full or partial trust, but some feature The restriction is that the anonymously hosted dynamic method can access private data only in assemblies with trust levels equal to or less than the trust level of the emitting assembly. For example, if the dynamic method is executing with Internet trust, it can access private data in other assemblies that are also executing with Internet trust, but it cannot access private data of [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] assemblies. [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] assemblies are installed in the global assembly cache and are always fully trusted. - Anonymously hosted dynamic methods can use this restricted ability to skip JIT visibility checks only if the host application grants with the flag. The demand for this permission is made when the method is invoked. + Anonymously hosted dynamic methods can use this restricted ability to skip JIT visibility checks only if the host application grants with the flag. The demand for this permission is made when the method is invoked. > [!NOTE] > Call stack information for the emitting assembly is included when the dynamic method is constructed. Therefore, the demand is made against the permissions of the emitting assembly instead of the assembly that invokes the method. This prevents the emitted code from being executed with elevated permissions. @@ -190,19 +190,19 @@ Reflection emit uses the same API set in full or partial trust, but some feature The example defines a `Worker` class that can be marshaled across application domain boundaries. The class has two `AccessPrivateMethod` method overloads that emit and execute dynamic methods. The first overload emits a dynamic method that calls the private `PrivateMethod` method of the `Worker` class, and it can emit the dynamic method with or without JIT visibility checks. The second overload emits a dynamic method that accesses an `internal` property (`Friend` property in Visual Basic) of the class. - The example uses a helper method to create a grant set limited to `Internet` permissions, and then creates an application domain, using the method overload to specify that all code that executes in the domain uses this grant set. The example creates an instance of the `Worker` class in the application domain, and executes the `AccessPrivateMethod` method two times. + The example uses a helper method to create a grant set limited to `Internet` permissions, and then creates an application domain, using the method overload to specify that all code that executes in the domain uses this grant set. The example creates an instance of the `Worker` class in the application domain, and executes the `AccessPrivateMethod` method two times. - The first time the `AccessPrivateMethod` method is executed, JIT visibility checks are enforced. The dynamic method fails when it is invoked, because JIT visibility checks prevent it from accessing the private method. - The second time the `AccessPrivateMethod` method is executed, JIT visibility checks are skipped. The dynamic method fails when it is compiled, because the `Internet` grant set does not grant sufficient permissions to skip visibility checks. - The example adds with to the grant set. The example then creates a second domain, specifying that all code that executes in the domain is granted the permissions in the new grant set. The example creates an instance of the `Worker` class in the new application domain, and executes both overloads of the `AccessPrivateMethod` method. + The example adds with to the grant set. The example then creates a second domain, specifying that all code that executes in the domain is granted the permissions in the new grant set. The example creates an instance of the `Worker` class in the new application domain, and executes both overloads of the `AccessPrivateMethod` method. - The first overload of the `AccessPrivateMethod` method is executed, and JIT visibility checks are skipped. The dynamic method compiles and executes successfully, because the assembly that emits the code is the same as the assembly that contains the private method. Therefore, the trust levels are equal. If the application that contains the `Worker` class had several assemblies, the same process would succeed for any one of those assemblies, because they would all be at the same trust level. - The second overload of the `AccessPrivateMethod` method is executed, and again JIT visibility checks are skipped. This time the dynamic method fails when it is compiled, because it tries to access the `internal` `FirstChar` property of the class. The assembly that contains the class is fully trusted. Therefore, it is at a higher level of trust than the assembly that emits the code. - This comparison shows how enables partially trusted code to skip visibility checks for other partially trusted code without compromising the security of trusted code. + This comparison shows how enables partially trusted code to skip visibility checks for other partially trusted code without compromising the security of trusted code. ### Code [!code-csharp[HowToEmitCodeInPartialTrust#1](../../../samples/snippets/csharp/VS_Snippets_CLR/HowToEmitCodeInPartialTrust/cs/source.cs#1)] diff --git a/docs/framework/resources/creating-resource-files-for-desktop-apps.md b/docs/framework/resources/creating-resource-files-for-desktop-apps.md index 4ec1cb5532dbf..c0dd5db989e8e 100644 --- a/docs/framework/resources/creating-resource-files-for-desktop-apps.md +++ b/docs/framework/resources/creating-resource-files-for-desktop-apps.md @@ -59,7 +59,7 @@ name2=value2 The resource file format of .txt and .restext files is identical. The .restext file extension merely serves to make text files immediately identifiable as text-based resource files. - String resources appear as *name/value* pairs, where *name* is a string that identifies the resource, and *value* is the resource string that is returned when you pass *name* to a resource retrieval method such as . *name* and *value* must be separated by an equal sign (=). For example: + String resources appear as *name/value* pairs, where *name* is a string that identifies the resource, and *value* is the resource string that is returned when you pass *name* to a resource retrieval method such as . *name* and *value* must be separated by an equal sign (=). For example: ``` FileMenuName=File @@ -71,7 +71,7 @@ HelpMenuName=Help > [!CAUTION] > Do not use resource files to store passwords, security-sensitive information, or private data. - Empty strings (that is, a resource whose value is ) are permitted in text files. For example: + Empty strings (that is, a resource whose value is ) are permitted in text files. For example: ``` EmptyString= @@ -169,13 +169,13 @@ greeting=Hello, {0}! ## Resources in .resources Files - You can use the class to programmatically create a binary resource (.resources) file directly from code. You can also use [Resource File Generator (Resgen.exe)](../../../docs/framework/tools/resgen-exe-resource-file-generator.md) to create a .resources file from a text file or a .resx file. The .resources file can contain binary data (byte arrays) and object data in addition to string data. Programmatically creating a .resources file requires the following steps: + You can use the class to programmatically create a binary resource (.resources) file directly from code. You can also use [Resource File Generator (Resgen.exe)](../../../docs/framework/tools/resgen-exe-resource-file-generator.md) to create a .resources file from a text file or a .resx file. The .resources file can contain binary data (byte arrays) and object data in addition to string data. Programmatically creating a .resources file requires the following steps: 1. Create a object with a unique file name. You can do this by specifying either a file name or a file stream to a class constructor. -2. Call one of the overloads of the method for each named resource to add to the file. The resource can be a string, an object, or a collection of binary data (a byte array). +2. Call one of the overloads of the method for each named resource to add to the file. The resource can be a string, an object, or a collection of binary data (a byte array). -3. Call the method to write the resources to the file and to close the object. +3. Call the method to write the resources to the file and to close the object. > [!NOTE] > Do not use resource files to store passwords, security-sensitive information, or private data. diff --git a/docs/framework/resources/creating-satellite-assemblies-for-desktop-apps.md b/docs/framework/resources/creating-satellite-assemblies-for-desktop-apps.md index c9b3fa433eee1..09d84b684f7bb 100644 --- a/docs/framework/resources/creating-satellite-assemblies-for-desktop-apps.md +++ b/docs/framework/resources/creating-satellite-assemblies-for-desktop-apps.md @@ -37,7 +37,7 @@ manager: "wpickett" Resource files play a central role in localized applications. They enable an application to display strings, images, and other data in the user's own language and culture, and to provide alternate data if resources for the user's own language or culture are unavailable. The .NET Framework uses a hub-and-spoke model to locate and retrieve localized resources. The hub is the main assembly that contains the non-localizable executable code and the resources for a single culture, which is called the neutral or default culture. The default culture is the fallback culture for the application; it is used when no localized resources are available. You use the attribute to designate the culture of the application's default culture. Each spoke connects to a satellite assembly that contains the resources for a single localized culture but does not contain any code. Because the satellite assemblies are not part of the main assembly, you can easily update or replace resources that correspond to a specific culture without replacing the main assembly for the application. > [!NOTE] -> The resources of an application's default culture can also be stored in a satellite assembly. To do this, you assign the attribute a value of . +> The resources of an application's default culture can also be stored in a satellite assembly. To do this, you assign the attribute a value of . ## Satellite Assembly Name and Location The hub-and-spoke model requires that you place resources in specific locations so that they can be easily located and used. If you do not compile and name resources as expected, or if you do not place them in the correct locations, the common language runtime will not be able to locate them and will use the resources of the default culture instead. The .NET Framework Resource Manager, represented by a object, is used to automatically access localized resources. The Resource Manager requires the following: @@ -90,7 +90,7 @@ al /target:lib /embed:strings.de.resources /culture:de /out:Example.resources.dl 1. Create a resource file named Greeting.resx or Greeting.txt to contain the resource for the default culture. Store a single string named `HelloString` whose value is "Hello world!" in this file. -2. To indicate that English (en) is the application's default culture, add the following attribute to the application's AssemblyInfo file or to the main source code file that will be compiled into the application's main assembly. +2. To indicate that English (en) is the application's default culture, add the following attribute to the application's AssemblyInfo file or to the main source code file that will be compiled into the application's main assembly. [!code-csharp[Conceptual.Resources.Locating#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.resources.locating/cs/assemblyinfo.cs#2)] [!code-vb[Conceptual.Resources.Locating#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.locating/vb/assemblyinfo.vb#2)] @@ -219,7 +219,7 @@ gacutil /i:StringLibrary.resources.dll 3. Create a resource file named Strings.resx to contain the resource for the default culture. Store a single string named `Greeting` whose value is "How do you do?" in that file. -4. To indicate that "en" is the application's default culture, add the following attribute to the application's AssemblyInfo file or to the main source code file that will be compiled into the application's main assembly: +4. To indicate that "en" is the application's default culture, add the following attribute to the application's AssemblyInfo file or to the main source code file that will be compiled into the application's main assembly: [!code-csharp[Conceptual.Resources.Satellites#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.resources.satellites/cs/stringlibrary.cs#2)] [!code-vb[Conceptual.Resources.Satellites#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.satellites/vb/stringlibrary.vb#2)] diff --git a/docs/framework/resources/index.md b/docs/framework/resources/index.md index 213311b1dd8e3..599b2e03b717f 100644 --- a/docs/framework/resources/index.md +++ b/docs/framework/resources/index.md @@ -45,17 +45,17 @@ Nearly every production-quality app has to use resources. A resource is any none For more information, see the [Packaging and Deploying Resources](../../../docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md) article. ## Retrieving Resources - At run time, an app loads the appropriate localized resources on a per-thread basis, based on the culture specified by the property. This property value is derived as follows: + At run time, an app loads the appropriate localized resources on a per-thread basis, based on the culture specified by the property. This property value is derived as follows: -- By directly assigning a object that represents the localized culture to the property. +- By directly assigning a object that represents the localized culture to the property. -- If a culture is not explicitly assigned, by retrieving the default thread UI culture from the property. +- If a culture is not explicitly assigned, by retrieving the default thread UI culture from the property. - If a default thread UI culture is not explicitly assigned, by retrieving the culture for the current user on the local computer by calling the Windows `GetUserDefaultUILanguage` function. - For more information about how the current UI culture is set, see the and reference pages. + For more information about how the current UI culture is set, see the and reference pages. - You can then retrieve resources for the current UI culture or for a specific culture by using the class. Although the class is most commonly used for retrieving resources in desktop apps, the namespace contains additional types that you can use to retrieve resources. These include: + You can then retrieve resources for the current UI culture or for a specific culture by using the class. Although the class is most commonly used for retrieving resources in desktop apps, the namespace contains additional types that you can use to retrieve resources. These include: - The class, which enables you to enumerate resources embedded in an assembly or stored in a standalone binary .resources file. It is useful when you don't know the precise names of the resources that are available at run time. @@ -67,7 +67,7 @@ Nearly every production-quality app has to use resources. A resource is any none ## See Also - + [Application Essentials](../../../docs/standard/application-essentials.md) [Creating Resource Files](../../../docs/framework/resources/creating-resource-files-for-desktop-apps.md) [Packaging and Deploying Resources](../../../docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md) diff --git a/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md b/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md index 25b4b40be1e83..faab7323b41f3 100644 --- a/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md +++ b/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md @@ -78,7 +78,7 @@ Applications rely on the .NET Framework Resource Manager, represented by the event to indicate that it is unable to find the satellite assembly. If you choose to handle the event, your event handler can return a reference to the satellite assembly whose resources will be used for the lookup. Otherwise, the event handler returns `null` and the search continues. +4. The runtime raises the event to indicate that it is unable to find the satellite assembly. If you choose to handle the event, your event handler can return a reference to the satellite assembly whose resources will be used for the lookup. Otherwise, the event handler returns `null` and the search continues. 5. The runtime next searches the global assembly cache again, this time for the parent assembly of the requested culture. If the parent assembly exists in the global assembly cache, the runtime searches the assembly for the requested resource. @@ -88,9 +88,9 @@ Applications rely on the .NET Framework Resource Manager, represented by the event to indicate that it is unable to find an appropriate fallback resource. If you choose to handle the event, your event handler can return a reference to the satellite assembly whose resources will be used for the lookup. Otherwise, the event handler returns `null` and the search continues. +8. The runtime raises the event to indicate that it is unable to find an appropriate fallback resource. If you choose to handle the event, your event handler can return a reference to the satellite assembly whose resources will be used for the lookup. Otherwise, the event handler returns `null` and the search continues. -9. The runtime next searches parent assemblies, as in the previous three steps, through many potential levels. Each culture has only one parent, which is defined by the property, but a parent might have its own parent. The search for parent cultures stops when a culture's property returns ; for resource fallback, the invariant culture is not considered a parent culture or a culture that can have resources. +9. The runtime next searches parent assemblies, as in the previous three steps, through many potential levels. Each culture has only one parent, which is defined by the property, but a parent might have its own parent. The search for parent cultures stops when a culture's property returns ; for resource fallback, the invariant culture is not considered a parent culture or a culture that can have resources. 10. If the culture that was originally specified and all parents have been searched and the resource is still not found, the resource for the default (fallback) culture is used. Typically, the resources for the default culture are included in the main application assembly. However, you can specify a value of for the property of the attribute to indicate that the ultimate fallback location for resources is a satellite assembly, rather than the main assembly. @@ -109,7 +109,7 @@ Applications rely on the .NET Framework Resource Manager, represented by the event. +- Application code does not handle the event. You optimize the probe for satellite assemblies by including the [\](../../../docs/framework/configure-apps/file-schema/runtime/relativebindforresources-element.md) element and setting its `enabled` attribute to `true` in the application configuration file, as shown in the following example. @@ -127,10 +127,10 @@ Applications rely on the .NET Framework Resource Manager, represented by the event. +- If the probe for a particular resource assembly fails, the runtime does not raise the event. ### Ultimate Fallback to Satellite Assembly - You can optionally remove resources from the main assembly and specify that the runtime should load the ultimate fallback resources from a satellite assembly that corresponds to a specific culture. To control the fallback process, you use the constructor and supply a value for the parameter that specifies whether Resource Manager should extract the fallback resources from the main assembly or from a satellite assembly. + You can optionally remove resources from the main assembly and specify that the runtime should load the ultimate fallback resources from a satellite assembly that corresponds to a specific culture. To control the fallback process, you use the constructor and supply a value for the parameter that specifies whether Resource Manager should extract the fallback resources from the main assembly or from a satellite assembly. The following example uses the attribute to store an application's fallback resources in a satellite assembly for the French (fr) language. The example has two text-based resource files that define a single string resource named `Greeting`. The first, resources.fr.txt, contains a French language resource. diff --git a/docs/framework/resources/retrieving-resources-in-desktop-apps.md b/docs/framework/resources/retrieving-resources-in-desktop-apps.md index b532599dbcbd2..171401e01d5ca 100644 --- a/docs/framework/resources/retrieving-resources-in-desktop-apps.md +++ b/docs/framework/resources/retrieving-resources-in-desktop-apps.md @@ -33,7 +33,7 @@ When you work with localized resources in .NET Framework desktop apps, you shoul ## Retrieving Resources from Assemblies - The class provides access to resources at run time. You use the method to retrieve string resources and the or method to retrieve non-string resources. Each method has two overloads: + The class provides access to resources at run time. You use the method to retrieve string resources and the or method to retrieve non-string resources. Each method has two overloads: - An overload whose single parameter is a string that contains the name of the resource. The method attempts to retrieve that resource for the current thread culture. For more information, see the , , and methods. @@ -60,7 +60,7 @@ TimeHeader=L'heure actuelle est TimeHeader=Текущее время — ``` - The source code for this example, which is in a file named GetString.cs for the C# version of the code and GetString.vb for the Visual Basic version, defines a string array that contains the name of four cultures: the three cultures for which resources are available and the Spanish (Spain) culture. A loop that executes five times randomly selects one of these cultures and assigns it to the and properties. It then calls the method to retrieve the localized string, which it displays along with the time of day. + The source code for this example, which is in a file named GetString.cs for the C# version of the code and GetString.vb for the Visual Basic version, defines a string array that contains the name of four cultures: the three cultures for which resources are available and the Spanish (Spain) culture. A loop that executes five times randomly selects one of these cultures and assigns it to the and properties. It then calls the method to retrieve the localized string, which it displays along with the time of day. [!code-csharp[Conceptual.Resources.Retrieving#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.resources.retrieving/cs/getstring.cs#3)] [!code-vb[Conceptual.Resources.Retrieving#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/getstring.vb#3)] @@ -106,7 +106,7 @@ resgen AppResources.resx csc GetStream.cs /resource:AppResources.resources ``` - The following example uses the method to deserialize a custom object. The example includes a source code file named UIElements.cs (UIElements.vb for Visual Basic) that defines the following structure named `PersonTable`. This structure is intended to be used by a general table display routine that displays the localized names of table columns. Note that the `PersonTable` structure is marked with the attribute. + The following example uses the method to deserialize a custom object. The example includes a source code file named UIElements.cs (UIElements.vb for Visual Basic) that defines the following structure named `PersonTable`. This structure is intended to be used by a general table display routine that displays the localized names of table columns. Note that the `PersonTable` structure is marked with the attribute. [!code-csharp[Conceptual.Resources.Retrieving#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.resources.retrieving/cs/example.cs#6)] [!code-vb[Conceptual.Resources.Retrieving#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example.vb#6)] @@ -147,7 +147,7 @@ GetObject.exe ## Retrieving Resources from .resources Files - If you choose not to deploy resources in satellite assemblies, you can still use a object to access resources from .resources files directly. To do this, you must deploy the .resources files correctly. Then you use the method to instantiate a object and specify the directory that contains the standalone .resources files. + If you choose not to deploy resources in satellite assemblies, you can still use a object to access resources from .resources files directly. To do this, you must deploy the .resources files correctly. Then you use the method to instantiate a object and specify the directory that contains the standalone .resources files. ### Deploying .resources Files When you embed .resources files in an application assembly and satellite assemblies, each satellite assembly has the same file name, but is placed in a subdirectory that reflects the satellite assembly's culture. In contrast, when you access resources from .resources files directly, you can place all the .resources files in a single directory, usually a subdirectory of the application directory. The name of the app's default .resources file consists of a root name only, with no indication of its culture (for example, strings.resources). The resources for each localized culture are stored in a file whose name consists of the root name followed by the culture (for example, strings.ja.resources or strings.de-DE.resources). The following illustration shows where resource files should be located in the directory structure. @@ -161,7 +161,7 @@ Directory structure and naming conventions for .resources files > [!NOTE] > Do not deploy ASP.NET apps using standalone .resources files. This can cause locking issues and breaks XCOPY deployment. We recommend that you deploy ASP.NET resources in satellite assemblies. For more information, see [ASP.NET Web Page Resources Overview](http://msdn.microsoft.com/library/0936b3b2-9e6e-4abe-9c06-364efef9dbbd). - After you instantiate the object, you use the , , and methods as discussed earlier to retrieve the resources. However, the retrieval of resources directly from .resources files differs from the retrieval of embedded resources from assemblies. When you retrieve resources from .resources files, the , , and methods always retrieve the default culture's resources regardless of the current culture. To retrieve the resources of the either the app's current culture or a specific culture, you must call the , , or method and specify the culture whose resources are to be retrieved. To retrieve the resources of the current culture, specify the value of the property as the `culture` argument. If the resource manager cannot retrieve the resources of `culture`, it uses the standard resource fallback rules to retrieve the appropriate resources. + After you instantiate the object, you use the , , and methods as discussed earlier to retrieve the resources. However, the retrieval of resources directly from .resources files differs from the retrieval of embedded resources from assemblies. When you retrieve resources from .resources files, the , , and methods always retrieve the default culture's resources regardless of the current culture. To retrieve the resources of the either the app's current culture or a specific culture, you must call the , , or method and specify the culture whose resources are to be retrieved. To retrieve the resources of the current culture, specify the value of the property as the `culture` argument. If the resource manager cannot retrieve the resources of `culture`, it uses the standard resource fallback rules to retrieve the appropriate resources. ### An Example The following example illustrates how the resource manager retrieves resources directly from .resources files. The example consists of three text-based resource files for the English (United States), French (France), and Russian (Russia) cultures. English (United States) is the example's default culture. Its resources are stored in the following file named Strings.txt: @@ -185,7 +185,7 @@ Greeting=Здравствуйте Prompt=Как вас зовут? ``` - The following is the source code for the example. The example instantiates objects for the English (United States), English (Canada), French (France), and Russian (Russia) cultures, and makes each the current culture. The method then supplies the value of the property as the `culture` argument to retrieve the appropriate culture-specific resources. + The following is the source code for the example. The example instantiates objects for the English (United States), English (Canada), French (France), and Russian (Russia) cultures, and makes each the current culture. The method then supplies the value of the property as the `culture` argument to retrieve the appropriate culture-specific resources. [!code-csharp[Conceptual.Resources.Retrieving#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.resources.retrieving/cs/example3.cs#9)] [!code-vb[Conceptual.Resources.Retrieving#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/example3.vb#9)] diff --git a/docs/framework/resources/working-with-resx-files-programmatically.md b/docs/framework/resources/working-with-resx-files-programmatically.md index 73b3d2df42f74..8ed546700fd17 100644 --- a/docs/framework/resources/working-with-resx-files-programmatically.md +++ b/docs/framework/resources/working-with-resx-files-programmatically.md @@ -27,15 +27,15 @@ Because XML resource (.resx) files must consist of well-defined XML, including a > There are also ways to work with .resx files other than programmatically. When you add a resource file to a Visual Studio project, Visual Studio provides an interface for creating and maintaining a .resx file, and automatically converts the .resx file to a .resources file at compile time. You can also use a text editor to manipulate a .resx file directly. However, to avoid corrupting the file, be careful not to modify any binary information that is stored in the file. ## Creating a .resx File - You can use the class to create a .resx file programmatically, by following these steps: + You can use the class to create a .resx file programmatically, by following these steps: -1. Instantiate a object by calling the method and supplying the name of the .resx file. The file name must include the .resx extension. If you instantiate the object in a `using` block, you do not explicitly have to call the method in step 3. +1. Instantiate a object by calling the method and supplying the name of the .resx file. The file name must include the .resx extension. If you instantiate the object in a `using` block, you do not explicitly have to call the method in step 3. -2. Call the method for each resource you want to add to the file. Use the overloads of this method to add string, object, and binary (byte array) data. If the resource is an object, it must be serializable. +2. Call the method for each resource you want to add to the file. Use the overloads of this method to add string, object, and binary (byte array) data. If the resource is an object, it must be serializable. -3. Call the method to generate the resource file and to release all resources. If the object was created within a `using` block, resources are written to the .resx file and the resources used by the object are released at the end of the `using` block. +3. Call the method to generate the resource file and to release all resources. If the object was created within a `using` block, resources are written to the .resx file and the resources used by the object are released at the end of the `using` block. - The resulting .resx file has the appropriate header and a `data` tag for each resource added by the method. + The resulting .resx file has the appropriate header and a `data` tag for each resource added by the method. > [!WARNING] > Do not use resource files to store passwords, security-sensitive information, or private data. @@ -51,15 +51,15 @@ Because XML resource (.resx) files must consist of well-defined XML, including a You cannot embed a .resx file in a runtime executable or compile it into a satellite assembly. You must convert your .resx file into a binary resource (.resources) file by using the [Resource File Generator (Resgen.exe)](../../../docs/framework/tools/resgen-exe-resource-file-generator.md). The resulting .resources file can then be embedded in an application assembly or a satellite assembly. For more information, see [Creating Resource Files](../../../docs/framework/resources/creating-resource-files-for-desktop-apps.md). ## Enumerating Resources - In some cases, you may want to retrieve all resources, instead of a specific resource, from a .resx file. To do this, you can use the class, which provides an enumerator for all resources in the .resx file. The class implements , which returns a object that represents a particular resource for each iteration of the loop. Its property returns the resource's key, and its property returns the resource's value. + In some cases, you may want to retrieve all resources, instead of a specific resource, from a .resx file. To do this, you can use the class, which provides an enumerator for all resources in the .resx file. The class implements , which returns a object that represents a particular resource for each iteration of the loop. Its property returns the resource's key, and its property returns the resource's value. - The following example creates a object for the CarResources.resx file created in the previous example and iterates through the resource file. It adds the two `Automobile` objects that are defined in the resource file to a object, and it adds five of the six strings to a object. The values in the object are converted to a parameter array, which is used to display column headings to the console. The `Automobile` property values are also displayed to the console. + The following example creates a object for the CarResources.resx file created in the previous example and iterates through the resource file. It adds the two `Automobile` objects that are defined in the resource file to a object, and it adds five of the six strings to a object. The values in the object are converted to a parameter array, which is used to display column headings to the console. The `Automobile` property values are also displayed to the console. [!code-csharp[Conceptual.Resources.ResX#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.resources.resx/cs/enumerate1.cs#2)] [!code-vb[Conceptual.Resources.ResX#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.resx/vb/enumerate1.vb#2)] ## Retrieving a Specific Resource - In addition to enumerating the items in a .resx file, you can retrieve a specific resource by name by using the class. The method retrieves the value of a named string resource. The method retrieves the value of a named object or binary data. The method returns an object that must then be cast (in C#) or converted (in Visual Basic) to an object of the appropriate type. + In addition to enumerating the items in a .resx file, you can retrieve a specific resource by name by using the class. The method retrieves the value of a named string resource. The method retrieves the value of a named object or binary data. The method returns an object that must then be cast (in C#) or converted (in Visual Basic) to an object of the appropriate type. The following example retrieves a form's caption string and icon by their resource names. It also retrieves the application-defined `Automobile` objects used in the previous example and displays them in a control. diff --git a/docs/framework/security/guidelines-for-migrating-an-application-built-using-wif-3-5-to-wif-4-5.md b/docs/framework/security/guidelines-for-migrating-an-application-built-using-wif-3-5-to-wif-4-5.md index 442ad00395fb0..758e8d52ec38e 100644 --- a/docs/framework/security/guidelines-for-migrating-an-application-built-using-wif-3-5-to-wif-4-5.md +++ b/docs/framework/security/guidelines-for-migrating-an-application-built-using-wif-3-5-to-wif-4-5.md @@ -31,32 +31,32 @@ manager: "mbaldwin" ### Assembly and Namespace Changes In WIF 3.5, all of the WIF classes were contained in the `Microsoft.IdentityModel` assembly (microsoft.identitymicrosoft.identitymodel.dll). In WIF 4.5, the WIF classes have been split across the following assemblies: `mscorlib` (mscorlib.dll), `System.IdentityModel` (System.IdentityModel.dll), `System.IdentityModel.Services` (System.IdentityModel.Services.dll), and `System.ServiceModel` (System.ServiceModel.dll). - The WIF 3.5 classes were all contained in one of the `Microsoft.IdentityModel` namespaces; for example, `Microsoft.IdentityModel`, `Microsoft.IdentityModel.Tokens`, `Microsoft.IdentityModel.Web`, and so on. In WIF 4.5, the WIF classes are now spread across the [System.IdentityModel](http://go.microsoft.com/fwlink/?LinkId=272004) namespaces, the namespace, and the namespace. In addition to this reorganization, some WIF 3.5 classes have been dropped in WIF 4.5. + The WIF 3.5 classes were all contained in one of the `Microsoft.IdentityModel` namespaces; for example, `Microsoft.IdentityModel`, `Microsoft.IdentityModel.Tokens`, `Microsoft.IdentityModel.Web`, and so on. In WIF 4.5, the WIF classes are now spread across the [System.IdentityModel](http://go.microsoft.com/fwlink/?LinkId=272004) namespaces, the namespace, and the namespace. In addition to this reorganization, some WIF 3.5 classes have been dropped in WIF 4.5. The following table shows some of the more important WIF 4.5 namespaces and the kind of classes they contain. For more detailed information about how namespaces map between WIF 3.5 and WIF 4.5 and about namespaces and classes that have been dropped in WIF 4.5, see [Namespace Mapping between WIF 3.5 and WIF 4.5](../../../docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md). |WIF 4.5 Namespace|Description| |-----------------------|-----------------| -||Contains classes that represent cookie transforms, security token services, and specialized XML dictionary readers. Contains classes from the following WIF 3.5 namespaces: `Microsoft.IdentityModel`, `Microsoft.IdentityModel.SecurityTokenService`, and `Microsoft.IdentityModel.Threading`.| -||Contains classes that represent claims, claims-based identities, claims based principals, and other claims based identity model artifacts. Contains classes from the `Microsoft.IdentityModel.Claims` namespace.| -||Contains classes that represent security tokens, security token handlers, and other security token artifacts. Contains classes from the following WIF 3.5 namespaces: `Microsoft.IdentityModel.Tokens`, `Microsoft.IdentityModel.Tokens.Saml11`, and `Microsoft.IdentityModel.Tokens.Saml2`.| -||Contains classes that are used in passive (WS-Federation) scenarios. Contains classes from the `Microsoft.IdentityModel.Web` namespace.| -||Classes that represent WCF contracts, channels, service hosts and other artifacts that are used in active (WS-Trust) scenarios are now in this namespace. In WIF 3.5 , these classes were in the `Microsoft.IdentityModel.Protocols.WSTrust` namespace.| +||Contains classes that represent cookie transforms, security token services, and specialized XML dictionary readers. Contains classes from the following WIF 3.5 namespaces: `Microsoft.IdentityModel`, `Microsoft.IdentityModel.SecurityTokenService`, and `Microsoft.IdentityModel.Threading`.| +||Contains classes that represent claims, claims-based identities, claims based principals, and other claims based identity model artifacts. Contains classes from the `Microsoft.IdentityModel.Claims` namespace.| +||Contains classes that represent security tokens, security token handlers, and other security token artifacts. Contains classes from the following WIF 3.5 namespaces: `Microsoft.IdentityModel.Tokens`, `Microsoft.IdentityModel.Tokens.Saml11`, and `Microsoft.IdentityModel.Tokens.Saml2`.| +||Contains classes that are used in passive (WS-Federation) scenarios. Contains classes from the `Microsoft.IdentityModel.Web` namespace.| +||Classes that represent WCF contracts, channels, service hosts and other artifacts that are used in active (WS-Trust) scenarios are now in this namespace. In WIF 3.5 , these classes were in the `Microsoft.IdentityModel.Protocols.WSTrust` namespace.| > [!IMPORTANT] -> The following `System.IdentityModel` namespaces contain classes that implement the WCF claims-based identity model: , , and . The WCF claims-based identity model is superseded by WIF. You should not use classes in these three namespaces when building solutions based on WIF. +> The following `System.IdentityModel` namespaces contain classes that implement the WCF claims-based identity model: , , and . The WCF claims-based identity model is superseded by WIF. You should not use classes in these three namespaces when building solutions based on WIF. ### Changes Due to .NET Integration - WIF is now integrated into the .NET Framework. Most .NET identity and principal classes now derive from and . The results in the following changes in WIF 4.5: + WIF is now integrated into the .NET Framework. Most .NET identity and principal classes now derive from and . The results in the following changes in WIF 4.5: -- WIF classes that represent claims, identities, and principals now exist in the namespace. +- WIF classes that represent claims, identities, and principals now exist in the namespace. > [!IMPORTANT] - > The namespace contains classes that represent artifacts in the WCF claims-based identity model. Many of these classes have names that are the same as WIF classes; for example, `Claims`. Do not use these classes when building solutions based on WIF. + > The namespace contains classes that represent artifacts in the WCF claims-based identity model. Many of these classes have names that are the same as WIF classes; for example, `Claims`. Do not use these classes when building solutions based on WIF. -- .NET identity and principal classes now derive directly from and , which represent claims-based identities and principals. For this reason, the WIF 3.5 interfaces `IClaimsIdentity` and `IClaimsPrincipal` are no longer needed and are not available in WIF 4.5. +- .NET identity and principal classes now derive directly from and , which represent claims-based identities and principals. For this reason, the WIF 3.5 interfaces `IClaimsIdentity` and `IClaimsPrincipal` are no longer needed and are not available in WIF 4.5. -- Because.NET identity and principal classes such as and now derive from and , they have claims functionality built-in. For this reason, claims-specific identity and principal classes such as `WindowsClaimsIdentity` and `WindowsClaimsPrincipal` that were present in WIF 3.5 are no longer needed and do not exist in WIF 4.5. +- Because.NET identity and principal classes such as and now derive from and , they have claims functionality built-in. For this reason, claims-specific identity and principal classes such as `WindowsClaimsIdentity` and `WindowsClaimsPrincipal` that were present in WIF 3.5 are no longer needed and do not exist in WIF 4.5. ### Other Changes to WIF Functionality In addition to the namespace changes and the changes due to integration with .NET, the following general changes to WIF functionality occur in WIF 4.5. @@ -112,9 +112,9 @@ manager: "mbaldwin" ### Passive (WS-Federation) Scenarios: -- Classes that support passive scenarios have been moved to the namespace. In WIF 3.5 these classes were in the `Microsoft.IdentityModel.Web` namespace. +- Classes that support passive scenarios have been moved to the namespace. In WIF 3.5 these classes were in the `Microsoft.IdentityModel.Web` namespace. -- The classes in the `Microsoft.IdentityModel.Web.Configuration` namespace have been moved to . These classes represent objects specific to configuration in passive scenarios. +- The classes in the `Microsoft.IdentityModel.Web.Configuration` namespace have been moved to . These classes represent objects specific to configuration in passive scenarios. - The `FederatedPasssiveSignInControl` is no longer supported; all classes in the `Microsoft.IdentityModel.Web.Controls` namespace have been removed from WIF 4.5. @@ -122,7 +122,7 @@ manager: "mbaldwin" ### Active (WCF/WS-Trust) Scenarios: -- The `Microsoft.IdentityModel.Protocols.WSTrust` namespace has been split mainly into two namespaces in WIF 4.5. Classes that represent artifacts that are specific to the WS-Trust protocol are now in . This includes classes like . Classes that represent service contracts, channels, service hosts and other artifacts that are involved in using WS-Trust in WCF applications have been moved to ; for example, the interface. +- The `Microsoft.IdentityModel.Protocols.WSTrust` namespace has been split mainly into two namespaces in WIF 4.5. Classes that represent artifacts that are specific to the WS-Trust protocol are now in . This includes classes like . Classes that represent service contracts, channels, service hosts and other artifacts that are involved in using WS-Trust in WCF applications have been moved to ; for example, the interface. - Configuring a WCF application to use WIF has been greatly simplified. Previously the `Microsoft.IdentityModel.Configuration.ConfigureServiceHostBehaviorExtensionElement` had to be added as a behavior extension and this functionality was then used to wedge WIF into the service behavior by specifying a `` element. WIF 4.5 has been more tightly integrated with WCF. Now you enable WIF on a WCF service by specifying the `useIdentityConfiguration` attribute on the ``/``/``/`` element as in the following XML: diff --git a/docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md b/docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md index 9b365f9c8fbfe..eda56e2103198 100644 --- a/docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md +++ b/docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md @@ -22,30 +22,30 @@ Beginning with .NET 4.5, Windows Identity Foundation (WIF) has been fully integr The WIF classes, which were collected under the `Microsoft.IdentityModel` namespaces in WIF 3.5, are now distributed among the following namespaces: `System.Security.Claims`, `System.ServiceModel.Security`, and the `System.IdentityModel` namespaces in WIF 4.5. In addition some WIF 3.5 namespaces were consolidated or dropped entirely in WIF 4.5. > [!IMPORTANT] -> The following `System.IdentityModel` namespaces contain classes that implement the WCF claims-based identity model: , , and . The WCF claims-based identity model is superseded by WIF. You should not use classes in these three namespaces when building solutions based on WIF. +> The following `System.IdentityModel` namespaces contain classes that implement the WCF claims-based identity model: , , and . The WCF claims-based identity model is superseded by WIF. You should not use classes in these three namespaces when building solutions based on WIF. The following table provides information about where WIF 3.5 classes can be found in WIF 4.5. |**WIF 3.5 Namespace**|**WIF 4.5 Namespace**|**Comments**| |-|-|-| -|`Microsoft.IdentityModel`||- Most of the classes that represent constants are not implemented.
- The classes that are used to build security token services have been moved from `Microsoft.IdentityModel.SecurityTokenService` to .
- The classes in `Microsoft.IdentityModel.Threading` have been moved to .
- The `ExceptionMapper` and `MruSecurityTokenCache` classes are not implemented.| -|`Microsoft.IdentityModel.Claims`||- The `IClaimsPrincipal` and `IClaimsIdentity` interfaces are not implemented in WIF 4.5. Instead and are now the base classes from which most .NET principal and identity classes derive. This means there is no need for specialized claims principal and identity classes like `Microsoft.IdentityModel.Claims.WindowsClaimsPrincipal` and `Microsoft.IdentityModel.Claims.WindowsClaimsIdentity` in WIF 4.5, use and instead. The same is true for other for the other specialized claims principal and identity classes that existed in WIF 3.5.
- The `Microsoft.IdentityModel.Claims.ClaimsCollection` class is not implemented in WIF 4.5. Instead, collections of claims are exposed as enumerable collections of type .
- and provide methods that now fully support LINQ.| -|`Microsoft.IdentityModel.Configuration`||Some elements and classes have undergone name changes and some have been dropped in WIF 4.5; for example `Microsoft.IdentityModel.Configuraiton.ServiceConfiguration` is now .| -|`Microsoft.IdentityModel.Protocols`||-| -|`Microsoft.IdentityModel.Protocols.WSFederation`||-| -|`Microsoft.IdentityModel.Protocols.WSFederation.Metadata`||-| +|`Microsoft.IdentityModel`||- Most of the classes that represent constants are not implemented.
- The classes that are used to build security token services have been moved from `Microsoft.IdentityModel.SecurityTokenService` to .
- The classes in `Microsoft.IdentityModel.Threading` have been moved to .
- The `ExceptionMapper` and `MruSecurityTokenCache` classes are not implemented.| +|`Microsoft.IdentityModel.Claims`||- The `IClaimsPrincipal` and `IClaimsIdentity` interfaces are not implemented in WIF 4.5. Instead and are now the base classes from which most .NET principal and identity classes derive. This means there is no need for specialized claims principal and identity classes like `Microsoft.IdentityModel.Claims.WindowsClaimsPrincipal` and `Microsoft.IdentityModel.Claims.WindowsClaimsIdentity` in WIF 4.5, use and instead. The same is true for other for the other specialized claims principal and identity classes that existed in WIF 3.5.
- The `Microsoft.IdentityModel.Claims.ClaimsCollection` class is not implemented in WIF 4.5. Instead, collections of claims are exposed as enumerable collections of type .
- and provide methods that now fully support LINQ.| +|`Microsoft.IdentityModel.Configuration`||Some elements and classes have undergone name changes and some have been dropped in WIF 4.5; for example `Microsoft.IdentityModel.Configuraiton.ServiceConfiguration` is now .| +|`Microsoft.IdentityModel.Protocols`||-| +|`Microsoft.IdentityModel.Protocols.WSFederation`||-| +|`Microsoft.IdentityModel.Protocols.WSFederation.Metadata`||-| |`Microsoft.IdentityModel.Protocols.WSIdentity`|Not Implemented in WIF 4.5|In WIF 3.5 contained classes to support CardSpace, not implemented in WIF 4.5.| -|`Microsoft.IdentityModel.Protocols.WSTrust`|Split between the and namespaces.|Classes that represents WS-Trust artifacts are in the namespace; for example, the class. Classes that represent WCF service contracts, service hosts, and channels that enable a WCF service to communicate using the WS-Trust protocol are in the namespace; for example, the class.| +|`Microsoft.IdentityModel.Protocols.WSTrust`|Split between the and namespaces.|Classes that represents WS-Trust artifacts are in the namespace; for example, the class. Classes that represent WCF service contracts, service hosts, and channels that enable a WCF service to communicate using the WS-Trust protocol are in the namespace; for example, the class.| |`Microsoft.IdentityModel.Protocols.WSTrust.Bindings`|Not Implemented in WIF 4.5|-| |`Microsoft.IdentityModel.Protocols.XmlEncryption`|Not Implemented in WIF 4.5|Contained classes that represent XML Encryption constants in WIF 3.5. These constants are not implemented in WIF 4.5.| -|`Microsoft.IdentityModel.Protocols.XmlSignature`||The `EnvelopingSignature` class and classes that represent constants are not implemented.| -|`Microsoft.IdentityModel.SecurityTokenService`|Split between the , , and namespaces.|-| -|`Microsoft.IdentityModel.Threading`||-| -|`Microsoft.IdentityModel.Tokens`||-| -|`Microsoft.IdentityModel.Tokens.Saml11`||-| -|`Microsoft.IdentityModel.Tokens.Saml2`||-| -|`Microsoft.IdentityModel.Web`||-| -|`Microsoft.IdentityModel.Web.Configuration`||Classes that provide configuration for passive (WS-Federation) scenarios have largely been moved to ; however, some of these classes are in .| +|`Microsoft.IdentityModel.Protocols.XmlSignature`||The `EnvelopingSignature` class and classes that represent constants are not implemented.| +|`Microsoft.IdentityModel.SecurityTokenService`|Split between the , , and namespaces.|-| +|`Microsoft.IdentityModel.Threading`||-| +|`Microsoft.IdentityModel.Tokens`||-| +|`Microsoft.IdentityModel.Tokens.Saml11`||-| +|`Microsoft.IdentityModel.Tokens.Saml2`||-| +|`Microsoft.IdentityModel.Web`||-| +|`Microsoft.IdentityModel.Web.Configuration`||Classes that provide configuration for passive (WS-Federation) scenarios have largely been moved to ; however, some of these classes are in .| |`Microsoft.IdentityModel.Web.Controls`|Not Implemented in WIF 4.5|The classes in `Microsoft.IdentityModel.Web.Controls` implemented the Federated Passive Sign-In Control, which does not exist in WIF 4.5.| |`Microsoft.IdentityModel.WindowsTokenService`|Not Implemented in WIF 4.5|-| diff --git a/docs/framework/security/whats-new-in-wif.md b/docs/framework/security/whats-new-in-wif.md index f9c83052170ae..7e9ff9ec181a5 100644 --- a/docs/framework/security/whats-new-in-wif.md +++ b/docs/framework/security/whats-new-in-wif.md @@ -21,10 +21,10 @@ The first version of Windows Identity Foundation (WIF) shipped as a standalone d Below you can find some highlights of the main changes. ## WIF Is Now Part of the .NET Framework - WIF classes are now spread across several assemblies, the main ones being `mscorlib`, `System.IdentityModel`, `System.IdentityModel.Services`, and `System.ServiceModel`. Likewise, the WIF classes are spread across several namespaces: , several [System.IdentityModel](http://go.microsoft.com/fwlink/?LinkId=272004) namespaces, and . The namespace contains the new and classes (see below). All principals in .NET now derive from . For more detailed information about the WIF namespaces and the kinds of classes that they contain, see [WIF API Reference](../../../docs/framework/security/wif-api-reference.md). For information about how namespaces map between WIF 3.5 and WIF 4.5, see [Namespace Mapping between WIF 3.5 and WIF 4.5](../../../docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md). + WIF classes are now spread across several assemblies, the main ones being `mscorlib`, `System.IdentityModel`, `System.IdentityModel.Services`, and `System.ServiceModel`. Likewise, the WIF classes are spread across several namespaces: , several [System.IdentityModel](http://go.microsoft.com/fwlink/?LinkId=272004) namespaces, and . The namespace contains the new and classes (see below). All principals in .NET now derive from . For more detailed information about the WIF namespaces and the kinds of classes that they contain, see [WIF API Reference](../../../docs/framework/security/wif-api-reference.md). For information about how namespaces map between WIF 3.5 and WIF 4.5, see [Namespace Mapping between WIF 3.5 and WIF 4.5](../../../docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md). ## New Claims Model and Principal Object - Claims are at the very core of the .NET Framework 4.5. The base claim classes (, , , , and ) all live directly in `mscorlib` in the namespace. It is no longer necessary to use interfaces in order to plug claims into the .NET identity system: , , and now inherit from ; and , , and now inherit from . In short, every principal class will now serve claims. The WIF 3.5 integration classes and interfaces (`WindowsClaimsIdentity`, `WindowsClaimsPrincipal`, `IClaimsPrincipal`, `IClaimsIdentity`) have thus been removed. In addition, the class now exposes methods which make it easier to query the identity’s claims collection. + Claims are at the very core of the .NET Framework 4.5. The base claim classes (, , , , and ) all live directly in `mscorlib` in the namespace. It is no longer necessary to use interfaces in order to plug claims into the .NET identity system: , , and now inherit from ; and , , and now inherit from . In short, every principal class will now serve claims. The WIF 3.5 integration classes and interfaces (`WindowsClaimsIdentity`, `WindowsClaimsPrincipal`, `IClaimsPrincipal`, `IClaimsIdentity`) have thus been removed. In addition, the class now exposes methods which make it easier to query the identity’s claims collection. ## Changes to the WIF 4.5 Visual Studio Experience @@ -36,7 +36,7 @@ The first version of Windows Identity Foundation (WIF) shipped as a standalone d ## Changes to the WIF 4.5 API -- In general, claims related classes are in the namespace; WCF related classes –- service contracts, channels, channel factories, and service hosts that are used for WS-Trust scenarios -- are in ; and all other WIF classes are spread across various [System.IdentityModel](http://go.microsoft.com/fwlink/?LinkId=272004) namespaces – these include, for example, classes that represent WS-* and SAML artifacts, token handlers and related classes, and classes used in WS-Federation scenarios. For more information, see [Namespace Mapping between WIF 3.5 and WIF 4.5](../../../docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md) and [WIF API Reference](../../../docs/framework/security/wif-api-reference.md). +- In general, claims related classes are in the namespace; WCF related classes –- service contracts, channels, channel factories, and service hosts that are used for WS-Trust scenarios -- are in ; and all other WIF classes are spread across various [System.IdentityModel](http://go.microsoft.com/fwlink/?LinkId=272004) namespaces – these include, for example, classes that represent WS-* and SAML artifacts, token handlers and related classes, and classes used in WS-Federation scenarios. For more information, see [Namespace Mapping between WIF 3.5 and WIF 4.5](../../../docs/framework/security/namespace-mapping-between-wif-3-5-and-wif-4-5.md) and [WIF API Reference](../../../docs/framework/security/wif-api-reference.md). - Machine key has been enabled for use in session cookies for web farm scenarios. For more information, see [WIF and Web Farms](../../../docs/framework/security/wif-and-web-farms.md). @@ -48,7 +48,7 @@ The first version of Windows Identity Foundation (WIF) shipped as a standalone d ## WCF changes as a result of WIF integration: -- The WCF claims-based identity model is superseded by WIF. This means that classes in the , , and namespaces should be dropped in favor of using WIF classes. +- The WCF claims-based identity model is superseded by WIF. This means that classes in the , , and namespaces should be dropped in favor of using WIF classes. - WIF is now enabled on a WCF service by specifying the `useIdentityConfiguration` attribute on the ``/``/``/`` element as in the following XML: diff --git a/docs/framework/security/wif-and-web-farms.md b/docs/framework/security/wif-and-web-farms.md index da3bb9b7fb1bd..5c4a311dc91b5 100644 --- a/docs/framework/security/wif-and-web-farms.md +++ b/docs/framework/security/wif-and-web-farms.md @@ -45,7 +45,7 @@ When you use Windows Identity Foundation (WIF) to secure the resources of a rely ``` -- Derive from and implement distributed caching, that is, a cache that is accessible from all computers in the farm on which the RP might run. Configure the RP to use your distributed cache by specifying the [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/sessionsecuritytokencache.md) element in the configuration file. You can override the method in your derived class to implement child elements of the `` element if they are required. +- Derive from and implement distributed caching, that is, a cache that is accessible from all computers in the farm on which the RP might run. Configure the RP to use your distributed cache by specifying the [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/sessionsecuritytokencache.md) element in the configuration file. You can override the method in your derived class to implement child elements of the `` element if they are required. ```xml diff --git a/docs/framework/security/wif-api-reference.md b/docs/framework/security/wif-api-reference.md index 44b2c6da11af1..94f3748addb0b 100644 --- a/docs/framework/security/wif-api-reference.md +++ b/docs/framework/security/wif-api-reference.md @@ -19,36 +19,36 @@ manager: "mbaldwin" Windows Identity Foundation (WIF) classes are split across the following assemblies: `mscorlib` (mscorlib.dll), `System.IdentityModel` (System.IdentityModel.dll), `System.IdentityModel.Services` (System.IdentityModel.Services.dll), and `System.ServiceModel` (System.ServiceModel.dll). This topic provides links to the WIF namespaces and brief explanations of the classes that each namespace contains. > [!IMPORTANT] -> The following `System.IdentityModel` namespaces contain classes that implement the WCF claims-based identity model: , , and . Starting with .NET Framework 4.5, the WCF claims-based identity model is superseded by WIF. You should not use classes in these three namespaces when building solutions based on WIF. +> The following `System.IdentityModel` namespaces contain classes that implement the WCF claims-based identity model: , , and . Starting with .NET Framework 4.5, the WCF claims-based identity model is superseded by WIF. You should not use classes in these three namespaces when building solutions based on WIF. - + Contains classes that represent cookie transforms, security token services, and specialized XML dictionary readers. - + Contains classes that provide configuration for applications and services built using the Windows Identity Foundation (WIF). The classes in this namespace represent settings under the [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element. - + Contains classes that represent elements in a Federation Metadata document. - + Contains classes that represent WS-Trust artifacts. - + Contains classes that are used in passive (WS-Federation) scenarios. Also contains some classes that represent settings under the [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/system-identitymodel-services.md) element. Settings under this element configure WS-Federation for applications. The `System.IdentityModel.Services.Configuration` namespace contains most of the classes that are used to configure WS-Federation. - + Contains classes that provide configuration for WIF applications that use the WS-Federation protocol. The classes in this namespace represent settings under the [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/system-identitymodel-services.md) element. The `System.IdentityModel.Services` namespace also contains some classes that are used to configure WS-Federation. - + Contains specialized security token handlers for Web farm scenarios. - + Contains classes that represent security tokens, security token handlers, and other security token artifacts. - + Contains classes that represent claims, claims-based identities, claims-based principals, and other claims-based identity model artifacts. - + Contains classes that represent WCF contracts, channels, service hosts and other artifacts that are used in active (WS-Trust) scenarios. This namespace also contains classes that are specific to Windows Communication Foundation (WCF) and that are not used by WIF. ## See Also diff --git a/docs/framework/security/wif-session-management.md b/docs/framework/security/wif-session-management.md index a02ab834b1b4d..804c19a1b0b2d 100644 --- a/docs/framework/security/wif-session-management.md +++ b/docs/framework/security/wif-session-management.md @@ -16,13 +16,13 @@ ms.author: "bruceper" manager: "mbaldwin" --- # WIF Session Management -When a client first tries to access a protected resource that is hosted by a relying party, the client must first authenticate itself to a security token service (STS) that is trusted by the relying party. The STS then issues a security token to the client. The client presents this token to the relying party, which then grants the client access to the protected resource. However, you don’t want the client to have to re-authenticate to the STS for each request, especially because it might not even be on the same computer or in the same domain as the relying party. Instead, Windows Identity Foundation (WIF) has the client and relying party establish a session in which the client uses a session security token to authenticate itself to the relying party for all requests after the first request. The relying party can use this session security token, which is stored inside a cookie, to reconstruct the client’s . +When a client first tries to access a protected resource that is hosted by a relying party, the client must first authenticate itself to a security token service (STS) that is trusted by the relying party. The STS then issues a security token to the client. The client presents this token to the relying party, which then grants the client access to the protected resource. However, you don’t want the client to have to re-authenticate to the STS for each request, especially because it might not even be on the same computer or in the same domain as the relying party. Instead, Windows Identity Foundation (WIF) has the client and relying party establish a session in which the client uses a session security token to authenticate itself to the relying party for all requests after the first request. The relying party can use this session security token, which is stored inside a cookie, to reconstruct the client’s . The STS defines what authentication the client must provide. However, the client might have multiple credentials with which it can authenticate itself to the STS. For example, it might have a token from Windows Live, a user name and password, a certificate, and a smartkey. In that case, the STS grants the client several identities, with each identity corresponding to one of the credentials that the client presents. The relying party can use one or more of these identities when it decides what level of access to grant the client. - The is used to reconstruct the client’s , which contains all of the client’s identities in . Each in the collection contains the bootstrap tokens that are associated with that identity. + The is used to reconstruct the client’s , which contains all of the client’s identities in . Each in the collection contains the bootstrap tokens that are associated with that identity. - If a new session token is issued with the session ID of the original session token, does not update the session token in the token cache. You should always instantiate a session token with a unique session ID. + If a new session token is issued with the session ID of the original session token, does not update the session token in the token cache. You should always instantiate a session token with a unique session ID. > [!NOTE] > Session.SecurityTokenHandler.ReadToken throws a exception if it receives invalid input; for example, if the cookie that contains the session token is corrupted. We recommend that you catch this exception and provide application-specific behavior. @@ -32,6 +32,6 @@ When a client first tries to access a protected resource that is hosted by a rel To operate in reference mode, Microsoft recommends providing a handler for the event in the **global.asax.cs** file and setting the **IsReferenceMode** property on the token passed in the property. These updates will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. ## Extensibility - You can extend the session management mechanism. One reason for this would be to improve the performance. For example, you could create a custom cookie handler that transforms or optimizes the session security token between its in-memory state and what goes into the cookie. To do so, you can configure the property of the to use a custom cookie handler that derives from . is the default cookie handler because the cookies exceed the allowable size for Hypertext Transfer Protocol (HTTP); if you use a custom cookie handler instead, you must implement chunking. + You can extend the session management mechanism. One reason for this would be to improve the performance. For example, you could create a custom cookie handler that transforms or optimizes the session security token between its in-memory state and what goes into the cookie. To do so, you can configure the property of the to use a custom cookie handler that derives from . is the default cookie handler because the cookies exceed the allowable size for Hypertext Transfer Protocol (HTTP); if you use a custom cookie handler instead, you must implement chunking. For more information, see [ClaimsAwareWebFarm](http://go.microsoft.com/fwlink/?LinkID=248408) (http://go.microsoft.com/fwlink/?LinkID=248408) sample. This sample shows a farm ready session cache (as opposed to a tokenreplycache) so that you can use sessions by reference instead of exchanging big cookies; this sample also demonstrates an easier way of securing cookies in a farm. The session cache is WCF-based. With regard to session securing, the sample demonstrates a new capability in WIF 4.5 of a cookie transform based on MachineKey, which can be activated by simply pasting the appropriate snippet in the web.config. The sample itself is not "farmed", but it demonstrates what you need for making your app farm-ready. diff --git a/docs/framework/security/wsfederation-authentication-module-overview.md b/docs/framework/security/wsfederation-authentication-module-overview.md index 81cbf1a8c9c01..def8aceea7c87 100644 --- a/docs/framework/security/wsfederation-authentication-module-overview.md +++ b/docs/framework/security/wsfederation-authentication-module-overview.md @@ -42,7 +42,7 @@ Windows Identity Foundation (WIF) includes support for federated authentication 1. Passive redirect: When an unauthenticated user tries to access a protected resource, and you want to simply redirect them to an STS without requiring a login page, then this is the right approach. The STS verifies the user’s identity, and issues a security token that contains the appropriate claims for that user. This option requires the WS-FAM to be added in the HTTP Modules pipeline. You can use the Identity and Access Tool for Visual Studio 2012 to modify your application’s configuration file to use the WS-FAM and to federate with an STS. For more information, see [Identity and Access Tool for Visual Studio 2012](../../../docs/framework/security/identity-and-access-tool-for-vs.md). -2. You can call the method or the method from the code-behind for a sign-in page in your RP application. +2. You can call the method or the method from the code-behind for a sign-in page in your RP application. In passive redirect, all communication is performed through response/redirect from the client (typically a browser). You can add the WS-FAM to your application’s HTTP pipeline, where it watches for unauthenticated user requests and redirects users to the STS you specify. @@ -70,7 +70,7 @@ Windows Identity Foundation (WIF) includes support for federated authentication - The ASP.NET infrastructure invokes the module’s method to initialize the module. -- The event is raised when the ASP.NET infrastructure invokes the method for the first time on one of the application’s modules that derive from . This method accesses the static property, which causes configuration to be loaded from the Web.config file. This event is only raised the first time this property is accessed. The object that is initialized from configuration can be accessed through the property in an event handler. You can use this event to modify the configuration before it is applied to any modules. You can add a handler for this event in the Application_Start method: +- The event is raised when the ASP.NET infrastructure invokes the method for the first time on one of the application’s modules that derive from . This method accesses the static property, which causes configuration to be loaded from the Web.config file. This event is only raised the first time this property is accessed. The object that is initialized from configuration can be accessed through the property in an event handler. You can use this event to modify the configuration before it is applied to any modules. You can add a handler for this event in the Application_Start method: ``` void Application_Start(object sender, EventArgs e) @@ -79,7 +79,7 @@ Windows Identity Foundation (WIF) includes support for federated authentication } ``` - Each module overrides the and abstract methods. The first of these methods adds handlers for ASP.NET pipeline events that are of interest to the module. In most cases the module’s default implementation will suffice. The second of these methods initializes the module’s properties from its property. (This is a copy of the configuration that was loaded previously.) You may need to override this second method if you want to support the initialization of new properties from configuration in classes that you derive from or . In such cases you would also need to derive from the appropriate configuration objects to support the added configuration properties; for example, from , , or . + Each module overrides the and abstract methods. The first of these methods adds handlers for ASP.NET pipeline events that are of interest to the module. In most cases the module’s default implementation will suffice. The second of these methods initializes the module’s properties from its property. (This is a copy of the configuration that was loaded previously.) You may need to override this second method if you want to support the initialization of new properties from configuration in classes that you derive from or . In such cases you would also need to derive from the appropriate configuration objects to support the added configuration properties; for example, from , , or . - The WS-FAM raises the event when it intercepts a security token that has been issued by the STS. @@ -96,7 +96,7 @@ Windows Identity Foundation (WIF) includes support for federated authentication - The WS-FAM raises the event one time per session as the session is being closed down for each user. It is not raised if the session is closed down on the client-side (for example, by deleting the session cookie). In an SSO environment, the IP-STS can request each RP to sign out, too. This will also raise this event, with set to `true`. > [!NOTE] -> You should not use the property during any event raised by or . This is because is set after the authentication process, while events are raised during the authentication process. +> You should not use the property during any event raised by or . This is because is set after the authentication process, while events are raised during the authentication process. ### Configuration of Federated Authentication The WS-FAM and SAM are configured through the [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element. The [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/wsfederation.md) child element configures default values for the WS-FAM properties; such as the property and the property. (These values can be changed on a per request basis by providing handlers for some of the WS-FAM events; for example, .) The cookie handler that is used by the SAM is configured through the [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) child element. WIF provides a default cookie handler implemented in the class that can have its chunk size set through the [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/chunkedcookiehandler.md) element. The `` element references an , which provides configuration for other WIF components used in the application, such as the and the . The identity configuration may be referenced explicitly by specifying a named [\](../../../docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element in the `identityConfigurationName` attribute of the `` element. If the identity configuration is not referenced explicitly, the default identity configuration will be used. diff --git a/docs/framework/tools/fuslogvw-exe-assembly-binding-log-viewer.md b/docs/framework/tools/fuslogvw-exe-assembly-binding-log-viewer.md index 24b15a0cca3e3..3eb47f7708f12 100644 --- a/docs/framework/tools/fuslogvw-exe-assembly-binding-log-viewer.md +++ b/docs/framework/tools/fuslogvw-exe-assembly-binding-log-viewer.md @@ -215,7 +215,7 @@ Discarding native image. See the Important note regarding assemblies that are loaded as domain neutral. > [!IMPORTANT] -> When an assembly is loaded as domain neutral, for example by setting the property to or , turning on logging might leak memory in some cases. This can happen if a log entry is made when a domain-neutral module is loaded into an application domain, and later the application domain is unloaded. The log entry might not be released until the process ends. Some debuggers automatically turn on logging. +> When an assembly is loaded as domain neutral, for example by setting the property to or , turning on logging might leak memory in some cases. This can happen if a log entry is made when a domain-neutral module is loaded into an application domain, and later the application domain is unloaded. The log entry might not be released until the process ends. Some debuggers automatically turn on logging. #### To enable a custom log path diff --git a/docs/framework/tools/installutil-exe-installer-tool.md b/docs/framework/tools/installutil-exe-installer-tool.md index 627899956d7f0..8451424625862 100644 --- a/docs/framework/tools/installutil-exe-installer-tool.md +++ b/docs/framework/tools/installutil-exe-installer-tool.md @@ -56,7 +56,7 @@ installutil [/u[ninstall]] [options] assembly [[options] assembly] ... |Option|Description| |------------|-----------------| |`/h[elp]`

-or-

`/?`|Displays command syntax and options for the tool.| -|`/help` *assembly*

-or-

`/?` *assembly*|Displays additional options recognized by individual installers within the specified assembly, along with command syntax and options for InstallUtil.exe. This option adds the text returned by each installer component's property to the help text of InstallUtil.exe.| +|`/help` *assembly*

-or-

`/?` *assembly*|Displays additional options recognized by individual installers within the specified assembly, along with command syntax and options for InstallUtil.exe. This option adds the text returned by each installer component's property to the help text of InstallUtil.exe.| |`/AssemblyName` "*assemblyName*

,Version=*major.minor.build.revision*

,Culture=*locale*

,PublicKeyToken=*publicKeyToken*"|Specifies the strong name of an assembly, which must be registered in the global assembly cache. The assembly name must be fully qualified with the version, culture, and public key token of the assembly. The fully qualified name must be surrounded by quotes.

For example, "myAssembly, Culture=neutral, PublicKeyToken=0038abc9deabfle5, Version=4.0.0.0" is a fully qualified assembly name.| |`/InstallStateDir=[` *directoryName* `]`|Specifies the directory of the .InstallState file that contains the data used to uninstall the assembly. The default is the directory that contains the assembly.| |`/LogFile=`[*filename*]|Specifies the name of the log file where installation progress is recorded. By default, if the `/LogFile` option is omitted, a log file named *assemblyname*.InstallLog is created. If *filename* is omitted, no log file is generated.| @@ -69,7 +69,7 @@ installutil [/u[ninstall]] [options] assembly [[options] assembly] ... Individual installers used within an assembly may recognize options in addition to those listed in the [Options](#options) section. To learn about these options, run InstallUtil.exe with the paths of the assemblies on the command line along with the `/?` or `/help` option. To specify these options, you include them on the command line along with the options recognized by InstallUtil.exe. > [!NOTE] -> Help text on the options supported by individual installer components is returned by the property. The individual options that have been entered on the command line are accessible programmatically from the property. +> Help text on the options supported by individual installer components is returned by the property. The individual options that have been entered on the command line are accessible programmatically from the property. All options and command-line parameters are written to the installation log file. However, if you use the `/Password` parameter, which is recognized by some installer components, the password information will be replaced by eight asterisks (*) and will not appear in the log file. @@ -89,7 +89,7 @@ installutil [/u[ninstall]] [options] assembly [[options] assembly] ... - *assemblyname*.InstallState - Contains data used to uninstall the assembly. - Installutil.exe uses reflection to inspect the specified assemblies and to find all types that have the attribute set to `true`. The tool then executes either the or the method on each instance of the type. Installutil.exe performs installation in a transactional manner; that is, if one of the assemblies fails to install, it rolls back the installations of all other assemblies. Uninstall is not transactional. + Installutil.exe uses reflection to inspect the specified assemblies and to find all types that have the attribute set to `true`. The tool then executes either the or the method on each instance of the type. Installutil.exe performs installation in a transactional manner; that is, if one of the assemblies fails to install, it rolls back the installations of all other assemblies. Uninstall is not transactional. Installutil.exe cannot install or uninstall delay-signed assemblies, but it can install or uninstall strong-named assemblies. @@ -104,7 +104,7 @@ installutil [/u[ninstall]] [options] assembly [[options] assembly] ... installutil /? ``` - The following command displays a description of the command syntax and options for InstallUtil.exe. It also displays a description and list of options supported by the installer components in `myAssembly.exe` if help text has been assigned to the installer's property. + The following command displays a description of the command syntax and options for InstallUtil.exe. It also displays a description and list of options supported by the installer components in `myAssembly.exe` if help text has been assigned to the installer's property. ``` installutil /? myAssembly.exe diff --git a/docs/framework/tools/mgmtclassgen-exe.md b/docs/framework/tools/mgmtclassgen-exe.md index c78d624309bae..e845130b1d563 100644 --- a/docs/framework/tools/mgmtclassgen-exe.md +++ b/docs/framework/tools/mgmtclassgen-exe.md @@ -52,7 +52,7 @@ WMIClass [options] |**/?**|Displays command syntax and options for the tool.| ## Remarks - Mgmtclassgen.exe uses the method. Therefore, you can use any custom code provider to generate code in managed languages other than C#, Visual Basic, and JScript. + Mgmtclassgen.exe uses the method. Therefore, you can use any custom code provider to generate code in managed languages other than C#, Visual Basic, and JScript. Note that generated classes are bound to the schema for which they are generated. If the underlying schema changes, you must regenerate the class if you want it to reflect changes to the schema. @@ -158,7 +158,7 @@ public class App ## See Also - - + + [Tools](../../../docs/framework/tools/index.md) [Command Prompts](../../../docs/framework/tools/developer-command-prompt-for-vs.md) diff --git a/docs/framework/tools/ngen-exe-native-image-generator.md b/docs/framework/tools/ngen-exe-native-image-generator.md index ac4c3d271aa03..ffa8f62e365ae 100644 --- a/docs/framework/tools/ngen-exe-native-image-generator.md +++ b/docs/framework/tools/ngen-exe-native-image-generator.md @@ -138,20 +138,20 @@ ngen /? | /help Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], the native images that are generated with Ngen.exe can no longer be loaded into applications that are running in partial trust. Instead, the just-in-time (JIT) compiler is invoked. - Ngen.exe generates native images for the assembly specified by the `assemblyname` argument to the `install` action and all its dependencies. Dependencies are determined from references in the assembly manifest. The only scenario in which you need to install a dependency separately is when the application loads it using reflection, for example by calling the method. + Ngen.exe generates native images for the assembly specified by the `assemblyname` argument to the `install` action and all its dependencies. Dependencies are determined from references in the assembly manifest. The only scenario in which you need to install a dependency separately is when the application loads it using reflection, for example by calling the method. > [!IMPORTANT] -> Do not use the method with native images. An image loaded with this method cannot be used by other assemblies in the execution context. +> Do not use the method with native images. An image loaded with this method cannot be used by other assemblies in the execution context. Ngen.exe maintains a count on dependencies. For example, suppose `MyAssembly.exe` and `YourAssembly.exe` are both installed in the native image cache, and both have references to `OurDependency.dll`. If `MyAssembly.exe` is uninstalled, `OurDependency.dll` is not uninstalled. It is only removed when `YourAssembly.exe` is also uninstalled. - If you are generating a native image for an assembly in the global assembly cache, specify its display name. See . + If you are generating a native image for an assembly in the global assembly cache, specify its display name. See . The native images that Ngen.exe generates can be shared across application domains. This means you can use Ngen.exe in application scenarios that require assemblies to be shared across application domains. To specify domain neutrality: - Apply the attribute to your application. -- Set the property when you create setup information for a new application domain. +- Set the property when you create setup information for a new application domain. Always use domain-neutral code when loading the same assembly into multiple application domains. If a native image is loaded into a nonshared application domain after having been loaded into a shared domain, it cannot be used. @@ -283,7 +283,7 @@ ngen /? | /help ### Specifying a binding hint for a dependency - Apply the to an assembly to indicate the likelihood that a specified dependency will be loaded. indicates that hard binding is appropriate, indicates that the default for the dependency should be used, and indicates that hard binding is not appropriate. + Apply the to an assembly to indicate the likelihood that a specified dependency will be loaded. indicates that hard binding is appropriate, indicates that the default for the dependency should be used, and indicates that hard binding is not appropriate. The following code shows the attributes for an assembly that has two dependencies. The first dependency (Assembly1) is an appropriate candidate for hard binding, and the second (Assembly2) is not. @@ -309,10 +309,10 @@ using namespace System::Runtime::CompilerServices; ### Specifying a default binding hint for an assembly - Default binding hints are only needed for assemblies that will be used immediately and frequently by any application that has a dependency on them. Apply the with to such assemblies to specify that hard binding should be used. + Default binding hints are only needed for assemblies that will be used immediately and frequently by any application that has a dependency on them. Apply the with to such assemblies to specify that hard binding should be used. > [!NOTE] -> There is no reason to apply to .dll assemblies that do not fall into this category, because applying the attribute with any value other than has the same effect as not applying the attribute at all. +> There is no reason to apply to .dll assemblies that do not fall into this category, because applying the attribute with any value other than has the same effect as not applying the attribute at all. Microsoft uses the to specify that hard binding is the default for a very small number of assemblies in the .NET Framework, such as mscorlib.dll. @@ -410,7 +410,7 @@ ngen install c:\myfiles\MyAssembly.exe > [!NOTE] > This is a change from Ngen.exe behavior in the .NET Framework versions 1.0 and 1.1, where the application base is set to the current directory. - An assembly can have a dependency without a reference, for example if it loads a .dll file by using the method. You can create a native image for such a .dll file by using configuration information for the application assembly, with the `/ExeConfig` option. The following command generates a native image for `MyLib.dll,` using the configuration information from `MyApp.exe`. + An assembly can have a dependency without a reference, for example if it loads a .dll file by using the method. You can create a native image for such a .dll file by using configuration information for the application assembly, with the `/ExeConfig` option. The following command generates a native image for `MyLib.dll,` using the configuration information from `MyApp.exe`. ``` ngen install c:\myfiles\MyLib.dll /ExeConfig:c:\myapps\MyApp.exe diff --git a/docs/framework/ui-automation/add-content-to-a-text-box-using-ui-automation.md b/docs/framework/ui-automation/add-content-to-a-text-box-using-ui-automation.md index 6c24ba04dd0e8..bd0ce5b2e197a 100644 --- a/docs/framework/ui-automation/add-content-to-a-text-box-using-ui-automation.md +++ b/docs/framework/ui-automation/add-content-to-a-text-box-using-ui-automation.md @@ -26,7 +26,7 @@ manager: "markl" This topic contains example code that demonstrates how to use [!INCLUDE[TLA#tla_uiautomation](../../../includes/tlasharptla-uiautomation-md.md)] to insert text into a single-line text box. An alternate method is provided for multi-line and rich text controls where [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] is not applicable. For comparison purposes, the example also demonstrates how to use Win32 methods to accomplish the same results. ## Example - The following example steps through a sequence of text controls in a target application. Each text control is tested to see if a object can be obtained from it using the method. If the text control does support , the method is used to insert a user-defined string into the text control. Otherwise, the method is used. + The following example steps through a sequence of text controls in a target application. Each text control is tested to see if a object can be obtained from it using the method. If the text control does support , the method is used to insert a user-defined string into the text control. Otherwise, the method is used. [!code-csharp[InsertText#InsertText](../../../samples/snippets/csharp/VS_Snippets_Wpf/InsertText/CSharp/Window1.xaml.cs#inserttext)] [!code-vb[InsertText#InsertText](../../../samples/snippets/visualbasic/VS_Snippets_Wpf/InsertText/VisualBasic/Window1.xaml.vb#inserttext)] diff --git a/docs/framework/ui-automation/caching-in-ui-automation-clients.md b/docs/framework/ui-automation/caching-in-ui-automation-clients.md index 3c227337f3b23..674d63b1ab5b7 100644 --- a/docs/framework/ui-automation/caching-in-ui-automation-clients.md +++ b/docs/framework/ui-automation/caching-in-ui-automation-clients.md @@ -28,7 +28,7 @@ manager: "markl" The benefits of caching are most noticeable with [!INCLUDE[TLA#tla_wpf](../../../includes/tlasharptla-wpf-md.md)] controls and custom controls that have server-side UI Automation providers. There is less benefit when accessing client-side providers such as the default providers for [!INCLUDE[TLA2#tla_win32](../../../includes/tla2sharptla-win32-md.md)] controls. - Caching occurs when the application activates a and then uses any method or property that returns an ; for example, , . The methods of the class are an exception; caching is only done if a is specified as a parameter (for example, . + Caching occurs when the application activates a and then uses any method or property that returns an ; for example, , . The methods of the class are an exception; caching is only done if a is specified as a parameter (for example, . Caching also occurs when you subscribe to an event while a is active. The passed to your event handler as the source of an event contains the cached properties and patterns specified by the original . Any changes made to the after you subscribe to the event have no effect. @@ -44,17 +44,17 @@ manager: "markl" ### Control Patterns to Cache - You can specify control patterns to cache by calling for each pattern before activating the request. When a pattern is cached, its properties are not automatically cached; you must specify the properties you want cached by using . + You can specify control patterns to cache by calling for each pattern before activating the request. When a pattern is cached, its properties are not automatically cached; you must specify the properties you want cached by using . ### Scope and Filtering of Caching - You can specify the elements whose properties and patterns you want to cache by setting the property before activating the request. The scope is relative to the elements that are retrieved while the request is active. For example, if you set only , and then retrieve an , the properties and patterns of children of that element are cached, but not those of the element itself. To ensure that caching is done for the retrieved element itself, you must include in the property. It is not possible to set the scope to or . However, a parent element can be cached when a child element is cached; see Retrieving Cached Children and Parents in this topic. + You can specify the elements whose properties and patterns you want to cache by setting the property before activating the request. The scope is relative to the elements that are retrieved while the request is active. For example, if you set only , and then retrieve an , the properties and patterns of children of that element are cached, but not those of the element itself. To ensure that caching is done for the retrieved element itself, you must include in the property. It is not possible to set the scope to or . However, a parent element can be cached when a child element is cached; see Retrieving Cached Children and Parents in this topic. - The extent of caching is also affected by the property. By default, caching is performed only for elements that appear in the control view of the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] tree. However, you can change this property to apply caching to all elements, or only to elements that appear in the content view. + The extent of caching is also affected by the property. By default, caching is performed only for elements that appear in the control view of the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] tree. However, you can change this property to apply caching to all elements, or only to elements that appear in the content view. ### Strength of the Element References - When you retrieve an , by default you have access to all properties and patterns of that element, including those that were not cached. However, for greater efficiency you can specify that the reference to the element refers to cached data only, by setting the property of the to . In this case, you do not have access to any non-cached properties and patterns of retrieved elements. This means that you cannot access any properties through or the `Current` property of or any control pattern; nor can you retrieve a pattern by using or . On cached patterns, you can call methods that retrieve array properties, such as , but not any that perform actions on the control, such as . + When you retrieve an , by default you have access to all properties and patterns of that element, including those that were not cached. However, for greater efficiency you can specify that the reference to the element refers to cached data only, by setting the property of the to . In this case, you do not have access to any non-cached properties and patterns of retrieved elements. This means that you cannot access any properties through or the `Current` property of or any control pattern; nor can you retrieve a pattern by using or . On cached patterns, you can call methods that retrieve array properties, such as , but not any that perform actions on the control, such as . An example of an application that might not need full references to objects is a screen reader, which would prefetch the and properties of elements in a window but would not need the objects themselves. diff --git a/docs/framework/ui-automation/expose-a-server-side-ui-automation-provider.md b/docs/framework/ui-automation/expose-a-server-side-ui-automation-provider.md index 9e03ada70e752..870cd8560aba1 100644 --- a/docs/framework/ui-automation/expose-a-server-side-ui-automation-provider.md +++ b/docs/framework/ui-automation/expose-a-server-side-ui-automation-provider.md @@ -23,7 +23,7 @@ manager: "markl" > [!NOTE] > This documentation is intended for .NET Framework developers who want to use the managed [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] classes defined in the namespace. For the latest information about [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)], see [Windows Automation API: UI Automation](http://go.microsoft.com/fwlink/?LinkID=156746). - This topic contains example code that shows how to expose a server-side UI Automation provider that is hosted in a window. + This topic contains example code that shows how to expose a server-side UI Automation provider that is hosted in a window. The example overrides the window procedure to trap WM_GETOBJECT, which is the message sent by the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] core service when a client application requests information about the window. diff --git a/docs/framework/ui-automation/obtaining-ui-automation-elements.md b/docs/framework/ui-automation/obtaining-ui-automation-elements.md index 68bb24ed7326a..b36bd7c24d056 100644 --- a/docs/framework/ui-automation/obtaining-ui-automation-elements.md +++ b/docs/framework/ui-automation/obtaining-ui-automation-elements.md @@ -31,7 +31,7 @@ manager: "markl" ## Root Element All searches for objects must have a starting-place. This can be any element, including the desktop, an application window, or a control. - The root element for the desktop, from which all elements are descended, is obtained from the static property. + The root element for the desktop, from which all elements are descended, is obtained from the static property. > [!CAUTION] > In general, you should try to obtain only direct children of the . A search for descendants may iterate through hundreds or even thousands of elements, possibly resulting in a stack overflow. If you are attempting to obtain a specific element at a lower level, you should start your search from the application window or from a container at a lower level. diff --git a/docs/framework/ui-automation/support-control-patterns-in-a-ui-automation-provider.md b/docs/framework/ui-automation/support-control-patterns-in-a-ui-automation-provider.md index 3c9e6308b16ae..5560e02f5902f 100644 --- a/docs/framework/ui-automation/support-control-patterns-in-a-ui-automation-provider.md +++ b/docs/framework/ui-automation/support-control-patterns-in-a-ui-automation-provider.md @@ -28,7 +28,7 @@ manager: "markl" 1. Implement the appropriate interfaces for the control patterns that the element should support, such as for . -2. Return the object containing your implementation of each control interface in your implementation of +2. Return the object containing your implementation of each control interface in your implementation of ## Example The following example shows an implementation of for a single-selection custom list box. It returns three properties and gets the currently selected item. diff --git a/docs/framework/ui-automation/ui-automation-and-microsoft-active-accessibility.md b/docs/framework/ui-automation/ui-automation-and-microsoft-active-accessibility.md index af2a68f0be9d9..c39bf49eefc3d 100644 --- a/docs/framework/ui-automation/ui-automation-and-microsoft-active-accessibility.md +++ b/docs/framework/ui-automation/ui-automation-and-microsoft-active-accessibility.md @@ -135,7 +135,7 @@ manager: "markl" |`get_accKeyboardShortcut`| or |`AccessKeyProperty` takes precedence if both are present.| |`get_accName`||| |`get_accRole`||See the previous table for mapping of roles to control types.| -|`get_accValue`|

|Valid only for control types that support ValuePattern or RangeValuePattern. RangeValue values are normalized to 0-100, to be consistent with MSAA behavior. Value items use a string.| +|`get_accValue`|

|Valid only for control types that support ValuePattern or RangeValuePattern. RangeValue values are normalized to 0-100, to be consistent with MSAA behavior. Value items use a string.| |`get_accHelp`||| |`accLocation`||| |`get_accDescription`|Not supported in [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)]|`accDescription` did not have a clear specification within MSAA, which resulted in providers placing different pieces of information in this property.| @@ -158,7 +158,7 @@ manager: "markl" |STATE_SYSTEM_MUTLISELECTABLE||N| |STATE_SYSTEM_OFFSCREEN| = True|N| |STATE_SYSTEM_PROTECTED||N| -|STATE_SYSTEM_READONLY| and |N| +|STATE_SYSTEM_READONLY| and |N| |STATE_SYSTEM_SELECTABLE| is supported|N| |STATE_SYSTEM_SELECTED||N| |STATE_SYSTEM_SIZEABLE||N| @@ -213,7 +213,7 @@ manager: "markl" |EVENT_OBJECT_SELECTIONWITHIN|No equivalent| |EVENT_OBJECT_SHOW|| |EVENT_OBJECT_STATECHANGE|Various property-changed events| -|EVENT_OBJECT_VALUECHANGE| and changed| +|EVENT_OBJECT_VALUECHANGE| and changed| |EVENT_SYSTEM_ALERT|No equivalent| |EVENT_SYSTEM_CAPTUREEND|No equivalent| |EVENT_SYSTEM_CAPTURESTART|No equivalent| diff --git a/docs/framework/ui-automation/ui-automation-and-screen-scaling.md b/docs/framework/ui-automation/ui-automation-and-screen-scaling.md index 972ad6a7b8837..4f33663d305c7 100644 --- a/docs/framework/ui-automation/ui-automation-and-screen-scaling.md +++ b/docs/framework/ui-automation/ui-automation-and-screen-scaling.md @@ -41,7 +41,7 @@ manager: "markl" Suppose you design a dialog box with a button at coordinates (100, 48). When this dialog box is displayed at the default 96 [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)], the button is located at physical coordinates of (100, 48). At 120 [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)], it is located at physical coordinates of (125, 60). But the logical coordinates are the same at any [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)] setting: (100, 48). - Logical coordinates are important, because they make the behavior of the operating system and applications consistent regardless of the [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)] setting. For example, normally returns the logical coordinates. If you move the cursor over an element in a dialog box, the same coordinates are returned regardless of the [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)] setting. If you draw a control at (100, 100), it is drawn to those logical coordinates, and will occupy the same relative position at any [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)] setting. + Logical coordinates are important, because they make the behavior of the operating system and applications consistent regardless of the [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)] setting. For example, normally returns the logical coordinates. If you move the cursor over an element in a dialog box, the same coordinates are returned regardless of the [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)] setting. If you draw a control at (100, 100), it is drawn to those logical coordinates, and will occupy the same relative position at any [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)] setting. ## Scaling in UI Automation Clients @@ -74,7 +74,7 @@ manager: "markl" [!code-vb[UIAClient_snip#185](../../../samples/snippets/visualbasic/VS_Snippets_Wpf/UIAClient_snip/VisualBasic/ClientForm.vb#185)] > [!CAUTION] -> Do not use . The behavior of this property outside client windows in a scaled environment is undefined. +> Do not use . The behavior of this property outside client windows in a scaled environment is undefined. If your application performs direct cross-process communication with non- [!INCLUDE[TLA2#tla_dpi](../../../includes/tla2sharptla-dpi-md.md)]-aware applications, you may have convert between logical and physical coordinates by using the [!INCLUDE[TLA#tla_win32](../../../includes/tlasharptla-win32-md.md)] functions `PhysicalToLogicalPoint` and `LogicalToPhysicalPoint`. diff --git a/docs/framework/ui-automation/ui-automation-control-patterns-for-clients.md b/docs/framework/ui-automation/ui-automation-control-patterns-for-clients.md index 1f7e972790f9d..5a3c3e6a7f96a 100644 --- a/docs/framework/ui-automation/ui-automation-control-patterns-for-clients.md +++ b/docs/framework/ui-automation/ui-automation-control-patterns-for-clients.md @@ -30,7 +30,7 @@ manager: "markl" ## Getting Control Patterns - Clients retrieve a control pattern from an by calling either or . + Clients retrieve a control pattern from an by calling either or . Clients can use the method or an individual `IsPatternAvailable` property (for example, ) to determine if a pattern or group of patterns is supported on the . However, it is more efficient to attempt to get the control pattern and test for a `null` reference than to check the supported properties and retrieve the control pattern since it results in fewer cross-process calls. @@ -40,7 +40,7 @@ manager: "markl" ## Retrieving Properties on Control Patterns - Clients can retrieve the property values on control patterns by calling either or and casting the object returned to an appropriate type. For more information on [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] properties, see [UI Automation Properties for Clients](../../../docs/framework/ui-automation/ui-automation-properties-for-clients.md). + Clients can retrieve the property values on control patterns by calling either or and casting the object returned to an appropriate type. For more information on [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] properties, see [UI Automation Properties for Clients](../../../docs/framework/ui-automation/ui-automation-properties-for-clients.md). In addition to the `GetPropertyValue` methods, property values can be retrieved through the [!INCLUDE[TLA#tla_clr](../../../includes/tlasharptla-clr-md.md)] accessors to access the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] properties on a pattern. diff --git a/docs/framework/ui-automation/ui-automation-control-patterns-overview.md b/docs/framework/ui-automation/ui-automation-control-patterns-overview.md index 5ad0e20ba50d6..61a958055a1c0 100644 --- a/docs/framework/ui-automation/ui-automation-control-patterns-overview.md +++ b/docs/framework/ui-automation/ui-automation-control-patterns-overview.md @@ -47,7 +47,7 @@ manager: "markl" UI Automation clients access methods and properties of [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] control pattern classes and use them to get information about the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], or to manipulate the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]. These control pattern classes are found in the namespace (for example, and ). - Clients use methods (such as or ) or the [!INCLUDE[TLA#tla_clr](../../../includes/tlasharptla-clr-md.md)] accessors to access the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] properties on a pattern. Each control pattern class has a field member (for example, ``or ) that identifies that control pattern and can be passed as a parameter to or to retrieve that pattern for an . + Clients use methods (such as or ) or the [!INCLUDE[TLA#tla_clr](../../../includes/tlasharptla-clr-md.md)] accessors to access the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] properties on a pattern. Each control pattern class has a field member (for example, ``or ) that identifies that control pattern and can be passed as a parameter to or to retrieve that pattern for an . ## Dynamic Control Patterns diff --git a/docs/framework/ui-automation/ui-automation-events-overview.md b/docs/framework/ui-automation/ui-automation-events-overview.md index 09245a2beb0ae..2973db8ffdeb1 100644 --- a/docs/framework/ui-automation/ui-automation-events-overview.md +++ b/docs/framework/ui-automation/ui-automation-events-overview.md @@ -61,12 +61,12 @@ manager: "markl" |Client Identifier|Provider identifier|Event Arguments Type| |-----------------------|-------------------------|--------------------------| -|||| -|























|























|| -|||| -|||| -|||| -|||| +|||| +|























|























|| +|||| +|||| +|||| +|||| ## UI Automation Event Arguments diff --git a/docs/framework/ui-automation/ui-automation-properties-for-clients.md b/docs/framework/ui-automation/ui-automation-properties-for-clients.md index 5e1a87fc810a5..0b0a02c7f0bc3 100644 --- a/docs/framework/ui-automation/ui-automation-properties-for-clients.md +++ b/docs/framework/ui-automation/ui-automation-properties-for-clients.md @@ -36,7 +36,7 @@ manager: "markl" ## Property IDs Property [!INCLUDE[TLA#tla_id#plural](../../../includes/tlasharptla-idsharpplural-md.md)] are unique, constant values that are encapsulated in objects. UI Automation client applications get these [!INCLUDE[TLA2#tla_id#plural](../../../includes/tla2sharptla-idsharpplural-md.md)] from the class or from the appropriate control pattern class, such as . UI Automation providers get them from or from one of the control pattern identifiers classes, such as . - The numeric of an is used by providers to identify properties that are being queried for in the method. In general, client applications do not need to examine the . The is used only for debugging and diagnostic purposes. + The numeric of an is used by providers to identify properties that are being queried for in the method. In general, client applications do not need to examine the . The is used only for debugging and diagnostic purposes. ## Property Conditions @@ -80,7 +80,7 @@ manager: "markl" ## Default Property Values If a UI Automation provider does not implement a property, the [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] system is able to supply a default value. For example, if the provider for a control does not support the property identified by , [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] returns an empty string. Similarly, if the provider does not support the property identified by , [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] returns `false`. - You can change this behavior by using the and method overloads. When you specify `true` as the second parameter, [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] does not return a default value, but instead returns the special value . + You can change this behavior by using the and method overloads. When you specify `true` as the second parameter, [!INCLUDE[TLA2#tla_uiautomation](../../../includes/tla2sharptla-uiautomation-md.md)] does not return a default value, but instead returns the special value . The following example code attempts to retrieve a property from an element, and if the property is not supported, an application-defined value is used instead. diff --git a/docs/framework/unmanaged-api/debugging/clr-debugging-process-flags-enumeration.md b/docs/framework/unmanaged-api/debugging/clr-debugging-process-flags-enumeration.md index 3ccc6b3486ce8..d6da1c6eb9afe 100644 --- a/docs/framework/unmanaged-api/debugging/clr-debugging-process-flags-enumeration.md +++ b/docs/framework/unmanaged-api/debugging/clr-debugging-process-flags-enumeration.md @@ -47,7 +47,7 @@ typedef enum CLR_DEBUGGING_PROCESS_FLAGS |Member|Description| |------------|-----------------| |`CLR_DEBUGGING_MANAGED_EVENT_PENDING`|This runtime has a non-catch-up managed debugger event to send. See the Remarks section for the distinction between catch-up and non-catch-up events.| -|`CLR_DEBUGGING_MANAGED_EVENT_DEBUGGER_LAUNCH`|The managed event that is pending is a request.| +|`CLR_DEBUGGING_MANAGED_EVENT_DEBUGGER_LAUNCH`|The managed event that is pending is a request.| ## Remarks Catch-up events include process, application domain, assembly, module, and thread creation notifications that bring the debugger up to the current state after it has attached to a process. Non-catch-up events, which are indicated by the `CLR_DEBUGGING_MANAGED_EVENT_PENDING` flag, include all other debugger events, such as exceptions and managed debugging assistant (MDA) notifications. diff --git a/docs/framework/unmanaged-api/debugging/cor-type-layout-structure.md b/docs/framework/unmanaged-api/debugging/cor-type-layout-structure.md index 0a48380dbade7..3263994d941e4 100644 --- a/docs/framework/unmanaged-api/debugging/cor-type-layout-structure.md +++ b/docs/framework/unmanaged-api/debugging/cor-type-layout-structure.md @@ -48,7 +48,7 @@ typedef struct COR_TYPE_LAYOUT { |Member|Description| |------------|-----------------| -|`parentID`|The identifier of the parent type to this type. This will be the NULL type id (token1= 0, token2 = 0) if the type id corresponds to .| +|`parentID`|The identifier of the parent type to this type. This will be the NULL type id (token1= 0, token2 = 0) if the type id corresponds to .| |`objectSize`|The base size of an object of this type. This is the total size for non-variable sized objects.| |`numFields`|The number of fields included in objects of this type.| |`boxOffset`|If this type is boxed, the beginning offset of an object's fields. This field is valid only for value types such as primitives and structures.| diff --git a/docs/framework/unmanaged-api/debugging/cordebugblockingreason-enumeration.md b/docs/framework/unmanaged-api/debugging/cordebugblockingreason-enumeration.md index 28b51b2cc7b47..e47226f04b66e 100644 --- a/docs/framework/unmanaged-api/debugging/cordebugblockingreason-enumeration.md +++ b/docs/framework/unmanaged-api/debugging/cordebugblockingreason-enumeration.md @@ -48,8 +48,8 @@ Typedef enum CorDebugBlockingReason |Member|Description| |------------|-----------------| |`BLOCKING_NONE`|Internal use only.| -|`BLOCKING_MONITOR_CRITICAL_SECTION`|A thread is trying to acquire the critical section that is associated with the monitor lock on an object. Typically, this occurs when you call one of the or methods.| -|`BLOCKING_MONITOR_EVENT`|A thread is waiting on the event that is associated with a monitor lock for an object. Typically, this occurs when you call one of the `Wait` methods.| +|`BLOCKING_MONITOR_CRITICAL_SECTION`|A thread is trying to acquire the critical section that is associated with the monitor lock on an object. Typically, this occurs when you call one of the or methods.| +|`BLOCKING_MONITOR_EVENT`|A thread is waiting on the event that is associated with a monitor lock for an object. Typically, this occurs when you call one of the `Wait` methods.| ## Remarks When the `BLOCKING_MONITOR_CRITICAL_SECTION` or `BLOCKING_MONITOR_EVENT` member is used in a [CorDebugBlockingObject](../../../../docs/framework/unmanaged-api/debugging/cordebugblockingobject-structure.md) structure, the `pBlockingObject` member of the structure points to an "ICorDebugValue" interface that represents the object that is being entered. It is also guaranteed to implement the [ICorDebugHeapValue3](../../../../docs/framework/unmanaged-api/debugging/icordebugheapvalue3-interface.md) interface. diff --git a/docs/framework/unmanaged-api/debugging/icordebugappdomain-getobject-method.md b/docs/framework/unmanaged-api/debugging/icordebugappdomain-getobject-method.md index 274aefe4e5fcd..47967b7749627 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugappdomain-getobject-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugappdomain-getobject-method.md @@ -46,10 +46,10 @@ HRESULT GetObject ( [out] A pointer to the address of an ICorDebugValue interface object that represents the CLR application domain. ## Return Value - If a managed object hasn't been constructed for this application domain, the method returns `S_FALSE` and places `NULL` in `*ppObject`. + If a managed object hasn't been constructed for this application domain, the method returns `S_FALSE` and places `NULL` in `*ppObject`. ## Remarks - Each application domain in a process may have a managed object in the runtime that represents it. This function gets an ICorDebugValue interface object that corresponds to this managed object. + Each application domain in a process may have a managed object in the runtime that represents it. This function gets an ICorDebugValue interface object that corresponds to this managed object. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/debugging/icordebugexceptionobjectvalue-interface.md b/docs/framework/unmanaged-api/debugging/icordebugexceptionobjectvalue-interface.md index bcbf439183fe1..bdaf806c34120 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugexceptionobjectvalue-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugexceptionobjectvalue-interface.md @@ -39,7 +39,7 @@ Extends the "ICorDebugObjectValue" interface to provide stack trace information |[EnumerateExceptionCallStack Method](../../../../docs/framework/unmanaged-api/debugging/icordebugexceptionobjectvalue-enumerateexceptioncallstack-method.md)|Gets an enumerator to the call stack embedded in an exception object.| ## Remarks - The call to `QueryInterface` will succeed for managed objects that derive from . + The call to `QueryInterface` will succeed for managed objects that derive from . ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/debugging/icordebugheapvalue3-getmonitoreventwaitlist-method.md b/docs/framework/unmanaged-api/debugging/icordebugheapvalue3-getmonitoreventwaitlist-method.md index c4ef8fe486373..d4fedd674e102 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugheapvalue3-getmonitoreventwaitlist-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugheapvalue3-getmonitoreventwaitlist-method.md @@ -56,7 +56,7 @@ HRESULT GetMonitorEventWaitList ( ## Exceptions ## Remarks - The first thread in the list is the first thread that is released by the next call to . The next thread in the list is released on the following call, and so on. + The first thread in the list is the first thread that is released by the next call to . The next thread in the list is released on the following call, and so on. If the list is not empty, this method returns S_OK. If the list is empty, the method returns S_FALSE; in this case, the enumeration is still valid, although it is empty. diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe3-getreturnvalueforiloffset-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe3-getreturnvalueforiloffset-method.md index 1ac7fb7f917f5..5fbe40a3ad50e 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe3-getreturnvalueforiloffset-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe3-getreturnvalueforiloffset-method.md @@ -45,7 +45,7 @@ HRESULT GetReturnValueForILOffset( A pointer to the address of an "ICorDebugValue" interface object that provides information about the return value of a function call. ## Remarks - This method is used along with the [ICorDebugCode3::GetReturnValueLiveOffset](../../../../docs/framework/unmanaged-api/debugging/icordebugcode3-getreturnvalueliveoffset-method.md) method to get the return value of a method. It is particularly useful in the case of methods whose return values are ignored, as in the following two code examples. The first example calls the method, but ignores the method's return value. + This method is used along with the [ICorDebugCode3::GetReturnValueLiveOffset](../../../../docs/framework/unmanaged-api/debugging/icordebugcode3-getreturnvalueliveoffset-method.md) method to get the return value of a method. It is particularly useful in the case of methods whose return values are ignored, as in the following two code examples. The first example calls the method, but ignores the method's return value. [!code-csharp[Unmanaged.Debugging.MRV#1](../../../../samples/snippets/csharp/VS_Snippets_CLR/unmanaged.debugging.mrv/cs/mrv1.cs#1)] [!code-vb[Unmanaged.Debugging.MRV#1](../../../../samples/snippets/visualbasic/VS_Snippets_CLR/unmanaged.debugging.mrv/vb/mrv1.vb#1)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback3-customnotification-method.md b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback3-customnotification-method.md index cd67b6225a468..67f4ec1661165 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback3-customnotification-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback3-customnotification-method.md @@ -57,7 +57,7 @@ HRESULT CustomNotification(ICorDebugThread * pThread, ## Exceptions ## Remarks - A subsequent call to the [ICorDebugThread4::GetCurrentCustomDebuggerNotification](../../../../docs/framework/unmanaged-api/debugging/icordebugthread4-getcurrentcustomdebuggernotification-method.md) method retrieves the thread object that was passed to the method. The thread object's type must have been previously enabled by calling the [ICorDebugProcess3::SetEnableCustomNotification](../../../../docs/framework/unmanaged-api/debugging/icordebugprocess3-setenablecustomnotification-method.md) method. The debugger can read type-specific parameters from the fields of the thread object, and can store responses into fields. + A subsequent call to the [ICorDebugThread4::GetCurrentCustomDebuggerNotification](../../../../docs/framework/unmanaged-api/debugging/icordebugthread4-getcurrentcustomdebuggernotification-method.md) method retrieves the thread object that was passed to the method. The thread object's type must have been previously enabled by calling the [ICorDebugProcess3::SetEnableCustomNotification](../../../../docs/framework/unmanaged-api/debugging/icordebugprocess3-setenablecustomnotification-method.md) method. The debugger can read type-specific parameters from the fields of the thread object, and can store responses into fields. The [ICorDebug](../../../../docs/framework/unmanaged-api/debugging/icordebug-interface.md) interface imposes no policy on the types of notifications or their contents, and the semantics of the notifications are strictly a contract between debuggers, applications, and the .NET Framework. diff --git a/docs/framework/unmanaged-api/debugging/icordebugmergedassemblyrecord-getsimplename-method.md b/docs/framework/unmanaged-api/debugging/icordebugmergedassemblyrecord-getsimplename-method.md index 7e447864bbdaf..3577967f0002d 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmergedassemblyrecord-getsimplename-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmergedassemblyrecord-getsimplename-method.md @@ -41,7 +41,7 @@ HRESULT GetSimpleName( A pointer to a character array. ## Remarks - This method retrieves the simple name of an assembly (such as "System.Collections"), without a file extension, version, culture, or public key token. It corresponds to the property in managed code. + This method retrieves the simple name of an assembly (such as "System.Collections"), without a file extension, version, culture, or public key token. It corresponds to the property in managed code. > [!NOTE] > This method is available with .NET Native only. diff --git a/docs/framework/unmanaged-api/debugging/icordebugprocess3-setenablecustomnotification-method.md b/docs/framework/unmanaged-api/debugging/icordebugprocess3-setenablecustomnotification-method.md index e7cf7c32bb86e..1a36f9c1c9d3c 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugprocess3-setenablecustomnotification-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugprocess3-setenablecustomnotification-method.md @@ -48,7 +48,7 @@ HRESULT SetEnableCustomNotification(ICorDebugClass * pClass, [in] `true` to enable custom debugger notifications; `false` to disable notifications. The default value is `false`. ## Remarks - When `fEnable` is set to `true`, calls to the method trigger an [ICorDebugManagedCallback3::CustomNotification](../../../../docs/framework/unmanaged-api/debugging/icordebugmanagedcallback3-customnotification-method.md) callback. Notifications are disabled by default; therefore, the debugger must specify any notification types it knows about and wants to handle. Because the [ICorDebugClass](../../../../docs/framework/unmanaged-api/debugging/icordebug-interface.md) class is scoped by application domain, the debugger must call `SetEnableCustomNotification` for every application domain in the process if it wants to receive the notification across the entire process. + When `fEnable` is set to `true`, calls to the method trigger an [ICorDebugManagedCallback3::CustomNotification](../../../../docs/framework/unmanaged-api/debugging/icordebugmanagedcallback3-customnotification-method.md) callback. Notifications are disabled by default; therefore, the debugger must specify any notification types it knows about and wants to handle. Because the [ICorDebugClass](../../../../docs/framework/unmanaged-api/debugging/icordebug-interface.md) class is scoped by application domain, the debugger must call `SetEnableCustomNotification` for every application domain in the process if it wants to receive the notification across the entire process. Starting with the [!INCLUDE[net_v40_long](../../../../includes/net-v40-long-md.md)], the only supported notification is a cross-thread dependency notification. diff --git a/docs/framework/unmanaged-api/debugging/icordebugprocess6-interface.md b/docs/framework/unmanaged-api/debugging/icordebugprocess6-interface.md index 9197074b192b6..a72d697bd725a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugprocess6-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugprocess6-interface.md @@ -28,7 +28,7 @@ Logically extends the ICorDebugProcess interface to enable features such as deco |[EnableVirtualModuleSplitting Method](../../../../docs/framework/unmanaged-api/debugging/icordebugprocess6-enablevirtualmodulesplitting-method.md)|Enables or disables virtual module splitting.| |[GetCode Method](../../../../docs/framework/unmanaged-api/debugging/icordebugprocess6-getcode-method.md)|Gets information about the managed code at a particular code address.| |[GetExportStepInfo Method](../../../../docs/framework/unmanaged-api/debugging/icordebugprocess6-getexportstepinfo-method.md)|Provides information on runtime exported functions to help step through managed code.| -|[MarkDebuggerAttached Method](../../../../docs/framework/unmanaged-api/debugging/icordebugprocess6-markdebuggerattached-method.md)|Changes the internal state of the debugee so that the method in the .NET Framework Class Library returns `true`.| +|[MarkDebuggerAttached Method](../../../../docs/framework/unmanaged-api/debugging/icordebugprocess6-markdebuggerattached-method.md)|Changes the internal state of the debugee so that the method in the .NET Framework Class Library returns `true`.| |[ProcessStateChanged Method](../../../../docs/framework/unmanaged-api/debugging/icordebugprocess6-processstatechanged-method.md)|Notifies [ICorDebug](../../../../docs/framework/unmanaged-api/debugging/icordebug-interface.md) that the process is running.| ## Remarks diff --git a/docs/framework/unmanaged-api/debugging/icordebugprocess6-markdebuggerattached-method.md b/docs/framework/unmanaged-api/debugging/icordebugprocess6-markdebuggerattached-method.md index b19bb12ccf71c..217a4d541ddda 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugprocess6-markdebuggerattached-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugprocess6-markdebuggerattached-method.md @@ -18,7 +18,7 @@ ms.author: "ronpet" manager: "wpickett" --- # ICorDebugProcess6::MarkDebuggerAttached Method -Changes the internal state of the debugee so that the method in the .NET Framework Class Library returns `true`. +Changes the internal state of the debugee so that the method in the .NET Framework Class Library returns `true`. ## Syntax @@ -30,7 +30,7 @@ HRESULT MarkDebuggerAttached( #### Parameters `fIsAttached` - `true` if the method should indicate that a debugger is attached; `false` otherwise. + `true` if the method should indicate that a debugger is attached; `false` otherwise. ## Return Value The method can return the values listed in the following table. @@ -38,7 +38,7 @@ HRESULT MarkDebuggerAttached( |Return value|Description| |------------------|-----------------| |`S_OK`|The debuggee was successfully updated.| -|`CORDBG_E_MODULE_NOT_LOADED`|The assembly that contains the method is not loaded, or some other error, such as missing metadata, is preventing it from being recognized.

This error is common and benign. You should call the method again when additional assemblies load.| +|`CORDBG_E_MODULE_NOT_LOADED`|The assembly that contains the method is not loaded, or some other error, such as missing metadata, is preventing it from being recognized.

This error is common and benign. You should call the method again when additional assemblies load.| |Other failing `HRESULT` values.|Other values likely indicate misbehaving debugger or compiler components.| ## Remarks diff --git a/docs/framework/unmanaged-api/debugging/icordebugprocess7-setwriteablemetadataupdatemode-method.md b/docs/framework/unmanaged-api/debugging/icordebugprocess7-setwriteablemetadataupdatemode-method.md index f3d8213485d21..a4deb71192181 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugprocess7-setwriteablemetadataupdatemode-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugprocess7-setwriteablemetadataupdatemode-method.md @@ -43,7 +43,7 @@ HRESULT SetWriteableMetadataUpdateMode( A [WriteableMetadataUpdateMode](../../../../docs/framework/unmanaged-api/debugging/writeablemetadataupdatemode-enumeration.md) enumeration value that specifies whether in-memory updates to metadata in the target process are visible (`WriteableMetadataUpdateMode::AlwaysShowUpdates`) or not visible (`WriteableMetadataUpdateMode::LegacyCompatPolicy`) to the debugger. ## Remarks - Updates to the metadata of the target process can come from Edit and Continue, a profiler, or . + Updates to the metadata of the target process can come from Edit and Continue, a profiler, or . ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/guid-managedname-attribute.md b/docs/framework/unmanaged-api/guid-managedname-attribute.md index 870c8f0d703ac..7adf20db41077 100644 --- a/docs/framework/unmanaged-api/guid-managedname-attribute.md +++ b/docs/framework/unmanaged-api/guid-managedname-attribute.md @@ -55,7 +55,7 @@ EXTERN_GUID(GUID_ManagedName, 0xf21f359, 0xab84, 0x41e8, 0x9a, 0x78, 0x36, 0xd1, ## Remarks A custom interface attribute defines metadata for an object in the type library. - Use or to retrieve the managed name from the attribute. + Use or to retrieve the managed name from the attribute. For more information, see [Interface Attributes](/cpp/windows/interface-attributes) in the Visual C++ reference documentation. diff --git a/docs/framework/unmanaged-api/hosting/eapicategories-enumeration.md b/docs/framework/unmanaged-api/hosting/eapicategories-enumeration.md index 6f8332e955bf0..c5f77bcedc667 100644 --- a/docs/framework/unmanaged-api/hosting/eapicategories-enumeration.md +++ b/docs/framework/unmanaged-api/hosting/eapicategories-enumeration.md @@ -69,7 +69,7 @@ typedef enum { ## Remarks The [ICLRHostProtectionManager::SetProtectedCategories](../../../../docs/framework/unmanaged-api/hosting/iclrhostprotectionmanager-setprotectedcategories-method.md) method takes a parameter of type `EApiCategories`. - The `EApiCategories` enumeration and the `SetProtectedCategories` method are directly related to the managed class. The managed class is used with the enumeration, whose values correspond directly to the `EApiCategories` values, to mark managed types and members that expose capabilities corresponding to the categories described by `EApiCategories`. + The `EApiCategories` enumeration and the `SetProtectedCategories` method are directly related to the managed class. The managed class is used with the enumeration, whose values correspond directly to the `EApiCategories` values, to mark managed types and members that expose capabilities corresponding to the categories described by `EApiCategories`. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/iappdomainsetup-interface.md b/docs/framework/unmanaged-api/hosting/iappdomainsetup-interface.md index 4646023e13450..b49f572d4fa80 100644 --- a/docs/framework/unmanaged-api/hosting/iappdomainsetup-interface.md +++ b/docs/framework/unmanaged-api/hosting/iappdomainsetup-interface.md @@ -30,7 +30,7 @@ ms.author: "ronpet" manager: "wpickett" --- # IAppDomainSetup Interface -Provides properties that allow the host to configure an type before calling the [ICorRuntimeHost::CreateDomainEx](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md) method to create it. +Provides properties that allow the host to configure an type before calling the [ICorRuntimeHost::CreateDomainEx](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md) method to create it. ## Properties @@ -48,7 +48,7 @@ Provides properties that allow the host to configure an |Gets or sets a string that indicates whether shadow-copying is turned on or off. Valid values are "true" or "false".| ## Remarks - The `IAppDomainSetup` interface corresponds to the managed interface, which the type implements. See for detailed descriptions of its properties. + The `IAppDomainSetup` interface corresponds to the managed interface, which the type implements. See for detailed descriptions of its properties. `IAppDomainSetup` represents assembly binding information that can be added to an instance before its creation. For example, a host can set the property to establish a root directory, which the common language runtime (CLR) probes for managed assemblies. diff --git a/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentallocated-method.md b/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentallocated-method.md index ed5bf42d7b63b..140339a331328 100644 --- a/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentallocated-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentallocated-method.md @@ -56,7 +56,7 @@ HRESULT GetCurrentAllocated([in] DWORD dwAppDomainId, |COR_E_APPDOMAINUNLOADED|The application domain has been unloaded or does not exist.| ## Remarks - This method is the unmanaged equivalent of the managed property. + This method is the unmanaged equivalent of the managed property. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentcputime-method.md b/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentcputime-method.md index f51924e24b04f..4a81ddfe5177a 100644 --- a/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentcputime-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentcputime-method.md @@ -56,7 +56,7 @@ HRESULT GetCurrentCpuTime([in] DWORD dwAppDomainId, |E_FAIL|Application domain resource monitoring is not enabled.

-or-

All other failures.| ## Remarks - This method is the unmanaged equivalent of the managed property. + This method is the unmanaged equivalent of the managed property. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentsurvived-method.md b/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentsurvived-method.md index b9cc56f17abcc..13c38679c7f01 100644 --- a/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentsurvived-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentsurvived-method.md @@ -61,9 +61,9 @@ HRESULT STDMETHODCALLTYPE GetCurrentSurvived( |COR_E_APPDOMAINUNLOADED|The application domain has been unloaded or does not exist.| ## Remarks - Statistics are updated only after a full, blocking garbage collection; that is, a collection that includes all generations and that stops the application while collection occurs. For example, the method overload performs a full, blocking collection. Concurrent garbage collection occurs in the background and does not block the application. + Statistics are updated only after a full, blocking garbage collection; that is, a collection that includes all generations and that stops the application while collection occurs. For example, the method overload performs a full, blocking collection. Concurrent garbage collection occurs in the background and does not block the application. - The `GetCurrentSurvived` method is the unmanaged equivalent of the managed property. + The `GetCurrentSurvived` method is the unmanaged equivalent of the managed property. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-interface.md b/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-interface.md index 139d1f063b222..dedeef842d5c8 100644 --- a/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-interface.md +++ b/docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-interface.md @@ -43,15 +43,15 @@ Provides methods that inspect an application domain's memory and CPU usage. ## Remarks The `ICLRAppDomainResourceMonitor` interface provides functionality that is similar to the following managed properties: -- +- -- +- -- +- -- +- -- +- ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/iclrdomainmanager-interface.md b/docs/framework/unmanaged-api/hosting/iclrdomainmanager-interface.md index e261865a1f38c..d491b9e4f4796 100644 --- a/docs/framework/unmanaged-api/hosting/iclrdomainmanager-interface.md +++ b/docs/framework/unmanaged-api/hosting/iclrdomainmanager-interface.md @@ -34,7 +34,7 @@ Enables the host to specify the application domain manager that will be used to |Method|Description| |------------|-----------------| -|[SetAppDomainManagerType Method](../../../../docs/framework/unmanaged-api/hosting/iclrdomainmanager-setappdomainmanagertype-method.md)|Specifies the type, derived from the class, of the application domain manager that will be used to initialize the default application domain.| +|[SetAppDomainManagerType Method](../../../../docs/framework/unmanaged-api/hosting/iclrdomainmanager-setappdomainmanagertype-method.md)|Specifies the type, derived from the class, of the application domain manager that will be used to initialize the default application domain.| |[SetPropertiesForDefaultAppDomain Method](../../../../docs/framework/unmanaged-api/hosting/iclrdomainmanager-setpropertiesfordefaultappdomain-method.md)|Sets properties that will be used to initialize the default application domain.| ## Remarks diff --git a/docs/framework/unmanaged-api/hosting/iclrdomainmanager-setappdomainmanagertype-method.md b/docs/framework/unmanaged-api/hosting/iclrdomainmanager-setappdomainmanagertype-method.md index 7dd68c0b1ccb1..60302b17d1ca3 100644 --- a/docs/framework/unmanaged-api/hosting/iclrdomainmanager-setappdomainmanagertype-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrdomainmanager-setappdomainmanagertype-method.md @@ -29,7 +29,7 @@ ms.author: "ronpet" manager: "wpickett" --- # ICLRDomainManager::SetAppDomainManagerType Method -Specifies the type, derived from the class, of the application domain manager that will be used to initialize the default application domain. +Specifies the type, derived from the class, of the application domain manager that will be used to initialize the default application domain. ## Syntax @@ -60,7 +60,7 @@ HRESULT SetAppDomainManagerType( |HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| ## Remarks - Currently, the only defined value for `dwInitializeDomainFlags` is `eInitializeNewDomainFlags_NoSecurityChanges`, which tells the common language runtime (CLR) that the application domain manager will not modify security settings during the execution of the method. This allows the CLR to optimize the loading of assemblies that have the conditional (APTCA) attribute. This can result in a significant improvement in startup time if the transitive closure of this set of assemblies is large. + Currently, the only defined value for `dwInitializeDomainFlags` is `eInitializeNewDomainFlags_NoSecurityChanges`, which tells the common language runtime (CLR) that the application domain manager will not modify security settings during the execution of the method. This allows the CLR to optimize the loading of assemblies that have the conditional (APTCA) attribute. This can result in a significant improvement in startup time if the transitive closure of this set of assemblies is large. > [!IMPORTANT] > If the host specifies `eInitializeNewDomainFlags_NoSecurityChanges` for the application domain manager, an is thrown if any attempt is made to modify the security of the application domain. diff --git a/docs/framework/unmanaged-api/hosting/iclrdomainmanager-setpropertiesfordefaultappdomain-method.md b/docs/framework/unmanaged-api/hosting/iclrdomainmanager-setpropertiesfordefaultappdomain-method.md index fdd06f81b8a8a..7a08d684067fb 100644 --- a/docs/framework/unmanaged-api/hosting/iclrdomainmanager-setpropertiesfordefaultappdomain-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrdomainmanager-setpropertiesfordefaultappdomain-method.md @@ -60,7 +60,7 @@ HRESULT SetPropertiesForDefaultAppDomain( |HRESULT_FROM_WIN32(ERROR_UNKNOWN_PROPERTY)|`pwszPropertyNames` includes a property name that is not recognized by this method.| ## Remarks - The property value for "PARTIAL_TRUST_VISIBLE_ASSEMBLIES" is a list of assemblies that have the conditional (APTCA) attribute with the flag, which are to be made visible to partially trusted callers in the default application domain. + The property value for "PARTIAL_TRUST_VISIBLE_ASSEMBLIES" is a list of assemblies that have the conditional (APTCA) attribute with the flag, which are to be made visible to partially trusted callers in the default application domain. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/iclrmetahostpolicy-getrequestedruntime-method.md b/docs/framework/unmanaged-api/hosting/iclrmetahostpolicy-getrequestedruntime-method.md index c987dc706ebfb..89f0117553046 100644 --- a/docs/framework/unmanaged-api/hosting/iclrmetahostpolicy-getrequestedruntime-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrmetahostpolicy-getrequestedruntime-method.md @@ -55,7 +55,7 @@ HRESULT GetRequestedRuntime( |----------|-----------------| |`dwPolicyFlags`|[in] Required. Specifies a member of the [METAHOST_POLICY_FLAGS](../../../../docs/framework/unmanaged-api/hosting/metahost-policy-flags-enumeration.md) enumeration, representing a binding policy, and any number of modifiers. The only policy that is currently available is [METAHOST_POLICY_HIGHCOMPAT](../../../../docs/framework/unmanaged-api/hosting/metahost-policy-flags-enumeration.md).

Modifiers include [METAHOST_POLICY_EMULATE_EXE_LAUNCH](../../../../docs/framework/unmanaged-api/hosting/metahost-policy-flags-enumeration.md), [METAHOST_POLICY_APPLY_UPGRADE_POLICY](../../../../docs/framework/unmanaged-api/hosting/metahost-policy-flags-enumeration.md), [METAHOST_POLICY_SHOW_ERROR_DIALOG](../../../../docs/framework/unmanaged-api/hosting/metahost-policy-flags-enumeration.md), [METAHOST_POLICY_USE_PROCESS_IMAGE_PATH](../../../../docs/framework/unmanaged-api/hosting/metahost-policy-flags-enumeration.md), and [METAHOST_POLICY_ENSURE_SKU_SUPPORTED](../../../../docs/framework/unmanaged-api/hosting/metahost-policy-flags-enumeration.md).| |`pwzBinary`|[in] Optional. Specifies the assembly file path.| -|`pCfgStream`|[in] Optional. Specifies the configuration file as a .| +|`pCfgStream`|[in] Optional. Specifies the configuration file as a .| |`pwzVersion`|[in, out] Optional. Specifies or returns the preferred CLR version to be loaded.| |`pcchVersion`|[in, out] Required. Specifies the expected size of `pwzVersion` as input, to avoid buffer overruns. If `pwzVersion` is null, `pcchVersion` contains the expected size of `pwzVersion` when `GetRequestedRuntime` returns, to allow pre-allocation; otherwise, `pcchVersion` contains the number of characters written to `pwzVersion`.| |`pwzImageVersion`|[out] Optional. When `GetRequestedRuntime` returns, contains the CLR version corresponding to the [ICLRRuntimeInfo](../../../../docs/framework/unmanaged-api/hosting/iclrruntimeinfo-interface.md) interface that is returned.| diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md index a80a7d38070b4..c96b7f50a7fd6 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md @@ -31,7 +31,7 @@ ms.author: "ronpet" manager: "wpickett" --- # ICorRuntimeHost::CreateDomain Method -Creates an application domain. The caller receives an interface pointer of type to an instance of type . +Creates an application domain. The caller receives an interface pointer of type to an instance of type . ## Syntax @@ -51,7 +51,7 @@ HRESULT CreateDomain ( [in] An optional array of pointers to `IIdentity` instances that represent evidence mapped through security policy to establish a permission set. An `IIdentity` object can be obtained by calling the [CreateEvidence](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createevidence-method.md) method. `pAppDomain` - [out] An interface pointer of type to an instance of that can be used to further control the domain. + [out] An interface pointer of type to an instance of that can be used to further control the domain. ## Return Value diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md index da83cf7a1ebcb..9f99aab6ac4b4 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md @@ -31,7 +31,7 @@ ms.author: "ronpet" manager: "wpickett" --- # ICorRuntimeHost::CreateDomainEx Method -Creates an application domain. The caller receives an interface pointer, of type , to an instance of type . This method allows the caller to pass an IAppDomainSetup instance to configure additional features of the returned instance. +Creates an application domain. The caller receives an interface pointer, of type , to an instance of type . This method allows the caller to pass an IAppDomainSetup instance to configure additional features of the returned instance. ## Syntax @@ -55,7 +55,7 @@ HRESULT CreateDomainEx ( [in] An optional array of pointers to `IIdentity` instances that represent evidence mapped through security policy to establish a permission set. An `IIdentity` object can be obtained by calling the [CreateEvidence](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createevidence-method.md) method. `pAppDomain` - [out] An interface pointer of type to an instance of that can be used to further control the domain. + [out] An interface pointer of type to an instance of that can be used to further control the domain. ## Return Value @@ -81,6 +81,6 @@ HRESULT CreateDomainEx ( ## See Also - + [CreateDomain Method](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md) [ICorRuntimeHost Interface](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainsetup-method.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainsetup-method.md index 745111bc49cab..5cfc713c53234 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainsetup-method.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainsetup-method.md @@ -31,7 +31,7 @@ ms.author: "ronpet" manager: "wpickett" --- # ICorRuntimeHost::CreateDomainSetup Method -Gets an interface pointer of type IAppDomainSetup to an instance. `IAppDomainSetup` provides methods to configure aspects of an application domain before it is created. +Gets an interface pointer of type IAppDomainSetup to an instance. `IAppDomainSetup` provides methods to configure aspects of an application domain before it is created. ## Syntax @@ -43,7 +43,7 @@ HRESULT CreateDomainSetup ( #### Parameters `pAppDomainSetup` - [out] An interface pointer to an instance. This parameter is typed as `IUnknown`, so callers should generally call `QueryInterface` on this pointer to obtain an interface pointer of type `IAppDomainSetup`. + [out] An interface pointer to an instance. This parameter is typed as `IUnknown`, so callers should generally call `QueryInterface` on this pointer to obtain an interface pointer of type `IAppDomainSetup`. ## Return Value @@ -70,5 +70,5 @@ HRESULT CreateDomainSetup ( - + [ICorRuntimeHost Interface](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-createevidence-method.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-createevidence-method.md index 472433b0b1ec7..710d06929746d 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-createevidence-method.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-createevidence-method.md @@ -31,7 +31,7 @@ ms.author: "ronpet" manager: "wpickett" --- # ICorRuntimeHost::CreateEvidence Method -Gets an interface pointer of type , which allows the host to create security evidence to pass to the [CreateDomain](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md) or [CreateDomainEx](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md) method. +Gets an interface pointer of type , which allows the host to create security evidence to pass to the [CreateDomain](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md) or [CreateDomainEx](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md) method. ## Syntax @@ -43,7 +43,7 @@ HRESULT CreateEvidence ( #### Parameters `pEvidence` - [out] A interface pointer to an instance used to create security evidence. This pointer is typed `IUnknown`, so callers should typically call `QueryInterface` on this interface to obtain a pointer to an . + [out] A interface pointer to an instance used to create security evidence. This pointer is typed `IUnknown`, so callers should typically call `QueryInterface` on this interface to obtain a pointer to an . ## Return Value diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-currentdomain-method.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-currentdomain-method.md index 8fdd5071d72dd..6c1bab28794e7 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-currentdomain-method.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-currentdomain-method.md @@ -31,7 +31,7 @@ ms.author: "ronpet" manager: "wpickett" --- # ICorRuntimeHost::CurrentDomain Method -Gets an interface pointer of type that represents the domain loaded on the current thread. +Gets an interface pointer of type that represents the domain loaded on the current thread. ## Syntax @@ -43,7 +43,7 @@ HRESULT CurrentDomain ( #### Parameters `pAppDomain` - [out] A pointer of type that represents the thread's current application domain. This pointer is typed `IUnknown`, so callers should generally call `QueryInterface` to obtain a pointer of type . + [out] A pointer of type that represents the thread's current application domain. This pointer is typed `IUnknown`, so callers should generally call `QueryInterface` to obtain a pointer of type . ## Return Value diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-getdefaultdomain-method.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-getdefaultdomain-method.md index 73a291f919b19..81c9234f28f88 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-getdefaultdomain-method.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-getdefaultdomain-method.md @@ -31,7 +31,7 @@ ms.author: "ronpet" manager: "wpickett" --- # ICorRuntimeHost::GetDefaultDomain Method -Gets an interface pointer of type that represents the default domain for the current process. +Gets an interface pointer of type that represents the default domain for the current process. ## Syntax @@ -43,9 +43,9 @@ HRESULT GetDefaultDomain ( #### Parameters `pAppDomain` - [out] An interface pointer of type to the instance that represents the default application domain for the process. + [out] An interface pointer of type to the instance that represents the default application domain for the process. - This pointer is typed `IUnknown`, so callers should generally call `QueryInterface` to obtain an interface pointer of type . + This pointer is typed `IUnknown`, so callers should generally call `QueryInterface` to obtain an interface pointer of type . ## Return Value diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-interface.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-interface.md index d1f1cadaa4eee..1ff1a22322e05 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-interface.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-interface.md @@ -39,7 +39,7 @@ Provides methods that enable the host to start and stop the common language runt |Method|Description| |------------|-----------------| |[CloseEnum Method](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-closeenum-method.md)|Resets a domain enumerator back to the beginning of the domain list.| -|[CreateDomain Method](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md)|Creates an application domain. The caller receives an interface pointer of type to an instance of type .| +|[CreateDomain Method](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md)|Creates an application domain. The caller receives an interface pointer of type to an instance of type .| |[CreateDomainEx Method](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md)|Creates an application domain. This method allows the caller to pass an IAppDomainSetup instance to configure additional features of the returned instance.| |[CreateDomainSetup Method](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainsetup-method.md)|Gets an interface pointer of type `IAppDomainSetup` to an instance. `IAppDomainSetup` provides methods to configure aspects of an application domain before it is created.| |[CreateEvidence Method](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createevidence-method.md)|Gets an interface pointer of type , which allows the host to create security evidence to pass to [CreateDomain](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomain-method.md) or [CreateDomainEx](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-createdomainex-method.md).| diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-nextdomain-method.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-nextdomain-method.md index 7425040b5bba7..f4e2c5ce65738 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-nextdomain-method.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-nextdomain-method.md @@ -47,7 +47,7 @@ HRESULT NextDomain ( [in] The enumerator that was obtained through a call to [EnumDomains](../../../../docs/framework/unmanaged-api/hosting/icorruntimehost-enumdomains-method.md). `pAppDomain` - [out] An interface pointer to the type that represents the next domain in the enumeration, or null, if no more domains exist. + [out] An interface pointer to the type that represents the next domain in the enumeration, or null, if no more domains exist. ## Return Value diff --git a/docs/framework/unmanaged-api/hosting/icorruntimehost-unloaddomain-method.md b/docs/framework/unmanaged-api/hosting/icorruntimehost-unloaddomain-method.md index 8886a53d9c714..577833e488eed 100644 --- a/docs/framework/unmanaged-api/hosting/icorruntimehost-unloaddomain-method.md +++ b/docs/framework/unmanaged-api/hosting/icorruntimehost-unloaddomain-method.md @@ -43,7 +43,7 @@ HRESULT UnloadDomain ( #### Parameters `pAppDomain` - [in] A pointer of type that represents the domain to be unloaded. + [in] A pointer of type that represents the domain to be unloaded. ## Return Value diff --git a/docs/framework/unmanaged-api/hosting/ihostmemorymanager-getmemoryload-method.md b/docs/framework/unmanaged-api/hosting/ihostmemorymanager-getmemoryload-method.md index b1d674d5b50b9..d32b4c08563ab 100644 --- a/docs/framework/unmanaged-api/hosting/ihostmemorymanager-getmemoryload-method.md +++ b/docs/framework/unmanaged-api/hosting/ihostmemorymanager-getmemoryload-method.md @@ -75,5 +75,5 @@ HRESULT GetMemoryLoad ( **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] ## See Also - + [IHostMemoryManager Interface](../../../../docs/framework/unmanaged-api/hosting/ihostmemorymanager-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-setsecuritycontext-method.md b/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-setsecuritycontext-method.md index 85fb3aae68555..33f1d9e62833c 100644 --- a/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-setsecuritycontext-method.md +++ b/docs/framework/unmanaged-api/hosting/ihostsecuritymanager-setsecuritycontext-method.md @@ -63,7 +63,7 @@ HRESULT SetSecurityContext ( ## Remarks The CLR calls `SetSecurityContext` in several scenarios. Before it executes class and module constructors and finalizers, the CLR calls `SetSecurityContext` to protect the host from execution failures. It then resets the security context to its original state after execution of the constructor or finalizer, by using another call to `SetSecurityContext`. A similar pattern occurs with I/O completion. If the host implements [IHostIoCompletionManager](../../../../docs/framework/unmanaged-api/hosting/ihostiocompletionmanager-interface.md), the CLR calls `SetSecurityContext` after the host calls [ICLRIoCompletionManager::OnComplete](../../../../docs/framework/unmanaged-api/hosting/iclriocompletionmanager-oncomplete-method.md). - At asynchronous points in worker threads, the CLR calls `SetSecurityContext` within or within [IHostThreadPoolManager::QueueUserWorkItem](../../../../docs/framework/unmanaged-api/hosting/ihostthreadpoolmanager-queueuserworkitem-method.md), depending on whether the host or the CLR is implementing the thread pool. + At asynchronous points in worker threads, the CLR calls `SetSecurityContext` within or within [IHostThreadPoolManager::QueueUserWorkItem](../../../../docs/framework/unmanaged-api/hosting/ihostthreadpoolmanager-queueuserworkitem-method.md), depending on whether the host or the CLR is implementing the thread pool. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). @@ -75,7 +75,7 @@ HRESULT SetSecurityContext ( **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] ## See Also - + [EContextType Enumeration](../../../../docs/framework/unmanaged-api/hosting/econtexttype-enumeration.md) [ICLRIoCompletionManager Interface](../../../../docs/framework/unmanaged-api/hosting/iclriocompletionmanager-interface.md) [IHostIoCompletionManager Interface](../../../../docs/framework/unmanaged-api/hosting/ihostiocompletionmanager-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/ihostsyncmanager-createmonitorevent-method.md b/docs/framework/unmanaged-api/hosting/ihostsyncmanager-createmonitorevent-method.md index 641231418cc4d..9f63fe83b77a8 100644 --- a/docs/framework/unmanaged-api/hosting/ihostsyncmanager-createmonitorevent-method.md +++ b/docs/framework/unmanaged-api/hosting/ihostsyncmanager-createmonitorevent-method.md @@ -62,7 +62,7 @@ HRESULT CreateMonitorEvent ( |E_OUTOFMEMORY|Not enough memory was available to create the requested event object.| ## Remarks - `CreateMonitorEvent` returns an `IHostAutoEvent` that the CLR uses in its implementation of the managed type. This method mirrors the Win32 `CreateEvent` function, with a value of `false` specified for the `bManualReset` parameter. + `CreateMonitorEvent` returns an `IHostAutoEvent` that the CLR uses in its implementation of the managed type. This method mirrors the Win32 `CreateEvent` function, with a value of `false` specified for the `bManualReset` parameter. The host can use the cookie to determine which task is waiting on the monitor by calling the [ICLRSyncManager::GetMonitorOwner](../../../../docs/framework/unmanaged-api/hosting/iclrsyncmanager-getmonitorowner-method.md) method. diff --git a/docs/framework/unmanaged-api/hosting/ihosttask-alert-method.md b/docs/framework/unmanaged-api/hosting/ihosttask-alert-method.md index ef4395c2b68de..0b0d8633d27cf 100644 --- a/docs/framework/unmanaged-api/hosting/ihosttask-alert-method.md +++ b/docs/framework/unmanaged-api/hosting/ihosttask-alert-method.md @@ -51,7 +51,7 @@ HRESULT Alert (); |E_FAIL|An unknown catastrophic failure occurred. When a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to hosting methods return HOST_E_CLRNOTAVAILABLE.| ## Remarks - The CLR calls the `Alert` method when is called from user code, or when the associated with the current shuts down. The host must return immediately, because the call is made asynchronously. If the host cannot alert the task immediately, it must wake up the next time it enters a state in which it can be alerted. + The CLR calls the `Alert` method when is called from user code, or when the associated with the current shuts down. The host must return immediately, because the call is made asynchronously. If the host cannot alert the task immediately, it must wake up the next time it enters a state in which it can be alerted. > [!NOTE] > `Alert` affects only those tasks to which the runtime has passed a [WAIT_OPTION](../../../../docs/framework/unmanaged-api/hosting/wait-option-enumeration.md) value of WAIT_ALERTABLE to methods such as [Join](../../../../docs/framework/unmanaged-api/hosting/ihosttask-join-method.md). diff --git a/docs/framework/unmanaged-api/hosting/ihosttask-setpriority-method.md b/docs/framework/unmanaged-api/hosting/ihosttask-setpriority-method.md index c80c7370b9e9a..3ff1c911ae8cb 100644 --- a/docs/framework/unmanaged-api/hosting/ihosttask-setpriority-method.md +++ b/docs/framework/unmanaged-api/hosting/ihosttask-setpriority-method.md @@ -73,7 +73,7 @@ HRESULT SetPriority ( - THREAD_PRIORITY_TIME_CRITICAL - The CLR calls `SetPriority` when the value of the is modified by user code. A host can define its own algorithms for thread priority assignment, and is free to ignore this request. + The CLR calls `SetPriority` when the value of the is modified by user code. A host can define its own algorithms for thread priority assignment, and is free to ignore this request. > [!NOTE] > `SetPriority` does not report whether the thread priority level was changed. Call [IHostTask::GetPriority](../../../../docs/framework/unmanaged-api/hosting/ihosttask-getpriority-method.md) to determine the value of the task's thread priority level. diff --git a/docs/framework/unmanaged-api/hosting/ihosttaskmanager-beginthreadaffinity-method.md b/docs/framework/unmanaged-api/hosting/ihosttaskmanager-beginthreadaffinity-method.md index da8283042c154..507b01cb41c75 100644 --- a/docs/framework/unmanaged-api/hosting/ihosttaskmanager-beginthreadaffinity-method.md +++ b/docs/framework/unmanaged-api/hosting/ihosttaskmanager-beginthreadaffinity-method.md @@ -51,7 +51,7 @@ HRESULT BeginThreadAffinity (); |E_FAIL|An unknown catastrophic failure occurred. When a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to hosting methods return HOST_E_CLRNOTAVAILABLE.| ## Remarks - The CLR typically calls `IHostTaskManager::BeginThreadAffinity` in the context of a call to . The current task must not be rescheduled until a corresponding call is made to [IHostTaskManager::EndThreadAffinity](../../../../docs/framework/unmanaged-api/hosting/ihosttaskmanager-endthreadaffinity-method.md). Tasks can be switched out, but when they are switched back in, they must be assigned to the same operating system thread from which they were switched out. Nested calls to `BeginThreadAffinity` have no effect, because the call refers to the current task. + The CLR typically calls `IHostTaskManager::BeginThreadAffinity` in the context of a call to . The current task must not be rescheduled until a corresponding call is made to [IHostTaskManager::EndThreadAffinity](../../../../docs/framework/unmanaged-api/hosting/ihosttaskmanager-endthreadaffinity-method.md). Tasks can be switched out, but when they are switched back in, they must be assigned to the same operating system thread from which they were switched out. Nested calls to `BeginThreadAffinity` have no effect, because the call refers to the current task. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/ihosttaskmanager-setlocale-method.md b/docs/framework/unmanaged-api/hosting/ihosttaskmanager-setlocale-method.md index 9135e40c10532..5c3a713c43bda 100644 --- a/docs/framework/unmanaged-api/hosting/ihosttaskmanager-setlocale-method.md +++ b/docs/framework/unmanaged-api/hosting/ihosttaskmanager-setlocale-method.md @@ -58,7 +58,7 @@ HRESULT SetLocale ( |E_NOTIMPL|The host does not allow managed user code to modify the locale.| ## Remarks - The runtime calls `SetLocale` when the value of the property is changed by managed code. This method provides an opportunity for the host to execute any mechanisms it might have for synchronization of locales. If a host does not allow the locale to be changed from managed code, or does not implement a mechanism to synchronize locales, it should return E_NOTIMPL from this method. + The runtime calls `SetLocale` when the value of the property is changed by managed code. This method provides an opportunity for the host to execute any mechanisms it might have for synchronization of locales. If a host does not allow the locale to be changed from managed code, or does not implement a mechanism to synchronize locales, it should return E_NOTIMPL from this method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/ihosttaskmanager-setuilocale-method.md b/docs/framework/unmanaged-api/hosting/ihosttaskmanager-setuilocale-method.md index 126738daf1130..8d14cd29046d2 100644 --- a/docs/framework/unmanaged-api/hosting/ihosttaskmanager-setuilocale-method.md +++ b/docs/framework/unmanaged-api/hosting/ihosttaskmanager-setuilocale-method.md @@ -58,7 +58,7 @@ HRESULT SetUILocale ( |E_NOTIMPL|The host does not allow managed user code to change the UI culture.| ## Remarks - The runtime calls `SetUILocale` when the value of the property is changed by managed code. This method provides an opportunity for the host to execute any mechanisms it might have for synchronization of locales. If a host does not allow the UI locale to be changed from managed code, or does not implement a mechanism to synchronize locales, it should return E_NOTIMPL from this method. + The runtime calls `SetUILocale` when the value of the property is changed by managed code. This method provides an opportunity for the host to execute any mechanisms it might have for synchronization of locales. If a host does not allow the UI locale to be changed from managed code, or does not implement a mechanism to synchronize locales, it should return E_NOTIMPL from this method. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/ihosttaskmanager-sleep-method.md b/docs/framework/unmanaged-api/hosting/ihosttaskmanager-sleep-method.md index a79d065e72fbc..ea719c7615b34 100644 --- a/docs/framework/unmanaged-api/hosting/ihosttaskmanager-sleep-method.md +++ b/docs/framework/unmanaged-api/hosting/ihosttaskmanager-sleep-method.md @@ -61,7 +61,7 @@ HRESULT Sleep ( |E_FAIL|An unknown catastrophic failure occurred. When a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to hosting methods return HOST_E_CLRNOTAVAILABLE.| ## Remarks - The CLR typically calls `IHostTaskManager::Sleep` when is called from user code. + The CLR typically calls `IHostTaskManager::Sleep` when is called from user code. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/hosting/loadstringrcex-function.md b/docs/framework/unmanaged-api/hosting/loadstringrcex-function.md index e1c528290c657..cd95cefb08414 100644 --- a/docs/framework/unmanaged-api/hosting/loadstringrcex-function.md +++ b/docs/framework/unmanaged-api/hosting/loadstringrcex-function.md @@ -87,6 +87,6 @@ HRESULT LoadStringRCEx ( **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] ## See Also - + [LoadStringRC Function](../../../../docs/framework/unmanaged-api/hosting/loadstringrc-function.md) [Deprecated CLR Hosting Functions](../../../../docs/framework/unmanaged-api/hosting/deprecated-clr-hosting-functions.md) diff --git a/docs/framework/unmanaged-api/hosting/startup-flags-enumeration.md b/docs/framework/unmanaged-api/hosting/startup-flags-enumeration.md index 3e58fb48392f9..6dcdb45069baa 100644 --- a/docs/framework/unmanaged-api/hosting/startup-flags-enumeration.md +++ b/docs/framework/unmanaged-api/hosting/startup-flags-enumeration.md @@ -78,7 +78,7 @@ typedef enum { |`STARTUP_ALWAYSFLOW_IMPERSONATION`|Specifies that managed impersonations and impersonations achieved through platform invoke will flow across asynchronous points. By default, only managed impersonations will flow across asynchronous points.| |`STARTUP_TRIM_GC_COMMIT`|Specifies that garbage collection will use less committed space when system memory is low. See `gcTrimCommitOnLowMemory` in [Optimization for Shared Web Hosting](../../../../docs/standard/garbage-collection/optimization-for-shared-web-hosting.md).| |`STARTUP_ETW`|Specifies that event tracing for Windows (ETW) is enabled for common language runtime events. Beginning with Windows Vista, event tracing is always enabled, so this flag has no effect. See [Controlling .NET Framework Logging](../../../../docs/framework/performance/controlling-logging.md).| -|`STARTUP_ARM`|Specifies that application domain resource monitoring is enabled. See the property and [\ Element](../../../../docs/framework/configure-apps/file-schema/runtime/appdomainresourcemonitoring-element.md).| +|`STARTUP_ARM`|Specifies that application domain resource monitoring is enabled. See the property and [\ Element](../../../../docs/framework/configure-apps/file-schema/runtime/appdomainresourcemonitoring-element.md).| ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/metadata/corattributetargets-enumeration.md b/docs/framework/unmanaged-api/metadata/corattributetargets-enumeration.md index 1791e07a48db4..81dcec579bdca 100644 --- a/docs/framework/unmanaged-api/metadata/corattributetargets-enumeration.md +++ b/docs/framework/unmanaged-api/metadata/corattributetargets-enumeration.md @@ -90,7 +90,7 @@ typedef enum CorAttributeTargets ## Remarks The `CorAttributeTargets` enumeration values can be combined with a bitwise OR operation to get the preferred combination. - The `CorAttributeTargets` parallels the managed enumeration. + The `CorAttributeTargets` parallels the managed enumeration. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/metadata/imetadataimport-enummethodsemantics-method.md b/docs/framework/unmanaged-api/metadata/imetadataimport-enummethodsemantics-method.md index add9202c79491..d02292436033f 100644 --- a/docs/framework/unmanaged-api/metadata/imetadataimport-enummethodsemantics-method.md +++ b/docs/framework/unmanaged-api/metadata/imetadataimport-enummethodsemantics-method.md @@ -69,7 +69,7 @@ HRESULT EnumMethodSemantics ( |`S_FALSE`|There are no events or properties to enumerate. In that case, `pcEventProp` is zero.| ## Remarks - Many common language runtime types define *Property*`Changed` events and `On`*Property*`Changed` methods related to their properties. For example, the type defines a property, a event, and an method. The set accessor method of the property calls method, which in turn raises the event. You would call `EnumMethodSemantics` using the MethodDef for to get references to the property and the event. + Many common language runtime types define *Property*`Changed` events and `On`*Property*`Changed` methods related to their properties. For example, the type defines a property, a event, and an method. The set accessor method of the property calls method, which in turn raises the event. You would call `EnumMethodSemantics` using the MethodDef for to get references to the property and the event. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/metadata/imetadataimport-getpermissionsetprops-method.md b/docs/framework/unmanaged-api/metadata/imetadataimport-getpermissionsetprops-method.md index fed6afa7e6044..3ceb528a14ace 100644 --- a/docs/framework/unmanaged-api/metadata/imetadataimport-getpermissionsetprops-method.md +++ b/docs/framework/unmanaged-api/metadata/imetadataimport-getpermissionsetprops-method.md @@ -31,7 +31,7 @@ ms.author: "mairaw" manager: "wpickett" --- # IMetaDataImport::GetPermissionSetProps Method -Gets the metadata associated with the represented by the specified Permission token. +Gets the metadata associated with the represented by the specified Permission token. ## Syntax diff --git a/docs/framework/unmanaged-api/metadata/metadata-interfaces.md b/docs/framework/unmanaged-api/metadata/metadata-interfaces.md index 55785ddaffece..d7dbc9e2b0bfe 100644 --- a/docs/framework/unmanaged-api/metadata/metadata-interfaces.md +++ b/docs/framework/unmanaged-api/metadata/metadata-interfaces.md @@ -53,7 +53,7 @@ This section describes the unmanaged interfaces that provide access to the metad Provides methods to create, modify and store metadata about the assembly in the currently defined scope. [IMetaDataEmit2 Interface](../../../../docs/framework/unmanaged-api/metadata/imetadataemit2-interface.md) - Provides methods for defining and modifying the metadata signatures of methods and constructors with parameters of type . + Provides methods for defining and modifying the metadata signatures of methods and constructors with parameters of type . [IMetaDataError Interface](../../../../docs/framework/unmanaged-api/metadata/imetadataerror-interface.md) Provides a callback mechanism for reporting errors during the resolution of the metadata signature for an assembly. diff --git a/docs/framework/unmanaged-api/profiling/clr-profilers-and-windows-store-apps.md b/docs/framework/unmanaged-api/profiling/clr-profilers-and-windows-store-apps.md index 739d0cc104b51..7313ecc5b3f3f 100644 --- a/docs/framework/unmanaged-api/profiling/clr-profilers-and-windows-store-apps.md +++ b/docs/framework/unmanaged-api/profiling/clr-profilers-and-windows-store-apps.md @@ -403,7 +403,7 @@ GetAppContainerFolderPath(acSid, out acDir); ### ConditionalWeakTableReferences - Starting with the .NET Framework 4.5, there is a new GC callback, [ConditionalWeakTableElementReferences](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback5-conditionalweaktableelementreferences-method.md), which gives the profiler more complete information about *dependent handles*. These handles effectively add a reference from a source object to a target object for the purpose of GC lifetime management. Dependent handles are nothing new, and developers who program in managed code have been able to create their own dependent handles by using the class even before Windows 8 and the .NET Framework 4.5. + Starting with the .NET Framework 4.5, there is a new GC callback, [ConditionalWeakTableElementReferences](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback5-conditionalweaktableelementreferences-method.md), which gives the profiler more complete information about *dependent handles*. These handles effectively add a reference from a source object to a target object for the purpose of GC lifetime management. Dependent handles are nothing new, and developers who program in managed code have been able to create their own dependent handles by using the class even before Windows 8 and the .NET Framework 4.5. However, managed XAML Windows Store apps now make heavy use of dependent handles. In particular, the CLR uses them to aid with managing reference cycles between managed objects and unmanaged Windows Runtime objects. This means that it’s more important now than ever for memory profilers to be informed of these dependent handles so that they can be visualized along with the rest of the edges in the heap graph. Your Profiler DLL should use [RootReferences2](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback2-rootreferences2-method.md), [ObjectReferences](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback-objectreferences-method.md), and [ConditionalWeakTableElementReferences](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback5-conditionalweaktableelementreferences-method.md) together to form a complete view of the heap graph. diff --git a/docs/framework/unmanaged-api/profiling/cor-prf-module-flags-enumeration.md b/docs/framework/unmanaged-api/profiling/cor-prf-module-flags-enumeration.md index 021520793cf65..8570811e41913 100644 --- a/docs/framework/unmanaged-api/profiling/cor-prf-module-flags-enumeration.md +++ b/docs/framework/unmanaged-api/profiling/cor-prf-module-flags-enumeration.md @@ -53,9 +53,9 @@ typedef enum |------------|-----------------| |COR_PRF_MODULE_DISK|The module was loaded from disk.| |COR_PRF_MODULE_NGEN|The module was generated by the Native Image Generator (Ngen.exe).| -|COR_PRF_MODULE_DYNAMIC|The module was created by methods in the namespace.| +|COR_PRF_MODULE_DYNAMIC|The module was created by methods in the namespace.| |COR_PRF_MODULE_COLLECTIBLE|The module's lifetime is managed by the garbage collector.| -|COR_PRF_MODULE_RESOURCE|The module contains no metadata and is used strictly as a resource. The managed equivalent of this bit is the method.| +|COR_PRF_MODULE_RESOURCE|The module contains no metadata and is used strictly as a resource. The managed equivalent of this bit is the method.| |COR_PRF_MODULE_FLAT_LAYOUT|The module's layout in memory is flat, not mapped. If a module has this bit set, profilers that read information directly from the portable executable (PE) file header will have to be careful when interpreting relative virtual addresses (RVAs) in the header.| |COR_PRF_MODULE_WINDOWS_RUNTIME|The Windows Runtime content type flag is set in the metadata for this module's assembly. This is the case for all Windows Metadata (.winmd) modules.| diff --git a/docs/framework/unmanaged-api/profiling/icorprofilercallback7-moduleinmemorysymbolsupdated-method.md b/docs/framework/unmanaged-api/profiling/icorprofilercallback7-moduleinmemorysymbolsupdated-method.md index fe774ab4ef6dc..4d020618726a6 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilercallback7-moduleinmemorysymbolsupdated-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilercallback7-moduleinmemorysymbolsupdated-method.md @@ -47,7 +47,7 @@ HRESULT ModuleInMemorySymbolsUpdated( > [!NOTE] > This event is not currently raised for symbols implicitly created or modified via APIs. - Even when symbols are provided up front in a call to one of the overloads of the managed methods that includes a `rawSymbolStore` argument to specify the symbols for the assembly, the runtime may not actually associate the symbolic data with the module until after the [ModuleLoadFinished](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback-moduleloadfinished-method.md) callback has occurred. This event provides a later opportunity to collect symbols for such modules. + Even when symbols are provided up front in a call to one of the overloads of the managed methods that includes a `rawSymbolStore` argument to specify the symbols for the assembly, the runtime may not actually associate the symbolic data with the module until after the [ModuleLoadFinished](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback-moduleloadfinished-method.md) callback has occurred. This event provides a later opportunity to collect symbols for such modules. ## Requirements **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-getmoduleinfo2-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-getmoduleinfo2-method.md index 4e0b4170be47c..b6bbe27272447 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-getmoduleinfo2-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-getmoduleinfo2-method.md @@ -70,7 +70,7 @@ HRESULT GetModuleInfo2( [out] A bitmask of values from the [COR_PRF_MODULE_FLAGS](../../../../docs/framework/unmanaged-api/profiling/cor-prf-module-flags-enumeration.md) enumeration that specify the properties of the module. ## Remarks - For dynamic modules, the `szName` parameter is the metadata name of the module, and the base address is 0 (zero). The metadata name is the value in the Name column from the Module table inside metadata. This is also exposed as the property to managed code, and as the `szName` parameter of the [IMetaDataImport::GetScopeProps](../../../../docs/framework/unmanaged-api/metadata/imetadataimport-getscopeprops-method.md) method to unmanaged metadata client code. + For dynamic modules, the `szName` parameter is the metadata name of the module, and the base address is 0 (zero). The metadata name is the value in the Name column from the Module table inside metadata. This is also exposed as the property to managed code, and as the `szName` parameter of the [IMetaDataImport::GetScopeProps](../../../../docs/framework/unmanaged-api/metadata/imetadataimport-getscopeprops-method.md) method to unmanaged metadata client code. Although the `GetModuleInfo2` method may be called as soon as the module's ID exists, the ID of the parent assembly will not be available until the profiler receives the [ICorProfilerCallback::ModuleAttachedToAssembly](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback-moduleattachedtoassembly-method.md) callback. diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo7-getinmemorysymbolslength-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo7-getinmemorysymbolslength-method.md index b2971c4bcfe05..e46342d1d7dbe 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo7-getinmemorysymbolslength-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo7-getinmemorysymbolslength-method.md @@ -48,7 +48,7 @@ HRESULT GetInMemorySymbolsLength( ## Return Value The method returns `S_OK` if the length of the memory stream can be determined, even if it is zero (0). - The method returns `CORPROF_E_MODULE_IS_DYNAMIC` if the method was created using . + The method returns `CORPROF_E_MODULE_IS_DYNAMIC` if the method was created using . ## Remarks If the module has in-memory symbols, the length of the stream is placed in `pCountSymbolBytes`. If the module doesn't have in-memory symbols, `*pCountSymbolBytes = 0`. diff --git a/docs/framework/wcf/controlling-resource-consumption-and-improving-performance.md b/docs/framework/wcf/controlling-resource-consumption-and-improving-performance.md index 018daa47c9476..ac3e915b825ce 100644 --- a/docs/framework/wcf/controlling-resource-consumption-and-improving-performance.md +++ b/docs/framework/wcf/controlling-resource-consumption-and-improving-performance.md @@ -21,11 +21,11 @@ This topic describes various properties in different areas of the [!INCLUDE[indi ## Properties that Constrain Resource Consumption in WCF [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applies constraints on certain types of processes for either security or performance purposes. These constraints come in two main forms, either quotas and throttles. *Quotas* are limits that when reached or exceeded trigger an immediate exception at some point in the system. *Throttles* are limits that do not immediately cause an exception to be thrown. Instead, when a throttle limit is reached, processing continues but within the limits set by that throttle value. This limited processing might trigger an exception elsewhere, but this depends upon the application. - In addition to the distinction between quotas and throttles, some constraining properties are located at the serialization level, some at the transport level, and some at the application level. For example, the quota , which is implemented by all system-supplied transport binding elements, is set to 65,536 bytes by default to hinder malicious clients from engaging in denial-of-service attacks against a service by causing excessive memory consumption. (Typically, you can increase performance by lowering this value.) + In addition to the distinction between quotas and throttles, some constraining properties are located at the serialization level, some at the transport level, and some at the application level. For example, the quota , which is implemented by all system-supplied transport binding elements, is set to 65,536 bytes by default to hinder malicious clients from engaging in denial-of-service attacks against a service by causing excessive memory consumption. (Typically, you can increase performance by lowering this value.) - An example of a serialization quota is the property, which specifies the maximum number of objects that the serializer serializes or deserializes in a single method call. An example of an application-level throttle is the property, which by default restricts the number of concurrent sessionful channel connections to 10. (Unlike the quotas, if this throttle value is reached, the application continues processing but accepts no new sessionful channels, which means that new clients cannot connect until one of the other sessionful channels is ended.) + An example of a serialization quota is the property, which specifies the maximum number of objects that the serializer serializes or deserializes in a single method call. An example of an application-level throttle is the property, which by default restricts the number of concurrent sessionful channel connections to 10. (Unlike the quotas, if this throttle value is reached, the application continues processing but accepts no new sessionful channels, which means that new clients cannot connect until one of the other sessionful channels is ended.) - These controls are designed to provide an out-of-the-box mitigation against certain types of attacks or to improve performance metrics such as memory footprint, start-up time, and so on. However, depending on the application, these controls can impede service application performance or prevent the application from working at all. For example, an application designed to stream video can easily exceed the default property. This topic provides an overview of the various controls applied to applications at all levels of [!INCLUDE[indigo2](../../../includes/indigo2-md.md)], describes various ways to obtain more information about whether a setting is hindering your application, and describes ways to correct various problems. Most throttles and some quotas are available at the application level, even when the base property is a serialization or transport constraint. For example, you can set the property using the property on the service class. + These controls are designed to provide an out-of-the-box mitigation against certain types of attacks or to improve performance metrics such as memory footprint, start-up time, and so on. However, depending on the application, these controls can impede service application performance or prevent the application from working at all. For example, an application designed to stream video can easily exceed the default property. This topic provides an overview of the various controls applied to applications at all levels of [!INCLUDE[indigo2](../../../includes/indigo2-md.md)], describes various ways to obtain more information about whether a setting is hindering your application, and describes ways to correct various problems. Most throttles and some quotas are available at the application level, even when the base property is a serialization or transport constraint. For example, you can set the property using the property on the service class. > [!NOTE] > If you have a particular problem, you should first read the [WCF Troubleshooting Quickstart](../../../docs/framework/wcf/wcf-troubleshooting-quickstart.md) to see whether your problem (and a solution) is listed there. @@ -35,9 +35,9 @@ This topic describes various properties in different areas of the [!INCLUDE[indi ## Detecting Application and Performance Issues Related to Quota Settings The defaults of the preceding values have been chosen to enable basic application functionality across a wide range of application types while providing basic protection against common security issues. However, different application designs might exceed one or more throttle settings although the application otherwise is secure and would work as designed. In these cases, you must identify which throttle values are being exceeded and at what level, and decide on the appropriate course of action to increase application throughput. - Typically, when writing the application and debugging it, you set the property to `true` in the configuration file or programmatically. This instructs [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] to return service exception stack traces to the client application for viewing. This feature reports most application-level exceptions in such a way as to display which quota settings might be involved, if that is the problem. + Typically, when writing the application and debugging it, you set the property to `true` in the configuration file or programmatically. This instructs [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] to return service exception stack traces to the client application for viewing. This feature reports most application-level exceptions in such a way as to display which quota settings might be involved, if that is the problem. - Some exceptions happen at run time below the visibility of the application layer and are not returned using this mechanism, and they might not be handled by a custom implementation. If you are in a development environment like Microsoft Visual Studio, most of these exceptions are displayed automatically. However, some exceptions can be masked by development environment settings such as the [Just My Code](http://go.microsoft.com/fwlink/?LinkId=82174) settings in Visual Studio 2005. + Some exceptions happen at run time below the visibility of the application layer and are not returned using this mechanism, and they might not be handled by a custom implementation. If you are in a development environment like Microsoft Visual Studio, most of these exceptions are displayed automatically. However, some exceptions can be masked by development environment settings such as the [Just My Code](http://go.microsoft.com/fwlink/?LinkId=82174) settings in Visual Studio 2005. Regardless of the capabilities of your development environment, you can use capabilities of [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] tracing and message logging to debug all exceptions and tune the performance of your applications. For more information, see [Using Tracing to Troubleshoot Your Application](../../../docs/framework/wcf/diagnostics/tracing/using-tracing-to-troubleshoot-your-application.md). diff --git a/docs/framework/wcf/creating-ws-i-basic-profile-1-1-interoperable-services.md b/docs/framework/wcf/creating-ws-i-basic-profile-1-1-interoperable-services.md index 0b7134eeab104..b9f4e1a6da9a5 100644 --- a/docs/framework/wcf/creating-ws-i-basic-profile-1-1-interoperable-services.md +++ b/docs/framework/wcf/creating-ws-i-basic-profile-1-1-interoperable-services.md @@ -20,7 +20,7 @@ manager: "erikre" # Creating WS-I Basic Profile 1.1 Interoperable Services To configure a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service endpoint to be interoperable with [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)] Web service clients: -- Use the type as the binding type for your service endpoint. +- Use the type as the binding type for your service endpoint. - Do not use callback and session contract features or transaction behaviors on your service endpoint @@ -28,9 +28,9 @@ To configure a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service endp The following features of the class require functionality beyond WS-I Basic Profile 1.1: -- Message Transmission Optimization Mechanism (MTOM) message encoding controlled by the property. Leave this property at its default value, which is to not use MTOM. +- Message Transmission Optimization Mechanism (MTOM) message encoding controlled by the property. Leave this property at its default value, which is to not use MTOM. -- Message security controlled by the value provides WS-Security support compliant with WS-I Basic Security Profile 1.0. Leave this property at its default value, which is to not use WS-Security. +- Message security controlled by the value provides WS-Security support compliant with WS-I Basic Security Profile 1.0. Leave this property at its default value, which is to not use WS-Security. To make the metadata for a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service available to [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)], use the Web service client generation tools: [Web Services Description Language Tool (Wsdl.exe)](http://msdn.microsoft.com/en-us/b9210348-8bc2-4367-8c91-d1a04b403e88), [Web Services Discovery Tool (Disco.exe)](http://msdn.microsoft.com/en-us/acd88078-c581-42bc-94ca-6633e2851979), and the `Add Web Reference` feature in [!INCLUDE[vsprvs](../../../includes/vsprvs-md.md)]; you must enable metadata publication. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Publishing Metadata Endpoints](../../../docs/framework/wcf/publishing-metadata-endpoints.md). diff --git a/docs/framework/wcf/defining-and-specifying-faults.md b/docs/framework/wcf/defining-and-specifying-faults.md index 3a902d5cd9416..4ec57deee0051 100644 --- a/docs/framework/wcf/defining-and-specifying-faults.md +++ b/docs/framework/wcf/defining-and-specifying-faults.md @@ -22,7 +22,7 @@ manager: "erikre" SOAP faults convey error condition information from a service to a client and, in the duplex case, from a client to a service in an interoperable way. This topic discusses when and how to define custom fault content and specify which operations can return them. [!INCLUDE[crabout](../../../includes/crabout-md.md)] how a service, or duplex client, can send those faults and how a client or service application handles these faults, see [Sending and Receiving Faults](../../../docs/framework/wcf/sending-and-receiving-faults.md). For an overview of error handling in [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, see [Specifying and Handling Faults in Contracts and Services](../../../docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md). ## Overview - Declared SOAP faults are those in which an operation has a that specifies a custom SOAP fault type. Undeclared SOAP faults are those that are not specified in the contract for an operation. This topic helps you identify those error conditions and create a fault contract for your service that clients can use to properly handle those error conditions when notified by custom SOAP faults. The basic tasks are, in order: + Declared SOAP faults are those in which an operation has a that specifies a custom SOAP fault type. Undeclared SOAP faults are those that are not specified in the contract for an operation. This topic helps you identify those error conditions and create a fault contract for your service that clients can use to properly handle those error conditions when notified by custom SOAP faults. The basic tasks are, in order: 1. Define the error conditions that a client of your service should know about. @@ -33,7 +33,7 @@ SOAP faults convey error condition information from a service to a client and, i ### Defining Error Conditions That Clients Should Know About SOAP faults are publicly described messages that carry fault information for a particular operation. Because they are described along with other operation messages in WSDL, clients know and, therefore, expect to handle such faults when invoking an operation. But because [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] services are written in managed code, deciding which error conditions in managed code are to be converted into faults and returned to the client provides you the opportunity to separate error conditions and bugs in your service from the formal error conversation you have with a client. - For example, the following code example shows an operation that takes two integers and returns another integer. Several exceptions can be thrown here, so when designing the fault contract, you must determine which error conditions are important for your client. In this case, the service should detect the exception. + For example, the following code example shows an operation that takes two integers and returns another integer. Several exceptions can be thrown here, so when designing the fault contract, you must determine which error conditions are important for your client. In this case, the service should detect the exception. ```csharp [ServiceContract] @@ -64,15 +64,15 @@ End Class In the preceding example the operation can either return a custom SOAP fault that is specific to dividing by zero, a custom fault that is specific to math operations but that contains information specific to dividing by zero, multiple faults for several different error situations, or no SOAP fault at all. ### Define the Content of Error Conditions - Once an error condition has been identified as one that can usefully return a custom SOAP fault, the next step is to define the contents of that fault and ensure that the content structure can be serialized. The code example in the preceding section shows an error specific to a `Divide` operation, but if there are other operations on the `Calculator` service, then a single custom SOAP fault can inform the client of all calculator error conditions, `Divide` included. The following code example shows the creation of a custom SOAP fault, `MathFault`, which can report errors made using all math operations, including `Divide`. While the class can specify an operation (the `Operation` property) and a value that describes the problem (the `ProblemType` property), the class and these properties must be serializable to be transferred to the client in a custom SOAP fault. Therefore, the and attributes are used to make the type and its properties serializable and as interoperable as possible. + Once an error condition has been identified as one that can usefully return a custom SOAP fault, the next step is to define the contents of that fault and ensure that the content structure can be serialized. The code example in the preceding section shows an error specific to a `Divide` operation, but if there are other operations on the `Calculator` service, then a single custom SOAP fault can inform the client of all calculator error conditions, `Divide` included. The following code example shows the creation of a custom SOAP fault, `MathFault`, which can report errors made using all math operations, including `Divide`. While the class can specify an operation (the `Operation` property) and a value that describes the problem (the `ProblemType` property), the class and these properties must be serializable to be transferred to the client in a custom SOAP fault. Therefore, the and attributes are used to make the type and its properties serializable and as interoperable as possible. [!code-csharp[Faults#2](../../../samples/snippets/csharp/VS_Snippets_CFX/faults/cs/service.cs#2)] [!code-vb[Faults#2](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faults/vb/service.vb#2)] - [!INCLUDE[crabout](../../../includes/crabout-md.md)] how to ensure your data is serializable, see [Specifying Data Transfer in Service Contracts](../../../docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md). For a list of the serialization support that provides, see [Types Supported by the Data Contract Serializer](../../../docs/framework/wcf/feature-details/types-supported-by-the-data-contract-serializer.md). + [!INCLUDE[crabout](../../../includes/crabout-md.md)] how to ensure your data is serializable, see [Specifying Data Transfer in Service Contracts](../../../docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md). For a list of the serialization support that provides, see [Types Supported by the Data Contract Serializer](../../../docs/framework/wcf/feature-details/types-supported-by-the-data-contract-serializer.md). ### Mark Operations to Establish the Fault Contract - Once a serializable data structure that is returned as part of a custom SOAP fault is defined, the last step is to mark your operation contract as throwing a SOAP fault of that type. To do this, use the attribute and pass the type of the custom data type that you have constructed. The following code example shows how to use the attribute to specify that the `Divide` operation can return a SOAP fault of type `MathFault`. Other math-based operations can now also specify that they can return a `MathFault`. + Once a serializable data structure that is returned as part of a custom SOAP fault is defined, the last step is to mark your operation contract as throwing a SOAP fault of that type. To do this, use the attribute and pass the type of the custom data type that you have constructed. The following code example shows how to use the attribute to specify that the `Divide` operation can return a SOAP fault of type `MathFault`. Other math-based operations can now also specify that they can return a `MathFault`. [!code-csharp[Faults#1](../../../samples/snippets/csharp/VS_Snippets_CFX/faults/cs/service.cs#1)] [!code-vb[Faults#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faults/vb/service.vb#1)] @@ -86,7 +86,7 @@ End Class The attribute has a property that allows control of the WSDL fault element name that is generated in the metadata for that fault. - According to the SOAP standard, a fault can have an `Action`, a `Code`, and a `Reason`. The `Action` is controlled by the property. The property and property are both properties of the class, which is the parent class of the generic . The `Code` property includes a member. + According to the SOAP standard, a fault can have an `Action`, a `Code`, and a `Reason`. The `Action` is controlled by the property. The property and property are both properties of the class, which is the parent class of the generic . The `Code` property includes a member. When accessing non-services that generate faults, certain limitations exist. [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] supports only faults with detail types that the schema describes and that are compatible with data contracts. For example, as mentioned above, [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] does not support faults that use XML attributes in their detail types, or faults with more than one top-level element in the detail section. diff --git a/docs/framework/wcf/designing-service-contracts.md b/docs/framework/wcf/designing-service-contracts.md index fdd1e0fc22a53..5854f7e79ea3e 100644 --- a/docs/framework/wcf/designing-service-contracts.md +++ b/docs/framework/wcf/designing-service-contracts.md @@ -69,7 +69,7 @@ This topic describes what service contracts are, how they are defined, what oper Primitive types are serializable by default, as are many types in the .NET Framework. > [!NOTE] -> The value of the parameter names in the operation signature are part of the contract and are case sensitive. If you want to use the same parameter name locally but modify the name in the published metadata, see the . +> The value of the parameter names in the operation signature are part of the contract and are case sensitive. If you want to use the same parameter name locally but modify the name in the published metadata, see the . #### Data Contracts Service-oriented applications like [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications are designed to interoperate with the widest possible number of client applications on both Microsoft and non-Microsoft platforms. For the widest possible interoperability, it is recommended that you mark your types with the and attributes to create a data contract, which is the portion of the service contract that describes the data that your service operations exchange. @@ -178,12 +178,12 @@ End Interface In addition, using `out` or `ref` parameters requires that the operation have an underlying response message to carry back the modified object. If your operation is a one-way operation, an exception is thrown at runtime. ### Specify Message Protection Level on the Contract - When designing your contract, you must also decide the message protection level of services that implement your contract. This is necessary only if message security is applied to the binding in the contract's endpoint. If the binding has security turned off (that is, if the system-provided binding sets the to the value ) then you do not have to decide on the message protection level for the contract. In most cases, system-provided bindings with message-level security applied provide a sufficient protection level and you do not have to consider the protection level for each operation or for each message. + When designing your contract, you must also decide the message protection level of services that implement your contract. This is necessary only if message security is applied to the binding in the contract's endpoint. If the binding has security turned off (that is, if the system-provided binding sets the to the value ) then you do not have to decide on the message protection level for the contract. In most cases, system-provided bindings with message-level security applied provide a sufficient protection level and you do not have to consider the protection level for each operation or for each message. The protection level is a value that specifies whether the messages (or message parts) that support a service are signed, signed and encrypted, or sent without signatures or encryption. The protection level can be set at various scopes: At the service level, for a particular operation, for a message within that operation, or a message part. Values set at one scope become the default value for smaller scopes unless explicitly overridden. If a binding configuration cannot provide the required minimum protection level for the contract, an exception is thrown. And when no protection level values are explicitly set on the contract, the binding configuration controls the protection level for all messages if the binding has message security. This is the default behavior. > [!IMPORTANT] -> Deciding whether to explicitly set various scopes of a contract to less than the full protection level of is generally a decision that trades some degree of security for increased performance. In these cases, your decisions must revolve around your operations and the value of the data they exchange. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Securing Services](../../../docs/framework/wcf/securing-services.md). +> Deciding whether to explicitly set various scopes of a contract to less than the full protection level of is generally a decision that trades some degree of security for increased performance. In these cases, your decisions must revolve around your operations and the value of the data they exchange. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Securing Services](../../../docs/framework/wcf/securing-services.md). For example, the following code example does not set either the or the property on the contract. @@ -214,7 +214,7 @@ Public Interface ISampleService End Interface ``` - When interacting with an `ISampleService` implementation in an endpoint with a default (the default , which is ), all messages are encrypted and signed because this is the default protection level. However, when an `ISampleService` service is used with a default (the default , which is ), all messages are sent as text because there is no security for this binding and so the protection level is ignored (that is, the messages are neither encrypted nor signed). If the was changed to , then these messages would be encrypted and signed (because that would now be the binding's default protection level). + When interacting with an `ISampleService` implementation in an endpoint with a default (the default , which is ), all messages are encrypted and signed because this is the default protection level. However, when an `ISampleService` service is used with a default (the default , which is ), all messages are sent as text because there is no security for this binding and so the protection level is ignored (that is, the messages are neither encrypted nor signed). If the was changed to , then these messages would be encrypted and signed (because that would now be the binding's default protection level). If you want to explicitly specify or adjust the protection requirements for your contract, set the property (or any of the `ProtectionLevel` properties at a smaller scope) to the level your service contract requires. In this case, using an explicit setting requires the binding to support that setting at a minimum for the scope used. For example, the following code example specifies one value explicitly, for the `GetGuid` operation. @@ -252,20 +252,20 @@ Public Interface IExplicitProtectionLevelSampleService End Interface ``` - A service that implements this `IExplicitProtectionLevelSampleService` contract and has an endpoint that uses the default (the default , which is ) has the following behavior: + A service that implements this `IExplicitProtectionLevelSampleService` contract and has an endpoint that uses the default (the default , which is ) has the following behavior: - The `GetString` operation messages are encrypted and signed. - The `GetInt` operation messages are sent as unencrypted and unsigned (that is, plain) text. -- The `GetGuid` operation is returned in a message that is encrypted and signed. +- The `GetGuid` operation is returned in a message that is encrypted and signed. [!INCLUDE[crabout](../../../includes/crabout-md.md)] protection levels and how to use them, see [Understanding Protection Level](../../../docs/framework/wcf/understanding-protection-level.md). [!INCLUDE[crabout](../../../includes/crabout-md.md)] security, see [Securing Services](../../../docs/framework/wcf/securing-services.md). ##### Other Operation Signature Requirements Some application features require a particular kind of operation signature. For example, the binding supports durable services and clients, in which an application can restart in the middle of communication and pick up where it left off without missing any messages. ([!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Queues in WCF](../../../docs/framework/wcf/feature-details/queues-in-wcf.md).) However, durable operations must take only one `in` parameter and have no return value. - Another example is the use of types in operations. Because the parameter includes the entire message body, if an input or an output (that is, `ref` parameter, `out` parameter, or return value) is of type , then it must be the only input or output specified in your operation. In addition, the parameter or return type must be either , , or . [!INCLUDE[crabout](../../../includes/crabout-md.md)] streams, see [Large Data and Streaming](../../../docs/framework/wcf/feature-details/large-data-and-streaming.md). + Another example is the use of types in operations. Because the parameter includes the entire message body, if an input or an output (that is, `ref` parameter, `out` parameter, or return value) is of type , then it must be the only input or output specified in your operation. In addition, the parameter or return type must be either , , or . [!INCLUDE[crabout](../../../includes/crabout-md.md)] streams, see [Large Data and Streaming](../../../docs/framework/wcf/feature-details/large-data-and-streaming.md). ##### Names, Namespaces, and Obfuscation The names and namespaces of the .NET types in the definition of contracts and operations are significant when contracts are converted into WSDL and when contract messages are created and sent. Therefore, it is strongly recommended that service contract names and namespaces are explicitly set using the `Name` and `Namespace` properties of all supporting contract attributes such as the , , , , and other contract attributes. diff --git a/docs/framework/wcf/extending/bindings-and-binding-elements.md b/docs/framework/wcf/extending/bindings-and-binding-elements.md index bbe22de0da2d7..629403e2ef3fb 100644 --- a/docs/framework/wcf/extending/bindings-and-binding-elements.md +++ b/docs/framework/wcf/extending/bindings-and-binding-elements.md @@ -27,7 +27,7 @@ Bindings are collections of special configuration elements, called *binding elem ## Extending Bindings and Binding Elements [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] includes system-provided bindings that cover a wide range of scenarios. (For more, see [System-Provided Bindings](../../../../docs/framework/wcf/system-provided-bindings.md).) There may be times, however, when you need to create and use a binding that is not included in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The following scenarios require the creation of a new binding. -- To use a new binding element (such as a new transport, encoding, or protocol binding element), you must create a new binding that includes that binding element. For example, if you added a custom `UdpTransportBindingElement` for UDP transport, you would need to create a new binding to make use of it. For information about performing this behavior using the type, see [Custom Bindings](../../../../docs/framework/wcf/extending/custom-bindings.md). +- To use a new binding element (such as a new transport, encoding, or protocol binding element), you must create a new binding that includes that binding element. For example, if you added a custom `UdpTransportBindingElement` for UDP transport, you would need to create a new binding to make use of it. For information about performing this behavior using the type, see [Custom Bindings](../../../../docs/framework/wcf/extending/custom-bindings.md). - To configure existing binding elements in a way that the system-provided bindings to not expose on public properties. For example, you must create a new binding to change the order in which signing and encryption operations are performed. For information about performing this behavior, see [How to: Customize a System-Provided Binding](../../../../docs/framework/wcf/extending/how-to-customize-a-system-provided-binding.md). @@ -42,7 +42,7 @@ Bindings are collections of special configuration elements, called *binding elem The channel layer hands off or receives messages to and from the service layer and transports those messages between endpoints. On a client, the channel layer is a stack of channel factories that create channels to a network endpoint. On a service, the channel layer is a stack of channel listeners that accept channels received at a network endpoint. - There are two general types of channels: protocol channels and transport channels. Transport channels are responsible for the actual transmission of a message from one network endpoint to another. Transport channels must have a default message encoder and should be able to use an alternate message encoder supplied through a message encoder binding element. A message encoder is responsible for turning a into a wire representation and vice-versa. Protocol channels are responsible for implementing SOAP-level protocols (for example, WS-Security or WS-ReliableMessaging). + There are two general types of channels: protocol channels and transport channels. Transport channels are responsible for the actual transmission of a message from one network endpoint to another. Transport channels must have a default message encoder and should be able to use an alternate message encoder supplied through a message encoder binding element. A message encoder is responsible for turning a into a wire representation and vice-versa. Protocol channels are responsible for implementing SOAP-level protocols (for example, WS-Security or WS-ReliableMessaging). The primary requirement for transport and protocol channels is that they implement the required channel interfaces. To create a working channel layer they must have associated factories and listeners, and so on. To use the channel implementations from [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] there needs to be an associated binding elements derived from for each channel and there should be a related binding extension element for inclusion into configuration files that derives from . diff --git a/docs/framework/wcf/extending/channel-model-overview.md b/docs/framework/wcf/extending/channel-model-overview.md index faf9defff055f..904b7c55cfc4d 100644 --- a/docs/framework/wcf/extending/channel-model-overview.md +++ b/docs/framework/wcf/extending/channel-model-overview.md @@ -44,7 +44,7 @@ The [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] channel stack is a l - - Further, each of these shapes has an equivalent that extends to support sessions. These are: + Further, each of these shapes has an equivalent that extends to support sessions. These are: - @@ -80,7 +80,7 @@ The [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] channel stack is a l |-----------|-----------------| |[Service: Channel Listeners and Channels](../../../../docs/framework/wcf/extending/service-channel-listeners-and-channels.md)|Describes channel listeners, which listen for incoming channels in a service application.| |[Client: Channel Factories and Channels](../../../../docs/framework/wcf/extending/client-channel-factories-and-channels.md)|Describes channel factories, which create channels to connect to a service application.| -|[Understanding State Changes](../../../../docs/framework/wcf/extending/understanding-state-changes.md)|Describes how the interface models state changes in channels.| +|[Understanding State Changes](../../../../docs/framework/wcf/extending/understanding-state-changes.md)|Describes how the interface models state changes in channels.| |[Choosing a Message Exchange Pattern](../../../../docs/framework/wcf/extending/choosing-a-message-exchange-pattern.md)|Describes the six basic message exchange patterns that channels can support.| |[Handling Exceptions and Faults](../../../../docs/framework/wcf/extending/handling-exceptions-and-faults.md)|Describes how to handle faults and exceptions in custom channels.| |[Configuration and Metadata Support](../../../../docs/framework/wcf/extending/configuration-and-metadata-support.md)|Describes how to support the use of custom channels from the application model and how to export and import metadata using bindings and binding elements.| diff --git a/docs/framework/wcf/extending/choosing-a-message-exchange-pattern.md b/docs/framework/wcf/extending/choosing-a-message-exchange-pattern.md index 04c6b87b2957c..1f538b304b5bc 100644 --- a/docs/framework/wcf/extending/choosing-a-message-exchange-pattern.md +++ b/docs/framework/wcf/extending/choosing-a-message-exchange-pattern.md @@ -36,7 +36,7 @@ The first step in writing a custom transport is to decide which *message exchang ![Choosing a message exchange pattern](../../../../docs/framework/wcf/extending/media/wcfc-basicthreemepsc.gif "wcfc_BasicThreeMEPsc") The three basic message exchange patterns. Top to bottom: datagram, request-response, and duplex. - Each of these MEPs can also support *sessions*. A session (and implementation of of type ) correlates all messages sent and received on a channel. The request-response pattern is a stand-alone two-message session, as the request and reply are correlated. In contrast, the request-response pattern that supports sessions implies that all request/response pairs on that channel are correlated with each other. This gives you a total of six MEPs to choose from: + Each of these MEPs can also support *sessions*. A session (and implementation of of type ) correlates all messages sent and received on a channel. The request-response pattern is a stand-alone two-message session, as the request and reply are correlated. In contrast, the request-response pattern that supports sessions implies that all request/response pairs on that channel are correlated with each other. This gives you a total of six MEPs to choose from: - Datagram @@ -71,9 +71,9 @@ The three basic message exchange patterns. Top to bottom: datagram, request-resp The exception to this is which is used for both sending and receiving messages in a duplex, sessionful communication pattern. It is possible that one side will want to stop sending messages but continue to receive messages therefore when using there is a mechanism that lets you close the output session indicating you will not send any more messages but keep the input session opened allowing you to continue to receive messages. - In general, sessions are closed on the outgoing side and not on the incoming side. That is, sessionful output channels can be closed, thereby cleanly terminating the session. Closing a sessionful output channel causes the corresponding sessionful input channel to return null to the application calling on the . + In general, sessions are closed on the outgoing side and not on the incoming side. That is, sessionful output channels can be closed, thereby cleanly terminating the session. Closing a sessionful output channel causes the corresponding sessionful input channel to return null to the application calling on the . - However sessionful input channels should not be closed unless on the returns null, indicating that the session is already closed. If on the has not returned null, closing a sessionful input channel may throw an exception because it may receive unexpected messages while closing. If a receiver wishes to terminate a session before the sender does, it should call on the input channel, which abruptly terminates the session. + However sessionful input channels should not be closed unless on the returns null, indicating that the session is already closed. If on the has not returned null, closing a sessionful input channel may throw an exception because it may receive unexpected messages while closing. If a receiver wishes to terminate a session before the sender does, it should call on the input channel, which abruptly terminates the session. ## Writing Sessionful Channels As a sessionful channel author, there are a few things your channel must do to provide sessions. On the send side, your channel needs to: @@ -84,13 +84,13 @@ The three basic message exchange patterns. Top to bottom: datagram, request-resp - For each message sent using this channel, you need to provide the delivery guarantees mentioned above. If you are relying on the channel below you to provide the session, that channel will also provide the delivery guarantees. If you’re providing the session yourself, you need to implement those guarantees as part of your protocol. In general, if you are writing a protocol channel that assumes WCF on both sides you may require the TCP transport or the Reliable Messaging channel and rely on either one to provide a session. -- When is called on your channel, perform the necessary work to close the session using either the specified timeout or the default one. This can be as simple as calling on the channel below you (if you just obtained the session from it) or sending a special SOAP message or closing a transport connection. +- When is called on your channel, perform the necessary work to close the session using either the specified timeout or the default one. This can be as simple as calling on the channel below you (if you just obtained the session from it) or sending a special SOAP message or closing a transport connection. - When is called on your channel, terminate the session abruptly without performing I/O. This may mean doing nothing or may involve aborting a network connection or some other resource. On the receive side, your channel needs to: -- For each incoming message, the channel listener must detect the session it belongs to. If this is the first message in the session, the channel listener must create a new channel and return it from the call to . Otherwise the channel listener must find the existing channel that corresponds to the session and deliver the message through that channel. +- For each incoming message, the channel listener must detect the session it belongs to. If this is the first message in the session, the channel listener must create a new channel and return it from the call to . Otherwise the channel listener must find the existing channel that corresponds to the session and deliver the message through that channel. - If your channel is providing the session (along with the required delivery guarantees) the receive side may be required to perform some actions such as re-order messages or send acknowledgements. diff --git a/docs/framework/wcf/extending/client-channel-factories-and-channels.md b/docs/framework/wcf/extending/client-channel-factories-and-channels.md index 7e96e35a64ed1..8961740cd85ad 100644 --- a/docs/framework/wcf/extending/client-channel-factories-and-channels.md +++ b/docs/framework/wcf/extending/client-channel-factories-and-channels.md @@ -30,7 +30,7 @@ A channel factory creates channels. - The class implements and enforces the state machine described in step 2 of [Developing Channels](../../../../docs/framework/wcf/extending/developing-channels.md). -- The`` class implements and provides a unified base class for and . The class works in conjunction with , which is a base class that implements . +- The`` class implements and provides a unified base class for and . The class works in conjunction with , which is a base class that implements . - The`` class implements and and consolidates the `CreateChannel` overloads into one `OnCreateChannel` abstract method. diff --git a/docs/framework/wcf/extending/client-channel-level-programming.md b/docs/framework/wcf/extending/client-channel-level-programming.md index b1d027342b33f..1e79965dee74e 100644 --- a/docs/framework/wcf/extending/client-channel-level-programming.md +++ b/docs/framework/wcf/extending/client-channel-level-programming.md @@ -16,7 +16,7 @@ ms.author: "erikre" manager: "erikre" --- # Client Channel-Level Programming -This topic describes how to write a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client application without using the class and its associated object model. +This topic describes how to write a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client application without using the class and its associated object model. ## Sending Messages To be ready to send messages and receive and process replies, the following steps are required: @@ -32,13 +32,13 @@ This topic describes how to write a [!INCLUDE[indigo1](../../../../includes/indi 5. Close all channel objects. #### Creating a Binding - Similar to the receiving case (see [Service Channel-Level Programming](../../../../docs/framework/wcf/extending/service-channel-level-programming.md)), sending messages starts by creating a binding. This example creates a new and adds an to its Elements collection. + Similar to the receiving case (see [Service Channel-Level Programming](../../../../docs/framework/wcf/extending/service-channel-level-programming.md)), sending messages starts by creating a binding. This example creates a new and adds an to its Elements collection. #### Building a ChannelFactory - Instead of creating a , this time we create a by calling on the binding where the type parameter is . While channel listeners are used by the side that waits for incoming messages, channel factories are used by the side that initiates the communication to create a channel. Just like channel listeners, channel factories must be opened first before they can be used. + Instead of creating a , this time we create a by calling on the binding where the type parameter is . While channel listeners are used by the side that waits for incoming messages, channel factories are used by the side that initiates the communication to create a channel. Just like channel listeners, channel factories must be opened first before they can be used. #### Creating a Channel - We then call to create an . This call takes the address of the endpoint with which we want to communicate using the new channel being created. Once we have a channel, we call Open on it to put it in a state ready for communication. Depending on the nature of the transport, this call to Open may initiate a connection with the target endpoint or may do nothing at all on the network. + We then call to create an . This call takes the address of the endpoint with which we want to communicate using the new channel being created. Once we have a channel, we call Open on it to put it in a state ready for communication. Depending on the nature of the transport, this call to Open may initiate a connection with the target endpoint or may do nothing at all on the network. #### Sending a Request and Reading the Reply Once we have an opened channel, we can create a message and use the channel’s Request method to send the request and wait for the reply to come back. When this method returns, we have a reply message that we can read to find out what the endpoint’s reply was. diff --git a/docs/framework/wcf/extending/configuration-and-metadata-support.md b/docs/framework/wcf/extending/configuration-and-metadata-support.md index a7d6259ff1b4e..1b5282c4d794a 100644 --- a/docs/framework/wcf/extending/configuration-and-metadata-support.md +++ b/docs/framework/wcf/extending/configuration-and-metadata-support.md @@ -32,7 +32,7 @@ This topic describes how to enable configuration and metadata support for bindin For information about creating user-defined bindings and binding elements, see [Creating User-Defined Bindings](../../../../docs/framework/wcf/extending/creating-user-defined-bindings.md) and [Creating a BindingElement](../../../../docs/framework/wcf/extending/creating-a-bindingelement.md), respectively. ## Adding Configuration Support - To enable configuration file support for a channel, you must implement two configuration sections, , which enables configuration support for binding elements, and the and , which enable configuration support for bindings. + To enable configuration file support for a channel, you must implement two configuration sections, , which enables configuration support for binding elements, and the and , which enable configuration support for bindings. An easier way to do this is to use the [ConfigurationCodeGenerator](../../../../docs/framework/wcf/samples/configurationcodegenerator.md) sample tool to generate configuration code for your bindings and binding elements. @@ -131,7 +131,7 @@ protected override void OnApplyConfiguration(string configurationName) The transport binding element in a binding is responsible for exporting and importing addressing information in metadata. When using a SOAP binding, the transport binding element should also export a correct transport URI in metadata. The following example code is taken from the [Transport: UDP](../../../../docs/framework/wcf/samples/transport-udp.md) sample. #### WSDL Export - To export addressing information, the `UdpTransportBindingElement` implements the interface. The method adds the correct addressing information to the WSDL port. + To export addressing information, the `UdpTransportBindingElement` implements the interface. The method adds the correct addressing information to the WSDL port. ``` if (context.WsdlPort != null) @@ -173,7 +173,7 @@ if (soapBinding != null) 2. Add the configuration section to Svcutil.exe.config in the same directory as Svcutil.exe. - The `UdpBindingElementImporter` type implements the interface. The `ImportEndpoint` method imports the address from the WSDL port: + The `UdpBindingElementImporter` type implements the interface. The `ImportEndpoint` method imports the address from the WSDL port: ``` BindingElementCollection bindingElements = context.Endpoint.Binding.CreateBindingElements(); @@ -188,9 +188,9 @@ if (transportBindingElement is UdpTransportBindingElement) The custom binding element can export policy assertions in the WSDL binding for a service endpoint to express the capabilities of that binding element. The following example code is taken from the [Transport: UDP](../../../../docs/framework/wcf/samples/transport-udp.md) sample. #### Policy Export - The `UdpTransportBindingElement` type implements`` to add support for exporting policy. As a result, includes `UdpTransportBindingElement` in the generation of policy for any binding that includes it. + The `UdpTransportBindingElement` type implements`` to add support for exporting policy. As a result, includes `UdpTransportBindingElement` in the generation of policy for any binding that includes it. - In , add an assertion for UDP and another assertion if the channel is in multicast mode. This is because multicast mode affects how the communication stack is constructed, and thus must be coordinated between both sides. + In , add an assertion for UDP and another assertion if the channel is in multicast mode. This is because multicast mode affects how the communication stack is constructed, and thus must be coordinated between both sides. ``` ICollection bindingAssertions = context.GetBindingAssertions(); @@ -204,7 +204,7 @@ UdpPolicyStrings.Prefix, UdpPolicyStrings.MulticastAssertion, UdpPolicyStrin } ``` - Because custom transport binding elements are responsible for handling addressing, the implementation on the `UdpTransportBindingElement` must also handle exporting the appropriate WS-Addressing policy assertions to indicate the version of WS-Addressing being used. + Because custom transport binding elements are responsible for handling addressing, the implementation on the `UdpTransportBindingElement` must also handle exporting the appropriate WS-Addressing policy assertions to indicate the version of WS-Addressing being used. ``` AddWSAddressingAssertion(context, encodingBindingElement.MessageVersion.Addressing); @@ -227,16 +227,16 @@ AddWSAddressingAssertion(context, encodingBindingElement.MessageVersion.Addressi ``` - Then we implement from our registered class (`UdpBindingElementImporter`). In , examine the assertions in the appropriate namespace and process the ones for generating the transport and checking if it is multicast. In addition, remove the assertions that the importer handles from the list of binding assertions. Again, when running Svcutil.exe, there are two options for integration: + Then we implement from our registered class (`UdpBindingElementImporter`). In , examine the assertions in the appropriate namespace and process the ones for generating the transport and checking if it is multicast. In addition, remove the assertions that the importer handles from the list of binding assertions. Again, when running Svcutil.exe, there are two options for integration: 1. Point Svcutil.exe to our configuration file using the /SvcutilConfig:\. 2. Add the configuration section to Svcutil.exe.config in the same directory as Svcutil.exe. ### Adding a Custom Standard Binding Importer - Svcutil.exe and the type, by default, recognize and import system-provided bindings. Otherwise, the binding gets imported as a instance. To enable Svcutil.exe and the to import the `SampleProfileUdpBinding` the `UdpBindingElementImporter` also acts as a custom standard binding importer. + Svcutil.exe and the type, by default, recognize and import system-provided bindings. Otherwise, the binding gets imported as a instance. To enable Svcutil.exe and the to import the `SampleProfileUdpBinding` the `UdpBindingElementImporter` also acts as a custom standard binding importer. - A custom standard binding importer implements the `ImportEndpoint` method on the interface to examine the instance imported from metadata to see if it could have been generated by specific standard binding. + A custom standard binding importer implements the `ImportEndpoint` method on the interface to examine the instance imported from metadata to see if it could have been generated by specific standard binding. ``` if (context.Endpoint.Binding is CustomBinding) diff --git a/docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md b/docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md index 30f1246c02612..d8e7d562f9abc 100644 --- a/docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md +++ b/docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md @@ -52,7 +52,7 @@ Behaviors enable you to modify default behavior and add custom extensions that i - Operation behaviors ( types) enable the customization of the and classes, again, on the client and service. - You can add these behaviors to the various description objects by implementing custom attributes, using application configuration files, or directly by adding them to the behaviors collection on the appropriate description object. The must, however, be added to a service description or service endpoint description object prior to calling on the or a . + You can add these behaviors to the various description objects by implementing custom attributes, using application configuration files, or directly by adding them to the behaviors collection on the appropriate description object. The must, however, be added to a service description or service endpoint description object prior to calling on the or a . ### Behavior Scopes There are four behavior types, each of which corresponds to a particular scope of runtime access. @@ -76,11 +76,11 @@ Behaviors enable you to modify default behavior and add custom extensions that i #### Contract Behaviors Contract behaviors, which implement the interface, are used to extend both the client and service runtime across a contract. - There are two mechanisms for adding contract behaviors to a contract. The first mechanism is to create a custom attribute to be used on the contract interface. When a contract interface is passed to either a or a , [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] examines the attributes on the interface. If any attributes are implementations of , those are added to the behaviors collection on the created for that interface. + There are two mechanisms for adding contract behaviors to a contract. The first mechanism is to create a custom attribute to be used on the contract interface. When a contract interface is passed to either a or a , [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] examines the attributes on the interface. If any attributes are implementations of , those are added to the behaviors collection on the created for that interface. - You can also implement the on the custom contract behavior attribute. In this case, the behavior is as follows when applied to: + You can also implement the on the custom contract behavior attribute. In this case, the behavior is as follows when applied to: - •A contract interface. In this case, the behavior is applied to all contracts of that type in any endpoint and [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] ignores the value of the property. + •A contract interface. In this case, the behavior is applied to all contracts of that type in any endpoint and [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] ignores the value of the property. •A service class. In this case, the behavior is applied only to endpoints the contract of which is the value of the property. @@ -88,7 +88,7 @@ Behaviors enable you to modify default behavior and add custom extensions that i The second mechanism is to add the behavior to the behaviors collection on a . - Examples of contract behaviors in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] include the attribute. For more information and an example, see the reference topic. + Examples of contract behaviors in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] include the attribute. For more information and an example, see the reference topic. #### Endpoint Behaviors Endpoint behaviors, which implement , are the primary mechanism by which you modify the entire service or client run time for a specific endpoint. @@ -113,7 +113,7 @@ Behaviors enable you to modify default behavior and add custom extensions that i For more information and an example, see the reference topic. ### Using Configuration to Create Behaviors - Service and endpoint, and contract behaviors can by designed to be specified in code or using attributes; only service and endpoint behaviors can be configured using application or Web configuration files. Exposing behaviors using attributes allows developers to specify a behavior at compilation-time that cannot be added, removed, or modified at runtime. This is often suitable for behaviors that are always required for the correct operation of a service (for example, the transaction-related parameters to the attribute). Exposing behaviors using configuration allows developers to leave the specification and configuration of those behaviors to those who deploy the service. This is suitable for behaviors that are optional components or other deployment-specific configuration, such as whether metadata is exposed for the service or the particular authorization configuration for a service. + Service and endpoint, and contract behaviors can by designed to be specified in code or using attributes; only service and endpoint behaviors can be configured using application or Web configuration files. Exposing behaviors using attributes allows developers to specify a behavior at compilation-time that cannot be added, removed, or modified at runtime. This is often suitable for behaviors that are always required for the correct operation of a service (for example, the transaction-related parameters to the attribute). Exposing behaviors using configuration allows developers to leave the specification and configuration of those behaviors to those who deploy the service. This is suitable for behaviors that are optional components or other deployment-specific configuration, such as whether metadata is exposed for the service or the particular authorization configuration for a service. > [!NOTE] > You can also use behaviors that support configuration to enforce company application policies by inserting them into the machine.config configuration file and locking those items down. For a description and an example, see [How to: Lock Down Endpoints in the Enterprise](../../../../docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md). @@ -190,7 +190,7 @@ Behaviors enable you to modify default behavior and add custom extensions that i Where `Microsoft.WCF.Documentation.EndpointBehaviorMessageInspector` is the behavior extension type and `HostApplication` is the name of the assembly into which that class has been compiled. ### Evaluation Order - The and the are responsible for building the runtime from the programming model and description. Behaviors, as previously described, contribute to that build process at the service, endpoint, contract, and operation. + The and the are responsible for building the runtime from the programming model and description. Behaviors, as previously described, contribute to that build process at the service, endpoint, contract, and operation. The applies behaviors in the following order: @@ -215,11 +215,11 @@ Behaviors enable you to modify default behavior and add custom extensions that i Within any collection of behaviors, again, no order is guaranteed. ### Adding Behaviors Programmatically - Properties of the in the service application must not be modified subsequent to the method on . Some members, like the property and the `AddServiceEndpoint` methods on and , throw an exception if modified past that point. Others permit you to modify them, but the result is undefined. + Properties of the in the service application must not be modified subsequent to the method on . Some members, like the property and the `AddServiceEndpoint` methods on and , throw an exception if modified past that point. Others permit you to modify them, but the result is undefined. - Similarly, on the client the values must not be modified after the call to on the . The property throws an exception if modified past that point, but the other client description values can be modified without error. The result, however, is undefined. + Similarly, on the client the values must not be modified after the call to on the . The property throws an exception if modified past that point, but the other client description values can be modified without error. The result, however, is undefined. - Whether for the service or client, it is recommended that you modify the description prior to calling . + Whether for the service or client, it is recommended that you modify the description prior to calling . ### Inheritance Rules for Behavior Attributes All four types of behaviors can be populated using attributes – service behaviors and contract behaviors. Because attributes are defined on managed objects and members, and managed objects and members support inheritance, it is necessary to define how behavior attributes work in the context of inheritance. diff --git a/docs/framework/wcf/extending/creating-a-bindingelement.md b/docs/framework/wcf/extending/creating-a-bindingelement.md index d64fcf2fb38cd..5b881fd25b1e1 100644 --- a/docs/framework/wcf/extending/creating-a-bindingelement.md +++ b/docs/framework/wcf/extending/creating-a-bindingelement.md @@ -16,10 +16,10 @@ ms.author: "erikre" manager: "erikre" --- # Creating a BindingElement -Bindings and binding elements (objects that extend and , respectively) are the place where the [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] application model is associated with channel factories and channel listeners. Without bindings, using custom channels requires programming at the channel level as described in [Service Channel-Level Programming](../../../../docs/framework/wcf/extending/service-channel-level-programming.md) and [Client Channel-Level Programming](../../../../docs/framework/wcf/extending/client-channel-level-programming.md). This topic discusses the minimum requirement to enable using your channel in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], the development of a for your channel, and enable use from the application as described in step 4 of [Developing Channels](../../../../docs/framework/wcf/extending/developing-channels.md). +Bindings and binding elements (objects that extend and , respectively) are the place where the [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] application model is associated with channel factories and channel listeners. Without bindings, using custom channels requires programming at the channel level as described in [Service Channel-Level Programming](../../../../docs/framework/wcf/extending/service-channel-level-programming.md) and [Client Channel-Level Programming](../../../../docs/framework/wcf/extending/client-channel-level-programming.md). This topic discusses the minimum requirement to enable using your channel in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], the development of a for your channel, and enable use from the application as described in step 4 of [Developing Channels](../../../../docs/framework/wcf/extending/developing-channels.md). ## Overview - Creating a for your channel enables developers to use it in an [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] application. objects can be used from the class to connect an [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] application to your channel without having to the precise type information of your channel. + Creating a for your channel enables developers to use it in an [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] application. objects can be used from the class to connect an [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] application to your channel without having to the precise type information of your channel. Once a has been created, you can enable more functionality depending upon your requirements by following the remaining channel development steps described in [Developing Channels](../../../../docs/framework/wcf/extending/developing-channels.md). @@ -51,19 +51,19 @@ public IChannelListener BuildChannelListener(BindingContext It also contains members for cloning the `BindingElement` and returning our scheme (soap.udp). #### Protocol Binding Elements - New binding elements can replace or augment any of the included binding elements, adding new transports, encodings, or higher-level protocols. To create a new Protocol Binding Element, start by extending the class. At a minimum, you must then implement the and implement the `ChannelProtectionRequirements` using . This returns the for this binding element. For more information, see . + New binding elements can replace or augment any of the included binding elements, adding new transports, encodings, or higher-level protocols. To create a new Protocol Binding Element, start by extending the class. At a minimum, you must then implement the and implement the `ChannelProtectionRequirements` using . This returns the for this binding element. For more information, see . should return a fresh copy of this binding element. As a best practice, we recommend that binding element authors implement by using a copy constructor that calls the base copy constructor, then clones any additional fields in this class. #### Transport Binding Elements - To create a new Transport Binding Element, extend the interface. At a minimum, you must then implement the method and the property. + To create a new Transport Binding Element, extend the interface. At a minimum, you must then implement the method and the property. – Should return a fresh copy of this Binding Element. As a best practice, we recommend that Binding Element authors implement Clone by way of a copy constructor that calls the base copy constructor, then clones any additional fields in this class. - – The get property returns the URI scheme for the transport protocol represented by the binding element. For example, the and the return "http" and "net.tcp" from their respective properties. + – The get property returns the URI scheme for the transport protocol represented by the binding element. For example, the and the return "http" and "net.tcp" from their respective properties. #### Encoding Binding Elements - To create new Encoding Binding Elements, start by extending the class and implementing the class. At a minimum, you must then implement the , methods and the property. + To create new Encoding Binding Elements, start by extending the class and implementing the class. At a minimum, you must then implement the , methods and the property. - . Returns a fresh copy of this binding element. As a best practice, we recommend that binding element authors implement by using a copy constructor that calls the base copy constructor, then clones any additional fields in this class. diff --git a/docs/framework/wcf/extending/creating-user-defined-bindings.md b/docs/framework/wcf/extending/creating-user-defined-bindings.md index 563b06d274bc0..c0c4b421aff29 100644 --- a/docs/framework/wcf/extending/creating-user-defined-bindings.md +++ b/docs/framework/wcf/extending/creating-user-defined-bindings.md @@ -41,10 +41,10 @@ There are several ways to create bindings not provided by the system: |Layer|Options|Required| |-----------|-------------|--------------| -|Transaction Flow||No| -|Reliability||No| -|Security||No| -|Composite Duplex||No| +|Transaction Flow||No| +|Reliability||No| +|Security||No| +|Composite Duplex||No| |Encoding|Text, Binary, MTOM, Custom|Yes*| |Transport|TCP, Named Pipes, HTTP, HTTPS, MSMQ, Custom|Yes| diff --git a/docs/framework/wcf/extending/custom-stream-upgrades.md b/docs/framework/wcf/extending/custom-stream-upgrades.md index 38571b36197d2..0e9d2ccf382b3 100644 --- a/docs/framework/wcf/extending/custom-stream-upgrades.md +++ b/docs/framework/wcf/extending/custom-stream-upgrades.md @@ -38,13 +38,13 @@ Stream-oriented transports such as TCP and Named Pipes operate on a continuous s ## How to Implement a Stream Upgrade [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] provides four `abstract` classes that you can implement: -- +- -- +- -- +- -- +- To implement a custom stream upgrade, do the following. This procedure implements a minimal stream upgrade process on both the client and server machines. @@ -77,11 +77,11 @@ Stream-oriented transports such as TCP and Named Pipes operate on a continuous s For security scenarios not met by the above two binding elements, three security-related `abstract` classes are derived from the above initiator, acceptor and provider base classes: -1. +1. -2. +2. -3. +3. The process of implementing a security stream upgrade is the same as before, with the difference that you would derive from these three classes. Override the additional properties in these classes to supply security information to the runtime. diff --git a/docs/framework/wcf/extending/data-contract-surrogates.md b/docs/framework/wcf/extending/data-contract-surrogates.md index f5d3873bed959..5a2fc65cf9b14 100644 --- a/docs/framework/wcf/extending/data-contract-surrogates.md +++ b/docs/framework/wcf/extending/data-contract-surrogates.md @@ -101,10 +101,10 @@ The data contract *surrogate* is an advanced feature built upon the Data Contrac Either of these overloads must return either `null` or a serializable object. A non-null object will be serialized as annotation into the exported schema. For the `Type` overload, each type that is exported to schema is sent to this method in the first parameter along with the surrogated type as the `dataContractType` parameter. For the `MemberInfo` overload, each member that is exported to schema sends its information as the `memberInfo` parameter with the surrogated type in the second parameter. #### GetCustomDataToExport Method (Type, Type) - The method is called during schema export for every type definition. The method adds information to the types within the schema when exporting. Each type defined is sent to this method to determine whether there is any additional data that needs to be included in the schema. + The method is called during schema export for every type definition. The method adds information to the types within the schema when exporting. Each type defined is sent to this method to determine whether there is any additional data that needs to be included in the schema. #### GetCustomDataToExport Method (MemberInfo, Type) - The is called during export for every member in the types that are exported. This function enables you to customize any comments for the members that will be included in the schema upon export. The information for every member within the class is sent to this method to check whether any additional data need to be added in the schema. + The is called during export for every member in the types that are exported. This function enables you to customize any comments for the members that will be included in the schema upon export. The information for every member within the class is sent to this method to check whether any additional data need to be added in the schema. The example above searches through the `dataContractType` for each member of the surrogate. It then returns the appropriate access modifier for each field. Without this customization, the default value for access modifiers is public. Therefore, all members would be defined as public in the code generated using the exported schema no matter what their actual access restrictions are. When not using this implementation, the member `numpens` would be public in the exported schema even though it was defined in the surrogate as private. Through the use of this method, in the exported schema, the access modifier can be generated as private. diff --git a/docs/framework/wcf/extending/developing-channels.md b/docs/framework/wcf/extending/developing-channels.md index 2055cbfdee08e..5fdf5655d8319 100644 --- a/docs/framework/wcf/extending/developing-channels.md +++ b/docs/framework/wcf/extending/developing-channels.md @@ -25,7 +25,7 @@ To develop a protocol or transport channel that can be used with the [!INCLUDE[i 2. Create a channel factory and listener ( and ) that support your message exchange pattern. For details about developing factories, see [Client: Channel Factories and Channels](../../../../docs/framework/wcf/extending/client-channel-factories-and-channels.md). For details about developing listeners, see [Service: Channel Listeners and Channels](../../../../docs/framework/wcf/extending/service-channel-listeners-and-channels.md). -3. Ensure that any network-specific exceptions are normalized to either or the appropriate derived class of . For details, see [Handling Exceptions and Faults](../../../../docs/framework/wcf/extending/handling-exceptions-and-faults.md). +3. Ensure that any network-specific exceptions are normalized to either or the appropriate derived class of . For details, see [Handling Exceptions and Faults](../../../../docs/framework/wcf/extending/handling-exceptions-and-faults.md). 4. To enable use from the application layer, add a that adds the custom channel to a channel stack. For more information, see [Creating a BindingElement](../../../../docs/framework/wcf/extending/creating-a-bindingelement.md). diff --git a/docs/framework/wcf/extending/exporting-custom-metadata-for-a-wcf-extension.md b/docs/framework/wcf/extending/exporting-custom-metadata-for-a-wcf-extension.md index 9520b7204169e..cfaef661a1b8c 100644 --- a/docs/framework/wcf/extending/exporting-custom-metadata-for-a-wcf-extension.md +++ b/docs/framework/wcf/extending/exporting-custom-metadata-for-a-wcf-extension.md @@ -21,24 +21,24 @@ In [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)], metadata export is t This section describes exporting custom WSDL or policy assertions, and does not focus on the exporting process itself. For more information about how to use the types that export and import metadata regardless of whether the metadata is custom or system-constructed, see [Exporting and Importing Metadata](../../../../docs/framework/wcf/feature-details/exporting-and-importing-metadata.md). ## Overview - When metadata is published using the , the is examined and XSD and WSDL -- including policy assertions -- are generated for all contracts and bindings that [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] can support using system-provided attributes and bindings. However, custom behavior attributes or binding elements require support before they can be exported properly. + When metadata is published using the , the is examined and XSD and WSDL -- including policy assertions -- are generated for all contracts and bindings that [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] can support using system-provided attributes and bindings. However, custom behavior attributes or binding elements require support before they can be exported properly. This section describes: -1. How to implement and use the interface, which exposes the WSDL generation data to you prior to publishing the WSDL. +1. How to implement and use the interface, which exposes the WSDL generation data to you prior to publishing the WSDL. -2. How to implement and use the interface, which exposes the policy data to you prior to exporting the policy assertions in WSDL data. +2. How to implement and use the interface, which exposes the policy data to you prior to exporting the policy assertions in WSDL data. For more information about importing custom WSDL and policy assertions, see [Importing Custom Metadata for a WCF Extension](../../../../docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md). ## Exporting Custom WSDL Elements - Implement the on an operation behavior, contract behavior, endpoint behavior or binding element (, , , or respectively) and insert the behaviors or binding elements into the description of the service that you are trying to export. (For more information about inserting behaviors, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md)). The is called for each endpoint and each endpoint exports the contract first if it has not already been exported. You can participate in either export process, depending upon your needs: + Implement the on an operation behavior, contract behavior, endpoint behavior or binding element (, , , or respectively) and insert the behaviors or binding elements into the description of the service that you are trying to export. (For more information about inserting behaviors, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md)). The is called for each endpoint and each endpoint exports the contract first if it has not already been exported. You can participate in either export process, depending upon your needs: - Use the to modify the exported metadata in the method. - Use the to modify the exported metadata for the endpoint in the method. - The method is called on all implementations within the instance that is being exported. The method is called on all implementations with the instance that is being exported. + The method is called on all implementations within the instance that is being exported. The method is called on all implementations with the instance that is being exported. For more information, see [How to: Export Custom WSDL](../../../../docs/framework/wcf/extending/how-to-export-custom-wsdl.md) and the sample [Custom WSDL Publication](../../../../docs/framework/wcf/samples/custom-wsdl-publication.md). diff --git a/docs/framework/wcf/extending/extending-clients.md b/docs/framework/wcf/extending/extending-clients.md index 873f4d74ee11f..b26ab5f5704de 100644 --- a/docs/framework/wcf/extending/extending-clients.md +++ b/docs/framework/wcf/extending/extending-clients.md @@ -40,7 +40,7 @@ In a calling application, the service model layer is responsible for translating - Custom Message Transformations. Rather than modifying application code, the user may want to apply certain transformations to the message in the runtime (for example, for versioning). This can be accomplished, again, with the message interceptor interfaces. -- Custom Data Model. A user may want to have a data or serialization model other than those supported by default in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] (namely, , , and objects). This can be done by implementing the message formatter interfaces. For more information, see and the property. +- Custom Data Model. A user may want to have a data or serialization model other than those supported by default in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] (namely, , , and objects). This can be done by implementing the message formatter interfaces. For more information, see and the property. - Custom Parameter Validation. A user may want to enforce that typed parameters are valid (as opposed to XML). This can be done using the parameter inspector interfaces. For an example, see [How to: Inspect or Modify Parameters](../../../../docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md) or [Client Validation](../../../../docs/framework/wcf/samples/client-validation.md). diff --git a/docs/framework/wcf/extending/extending-dispatchers.md b/docs/framework/wcf/extending/extending-dispatchers.md index 782daf99c3467..8c9f4eb67f21a 100644 --- a/docs/framework/wcf/extending/extending-dispatchers.md +++ b/docs/framework/wcf/extending/extending-dispatchers.md @@ -52,7 +52,7 @@ Dispatchers are responsible for pulling incoming messages out of the underlying - Custom Message Transformations. Users can apply certain transformations to the message in the runtime (for example, for versioning). This can be accomplished, again, with the message interceptor interfaces. -- Custom Data Model. Users can have a data serialization model other than those supported by default in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] (namely, , , and raw messages). This can be done by implement the message formatter interfaces. For an example, see [Operation Formatter and Operation Selector](../../../../docs/framework/wcf/samples/operation-formatter-and-operation-selector.md). +- Custom Data Model. Users can have a data serialization model other than those supported by default in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] (namely, , , and raw messages). This can be done by implement the message formatter interfaces. For an example, see [Operation Formatter and Operation Selector](../../../../docs/framework/wcf/samples/operation-formatter-and-operation-selector.md). - Custom Parameter Validation. Users can enforce that typed parameters are valid (as opposed to XML). This can be done using the parameter inspector interfaces. diff --git a/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md b/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md index 89cf10e6430de..a481a5c4a6347 100644 --- a/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md +++ b/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md @@ -34,7 +34,7 @@ The service model layer is responsible for pulling incoming messages out of the To change settings on or insert extensions in the [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] runtime, you use Behaviors. WCF includes system-implemented behaviors for controlling throttling, instancing, and many other aspects of services and operations. This section describes how to create your own custom behaviors and how to make them available for use both programmatically and using configuration files. [Extending Hosting Using ServiceHostFactory](../../../../docs/framework/wcf/extending/extending-hosting-using-servicehostfactory.md) - Describes how to extend , , and use the classes to customize the host environment. + Describes how to extend , , and use the classes to customize the host environment. ## Reference diff --git a/docs/framework/wcf/extending/extending-the-metadata-system.md b/docs/framework/wcf/extending/extending-the-metadata-system.md index 2bd83c5ca23a3..67f6584807a3f 100644 --- a/docs/framework/wcf/extending/extending-the-metadata-system.md +++ b/docs/framework/wcf/extending/extending-the-metadata-system.md @@ -22,10 +22,10 @@ The [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] metadata system is a ## In This Section [Exporting Custom Metadata for a WCF Extension](../../../../docs/framework/wcf/extending/exporting-custom-metadata-for-a-wcf-extension.md) - Describes how to implement and use the interface to embed custom policy assertions in WSDL documents. + Describes how to implement and use the interface to embed custom policy assertions in WSDL documents. [Importing Custom Metadata for a WCF Extension](../../../../docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md) - Describes how to implement and use the interface to read and respond to custom policy assertions in WSDL documents. + Describes how to implement and use the interface to read and respond to custom policy assertions in WSDL documents. [Publishing and Retrieving Metadata Over a Custom Binding](../../../../docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md) Describes how to exchange metadata over custom bindings. diff --git a/docs/framework/wcf/extending/extensible-objects.md b/docs/framework/wcf/extending/extensible-objects.md index 8e8be0769fad0..1ce77ef884e45 100644 --- a/docs/framework/wcf/extending/extensible-objects.md +++ b/docs/framework/wcf/extending/extensible-objects.md @@ -40,7 +40,7 @@ where T : IExtensibleObject It is valid for implementations to restrict when they may be added and removed from an owner. For example, you can disallow removal entirely, disallowing adding or removing extensions when the owner or extension are in a certain state, disallow adding to multiple owners concurrently, or allow only a single addition followed by a single remove. - does not imply any interactions with other standard managed interfaces. Specifically, the method on the owner object does not normally detach its extensions. + does not imply any interactions with other standard managed interfaces. Specifically, the method on the owner object does not normally detach its extensions. When an extension is added to the collection, is called before it goes into the collection. When an extension is removed from the collection, is called after it is removed. This means (assuming appropriate synchronization) an extension can count on only being found in the collection while it is between and . @@ -52,7 +52,7 @@ where T : IExtensibleObject The second scenario uses the and properties to enable an object to participate in custom behavior, such as registering for events, watching state transitions, and so on. - The interface is a collection of the objects that allow for retrieving the by its type. returns the most recently added object that is an of that type. + The interface is a collection of the objects that allow for retrieving the by its type. returns the most recently added object that is an of that type. ### Extensible Objects in Windows Communication Foundation There are four extensible objects in [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)]: diff --git a/docs/framework/wcf/extending/handling-exceptions-and-faults.md b/docs/framework/wcf/extending/handling-exceptions-and-faults.md index fdb88d947dca3..b06145dde0c9d 100644 --- a/docs/framework/wcf/extending/handling-exceptions-and-faults.md +++ b/docs/framework/wcf/extending/handling-exceptions-and-faults.md @@ -22,7 +22,7 @@ Exceptions are used to communicate errors locally within the service or the clie There are two things to keep in mind when throwing an exception: First it has to be of a type that allows users to write correct code that can react appropriately to the exception. Second, it has to provide enough information for the user to understand what went wrong, the failure impact, and how to fix it. The following sections give guidance around exception types and messages for [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] channels. There is also general guidance around exceptions in .NET in the Design Guidelines for Exceptions document. ### Exception Types - All exceptions thrown by channels must be either a , , or a type derived from . (Exceptions such as may also be thrown, but only to indicate that the calling code has misused the channel. If a channel is used correctly, it must only throw the given exceptions.) [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] provides seven exception types that derive from and are designed to be used by channels. There are other -derived exceptions that are designed to be used by other parts of the system. These exception types are: + All exceptions thrown by channels must be either a , , or a type derived from . (Exceptions such as may also be thrown, but only to indicate that the calling code has misused the channel. If a channel is used correctly, it must only throw the given exceptions.) [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] provides seven exception types that derive from and are designed to be used by channels. There are other -derived exceptions that are designed to be used by other parts of the system. These exception types are: |Exception Type|Meaning|Inner Exception Content|Recovery Strategy| |--------------------|-------------|-----------------------------|-----------------------| @@ -52,7 +52,7 @@ Exceptions are used to communicate errors locally within the service or the clie ![Handling exceptions and faults](../../../../docs/framework/wcf/extending/media/wcfc-soap1-1andsoap1-2faultcomparisonc.gif "wcfc_SOAP1-1AndSOAP1-2FaultComparisonc") SOAP 1.2 Fault (left) and SOAP 1.1 Fault (right). Note that in SOAP 1.1 only the Fault element is namespace qualified. - SOAP defines a fault message as a message that contains only a fault element (an element whose name is ``) as a child of ``. The contents of the fault element differ slightly between SOAP 1.1 and SOAP 1.2 as shown in figure 1. However, the class normalizes these differences into one object model: + SOAP defines a fault message as a message that contains only a fault element (an element whose name is ``) as a child of ``. The contents of the fault element differ slightly between SOAP 1.1 and SOAP 1.2 as shown in figure 1. However, the class normalizes these differences into one object model: ``` public abstract class MessageFault @@ -313,9 +313,9 @@ public class MessageFault If a channel emits a header that is marked MustUnderstand = true, then that layer should also implement the Exception Generation API pattern and should convert `mustUnderstand` faults caused by that header to a more useful exception as described previously. ## Tracing - The .NET Framework provides a mechanism to trace program execution as a way to aid diagnosing production applications or intermittent problems where it is not possible to just attach a debugger and step through the code. The core components of this mechanism are in the namespace and consist of: + The .NET Framework provides a mechanism to trace program execution as a way to aid diagnosing production applications or intermittent problems where it is not possible to just attach a debugger and step through the code. The core components of this mechanism are in the namespace and consist of: -- , which is the source of trace information to be written, , which is an abstract base class for concrete listeners that receive the information to be traced from the and output it to a listener-specific destination. For example, outputs trace information to an XML file. Finally, , which lets the application user control the tracing verbosity and is typically specified in configuration. +- , which is the source of trace information to be written, , which is an abstract base class for concrete listeners that receive the information to be traced from the and output it to a listener-specific destination. For example, outputs trace information to an XML file. Finally, , which lets the application user control the tracing verbosity and is typically specified in configuration. - In addition to the core components, you can use the [Service Trace Viewer Tool (SvcTraceViewer.exe)](../../../../docs/framework/wcf/service-trace-viewer-tool-svctraceviewer-exe.md) to view and search [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] traces. The tool is designed specifically for trace files generated by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] and written out using . The following figure shows the various components involved in tracing. @@ -340,7 +340,7 @@ udpsource.TraceInformation("UdpInputChannel received a message"); > It is highly recommended that you specify a trace source name that is unique to your custom channel to help trace output readers understand where the output came from. #### Integrating with the Trace Viewer - Traces generated by your channel can be output in a format readable by the [Service Trace Viewer Tool (SvcTraceViewer.exe)](../../../../docs/framework/wcf/service-trace-viewer-tool-svctraceviewer-exe.md) by using as the trace listener. This is not something you, as the channel developer, need to do. Rather, it is the application user (or the person troubleshooting the application) that needs to configure this trace listener in the application’s configuration file. For example, the following configuration outputs trace information from both and `Microsoft.Samples.Udp` to the file named `TraceEventsFile.e2e`: + Traces generated by your channel can be output in a format readable by the [Service Trace Viewer Tool (SvcTraceViewer.exe)](../../../../docs/framework/wcf/service-trace-viewer-tool-svctraceviewer-exe.md) by using as the trace listener. This is not something you, as the channel developer, need to do. Rather, it is the application user (or the person troubleshooting the application) that needs to configure this trace listener in the application’s configuration file. For example, the following configuration outputs trace information from both and `Microsoft.Samples.Udp` to the file named `TraceEventsFile.e2e`: ```xml @@ -374,7 +374,7 @@ udpsource.TraceInformation("UdpInputChannel received a message"); ``` #### Tracing Structured Data - has a method that takes one or more objects that are to be included in the trace entry. In general, the method is called on each object and the resulting string is written as part of the trace entry. When using to output traces, you can pass an as the data object to . The resulting trace entry includes the XML provided by the . Here is an example entry with XML application data: + has a method that takes one or more objects that are to be included in the trace entry. In general, the method is called on each object and the resulting string is written as part of the trace entry. When using to output traces, you can pass an as the data object to . The resulting trace entry includes the XML provided by the . Here is an example entry with XML application data: ```xml diff --git a/docs/framework/wcf/extending/how-to-export-custom-policy-assertions.md b/docs/framework/wcf/extending/how-to-export-custom-policy-assertions.md index 3e3aab9308b63..9be5ccaf1c96c 100644 --- a/docs/framework/wcf/extending/how-to-export-custom-policy-assertions.md +++ b/docs/framework/wcf/extending/how-to-export-custom-policy-assertions.md @@ -18,15 +18,15 @@ manager: "erikre" # How to: Export Custom Policy Assertions Policy assertions describe the capabilities and requirements of a service endpoint. Service applications can use custom policy assertions in service metadata to communicate endpoint, binding or contract customization information to the client application. You can use [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] to export assertions in policy expressions attached in WSDL bindings at the endpoint, operation, or message subjects, depending upon the capabilities or requirements you are communicating. - Custom policy assertions are exported by implementing the interface on a and either inserting the binding element directly into the binding of the service endpoint or by registering the binding element in your application configuration file. Your policy export implementation should add your custom policy assertion as a instance to the appropriate on the passed into the method. + Custom policy assertions are exported by implementing the interface on a and either inserting the binding element directly into the binding of the service endpoint or by registering the binding element in your application configuration file. Your policy export implementation should add your custom policy assertion as a instance to the appropriate on the passed into the method. In addition you must check the property of the class and export nested policy expressions and policy framework attributes in the correct namespace based on the policy version specified. - To import custom policy assertions, see and [How to: Import Custom Policy Assertions](../../../../docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md). + To import custom policy assertions, see and [How to: Import Custom Policy Assertions](../../../../docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md). ### To export custom policy assertions -1. Implement the interface on a . The following code example shows the implementation of a custom policy assertion at the binding level. +1. Implement the interface on a . The following code example shows the implementation of a custom policy assertion at the binding level. [!code-csharp[CustomPolicySample#14](../../../../samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyexporter.cs#14)] [!code-vb[CustomPolicySample#14](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyexporter.vb#14)] @@ -35,17 +35,17 @@ Policy assertions describe the capabilities and requirements of a service endpoi ### To insert a binding element using an application configuration file -1. Implement for your custom policy assertion binding element. +1. Implement for your custom policy assertion binding element. 2. Add the binding element extension to the configuration file using the [\](../../../../docs/framework/configure-apps/file-schema/wcf/bindingelementextensions.md) element. -3. Build a custom binding using the . +3. Build a custom binding using the . ### To insert a binding element programmatically -1. Create a new and add it to a . +1. Create a new and add it to a . -2. Add the custom binding from step 1. to a new endpoint and add that new service endpoint to the by calling the method. +2. Add the custom binding from step 1. to a new endpoint and add that new service endpoint to the by calling the method. 3. Open the . The following code example shows the creation of a custom binding and the programmatic insertion of binding elements. diff --git a/docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md b/docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md index af2a77865f2e3..66fd00bf19290 100644 --- a/docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md +++ b/docs/framework/wcf/extending/how-to-import-custom-policy-assertions.md @@ -18,11 +18,11 @@ manager: "erikre" # How to: Import Custom Policy Assertions Policy assertions describe the capabilities and requirements of a service endpoint. Client applications can use policy assertions in service metadata to configure the client binding or to customize the service contract for a service endpoint. - Custom policy assertions are imported by implementing the interface and passing that object to the metadata system or by registering the implementation type in your application configuration file. Implementations of the interface must provide a default constructor. + Custom policy assertions are imported by implementing the interface and passing that object to the metadata system or by registering the implementation type in your application configuration file. Implementations of the interface must provide a default constructor. ### To import custom policy assertions -1. Implement the interface on a class. See the following procedures. +1. Implement the interface on a class. See the following procedures. 2. Insert the custom policy importer either by: @@ -34,16 +34,16 @@ Policy assertions describe the capabilities and requirements of a service endpoi ### To implement the System.ServiceModel.Description.IPolicyImportExtension interface on any class -1. In the method, for each policy subject that you are interested in, find the policy assertions that you want to import by calling the appropriate method (depending upon the scope of the assertion that you want) on the object passed to the method. The following code example shows how to use the method to locate the custom policy assertion and remove it from the collection in one step. If you use the remove method to locate and remove the assertion, you do not have to perform step 4. +1. In the method, for each policy subject that you are interested in, find the policy assertions that you want to import by calling the appropriate method (depending upon the scope of the assertion that you want) on the object passed to the method. The following code example shows how to use the method to locate the custom policy assertion and remove it from the collection in one step. If you use the remove method to locate and remove the assertion, you do not have to perform step 4. [!code-csharp[CustomPolicySample#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyimporter.cs#9)] [!code-vb[CustomPolicySample#9](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyimporter.vb#9)] 2. Process the policy assertions. Note that the policy system does not normalize nested policies and `wsp:optional`. You must process these constructs in your policy import extension implementation. -3. Perform the customization to the binding or contract that supports the capability or requirement specified by the policy assertion. Typically assertions indicate that a binding requires a particular configuration or a specific binding element. Make these modifications by accessing the property. Other assertions require that you modify the contract. You can access and modify the contract using the property. Note that your policy importer may get called multiple times for the same binding and contract, but different policy alternatives if importing a policy alternative fails. Your code should be resilient to this behavior. +3. Perform the customization to the binding or contract that supports the capability or requirement specified by the policy assertion. Typically assertions indicate that a binding requires a particular configuration or a specific binding element. Make these modifications by accessing the property. Other assertions require that you modify the contract. You can access and modify the contract using the property. Note that your policy importer may get called multiple times for the same binding and contract, but different policy alternatives if importing a policy alternative fails. Your code should be resilient to this behavior. -4. Remove the custom policy assertion from the assertion collection. If you do not remove the assertion [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] assumes that the policy import was unsuccessful and does not import the associated binding. If you used the method to locate the custom policy assertion and remove it from the collection in one step you do not have to perform this step. +4. Remove the custom policy assertion from the assertion collection. If you do not remove the assertion [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] assumes that the policy import was unsuccessful and does not import the associated binding. If you used the method to locate the custom policy assertion and remove it from the collection in one step you do not have to perform this step. ### To insert the custom policy importer into the metadata System using a configuration file @@ -51,7 +51,7 @@ Policy assertions describe the capabilities and requirements of a service endpoi [!code-xml[CustomPolicySample#7](../../../../samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/client.exe.config#7)] -2. In the client application, use the or to resolve the metadata and the importer is invoked automatically. +2. In the client application, use the or to resolve the metadata and the importer is invoked automatically. [!code-csharp[CustomPolicySample#10](../../../../samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/client.cs#10)] [!code-vb[CustomPolicySample#10](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/client.vb#10)] @@ -64,10 +64,10 @@ Policy assertions describe the capabilities and requirements of a service endpoi ### To insert the custom policy importer into the metadata system programmatically -1. Add the importer to the property (for example, if you are using the ) prior to importing the metadata. +1. Add the importer to the property (for example, if you are using the ) prior to importing the metadata. ## See Also - - - + + + [Extending the Metadata System](../../../../docs/framework/wcf/extending/extending-the-metadata-system.md) diff --git a/docs/framework/wcf/extending/how-to-inspect-and-modify-messages-on-the-service.md b/docs/framework/wcf/extending/how-to-inspect-and-modify-messages-on-the-service.md index bf510ca4473bd..439169f7fe8fb 100644 --- a/docs/framework/wcf/extending/how-to-inspect-and-modify-messages-on-the-service.md +++ b/docs/framework/wcf/extending/how-to-inspect-and-modify-messages-on-the-service.md @@ -16,15 +16,15 @@ ms.author: "erikre" manager: "erikre" --- # How to: Inspect and Modify Messages on the Service -You can inspect or modify the incoming or outgoing messages across a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client by implementing a and inserting it into the service runtime. For more information, see [Extending Dispatchers](../../../../docs/framework/wcf/extending/extending-dispatchers.md). The equivalent feature on the service is the . +You can inspect or modify the incoming or outgoing messages across a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client by implementing a and inserting it into the service runtime. For more information, see [Extending Dispatchers](../../../../docs/framework/wcf/extending/extending-dispatchers.md). The equivalent feature on the service is the . ### To inspect or modify messages -1. Implement the interface. +1. Implement the interface. -2. Implement a , , or interface depending upon the scope at which you want to easily insert your service message inspector. +2. Implement a , , or interface depending upon the scope at which you want to easily insert your service message inspector. -3. Insert your behavior prior to calling the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). +3. Insert your behavior prior to calling the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). ## Example The following code examples show, in order: @@ -44,6 +44,6 @@ You can inspect or modify the incoming or outgoing messages across a [!INCLUDE[i [!code-xml[Interceptors#9](../../../../samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/hostapplication.exe.config#9)] ## See Also - - + + [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md) diff --git a/docs/framework/wcf/extending/how-to-inspect-or-modify-messages-on-the-client.md b/docs/framework/wcf/extending/how-to-inspect-or-modify-messages-on-the-client.md index e5b0250d8bdb4..8a650ca1c8da6 100644 --- a/docs/framework/wcf/extending/how-to-inspect-or-modify-messages-on-the-client.md +++ b/docs/framework/wcf/extending/how-to-inspect-or-modify-messages-on-the-client.md @@ -16,15 +16,15 @@ ms.author: "erikre" manager: "erikre" --- # How to: Inspect or Modify Messages on the Client -You can inspect or modify the incoming or outgoing messages across a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client by implementing a and inserting it into the client runtime. For more information, see [Extending Clients](../../../../docs/framework/wcf/extending/extending-clients.md). The equivalent feature on the service is the . For a complete code example see the [Message Inspectors](../../../../docs/framework/wcf/samples/message-inspectors.md) sample. +You can inspect or modify the incoming or outgoing messages across a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client by implementing a and inserting it into the client runtime. For more information, see [Extending Clients](../../../../docs/framework/wcf/extending/extending-clients.md). The equivalent feature on the service is the . For a complete code example see the [Message Inspectors](../../../../docs/framework/wcf/samples/message-inspectors.md) sample. ### To inspect or modify messages -1. Implement the interface. +1. Implement the interface. -2. Implement a or depending upon the scope at which you want to insert the client message inspector. allows you to change behavior at the endpoint level. allows you to change behavior at the contract level. +2. Implement a or depending upon the scope at which you want to insert the client message inspector. allows you to change behavior at the endpoint level. allows you to change behavior at the contract level. -3. Insert the behavior prior to calling the or the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). +3. Insert the behavior prior to calling the or the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). ## Example The following code examples show, in order: @@ -132,6 +132,6 @@ public class SimpleBehaviorExtensionElement : BehaviorExtensionElement ``` ## See Also - - + + [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md) diff --git a/docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md b/docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md index 835771fc7b092..eaf4c0a51ebd3 100644 --- a/docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md +++ b/docs/framework/wcf/extending/how-to-inspect-or-modify-parameters.md @@ -16,22 +16,22 @@ ms.author: "erikre" manager: "erikre" --- # How to: Inspect or Modify Parameters -You can inspect or modify the incoming or outgoing messages for a single operation on a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client object or a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service by implementing the interface and inserting it into the client or service runtime. Typically an operation behavior is used to add parameter inspectors for a single operation; other behaviors can be used to provide easy access to the runtime at a greater scope. For more information, see [Extending Clients](../../../../docs/framework/wcf/extending/extending-clients.md) and [Extending Dispatchers](../../../../docs/framework/wcf/extending/extending-dispatchers.md). +You can inspect or modify the incoming or outgoing messages for a single operation on a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client object or a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service by implementing the interface and inserting it into the client or service runtime. Typically an operation behavior is used to add parameter inspectors for a single operation; other behaviors can be used to provide easy access to the runtime at a greater scope. For more information, see [Extending Clients](../../../../docs/framework/wcf/extending/extending-clients.md) and [Extending Dispatchers](../../../../docs/framework/wcf/extending/extending-dispatchers.md). ### Inspecting or Modifying Parameters -1. Implement the interface. +1. Implement the interface. -2. Implement a , , or (depending upon the required scope) to add your parameter inspector to either the or properties. +2. Implement a , , or (depending upon the required scope) to add your parameter inspector to either the or properties. -3. Insert your behavior prior to calling or the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). +3. Insert your behavior prior to calling or the method on the . For details, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). ## Example The following code examples show, in order: - A parameter inspector implementation. -- The behavior implementation that inserts the parameter inspector using a , , and an . +- The behavior implementation that inserts the parameter inspector using a , , and an . - A configuration file that loads and runs the endpoint behavior in a client application to insert the parameter inspector on the client. diff --git a/docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md b/docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md index 855b0aab41e29..a06f450c44634 100644 --- a/docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md +++ b/docs/framework/wcf/extending/how-to-lock-down-endpoints-in-the-enterprise.md @@ -47,7 +47,7 @@ Large enterprises often require that applications are developed in compliance wi 2. Install the strongly-named assembly into the global assembly cache using the [Gacutil.exe (Global Assembly Cache Tool)](http://msdn.microsoft.com/library/ex0ss12c\(v=vs.110\).aspx). -3. Use the namespace types to: +3. Use the namespace types to: 1. Add the extension to the [\](../../../../docs/framework/configure-apps/file-schema/wcf/behaviorextensions.md) section using a fully-qualified type name and lock the element. diff --git a/docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md b/docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md index 4f40ddd8dcba9..07366adb3702f 100644 --- a/docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md +++ b/docs/framework/wcf/extending/importing-custom-metadata-for-a-wcf-extension.md @@ -16,20 +16,20 @@ ms.author: "erikre" manager: "erikre" --- # Importing Custom Metadata for a WCF Extension -In [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)], metadata import is the process of generating an abstract representation of a service or its component parts from its metadata. For example, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] can import instances, instances or instances from a WSDL document for a service. To import service metadata in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], use an implementation of the abstract class. Types that derive from the class implement support for importing metadata formats that take advantage of the WS-Policy import logic in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. +In [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)], metadata import is the process of generating an abstract representation of a service or its component parts from its metadata. For example, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] can import instances, instances or instances from a WSDL document for a service. To import service metadata in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], use an implementation of the abstract class. Types that derive from the class implement support for importing metadata formats that take advantage of the WS-Policy import logic in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. Custom metadata consists of XML elements that the system-provided metadata importers cannot import. Typically, this includes custom WSDL extensions and custom policy assertions. This section describes how to import custom WSDL extensions and policy assertions. It does not focus on the importing process itself. For more information about how to use the types that export and import metadata regardless of whether the metadata is custom or system-supported, see [Exporting and Importing Metadata](../../../../docs/framework/wcf/feature-details/exporting-and-importing-metadata.md). ## Overview - The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The type imports WSDL metadata with attached policies that are bundled in a object. Policy assertions and WSDL extensions that the default importers do not recognize are passed to any registered custom policy and WSDL importers for importing. Typically, importers are implemented to support user-defined binding elements or to modify the imported contract. + The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The type imports WSDL metadata with attached policies that are bundled in a object. Policy assertions and WSDL extensions that the default importers do not recognize are passed to any registered custom policy and WSDL importers for importing. Typically, importers are implemented to support user-defined binding elements or to modify the imported contract. This section describes: -1. How to implement and use the interface, which exposes the WSDL data to custom importers prior to the generation of descriptions and the generation of code. You can use this interface to examine or modify the description types and code compilation performed using a given set of metadata. +1. How to implement and use the interface, which exposes the WSDL data to custom importers prior to the generation of descriptions and the generation of code. You can use this interface to examine or modify the description types and code compilation performed using a given set of metadata. -2. How to implement and use the interface, which exposes policy assertions to importers prior to the generation of description objects. You can use this interface to examine or modify the binding or contract based on the downloaded policies. +2. How to implement and use the interface, which exposes policy assertions to importers prior to the generation of description objects. You can use this interface to examine or modify the binding or contract based on the downloaded policies. For more information about exporting custom WSDL and policy assertions, see [Exporting Custom Metadata for a WCF Extension](../../../../docs/framework/wcf/extending/exporting-custom-metadata-for-a-wcf-extension.md). @@ -45,7 +45,7 @@ In [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)], metadata import is t To add support for importing custom policy assertions, implement the interface and then add your implementation to the property. The can also load implementations of the interface registered in your application configuration file. Note that a number of policy importers are registered by default and the order of the registered policy importers is significant. - The metadata system repeatedly calls the method on all registered policy import extensions for each combination of policy alternatives attached to the message, operation, and endpoint policy subjects. When importing a WSDL port, policies attached to the port and to the corresponding WSDL binding are merged before calling into the policy import extensions. The policy alternatives are made available through a as objects. Each is a collection of policy assertions represented by objects. + The metadata system repeatedly calls the method on all registered policy import extensions for each combination of policy alternatives attached to the message, operation, and endpoint policy subjects. When importing a WSDL port, policies attached to the port and to the corresponding WSDL binding are merged before calling into the policy import extensions. The policy alternatives are made available through a as objects. Each is a collection of policy assertions represented by objects. The and properties on the object expose the and objects that were imported from the WSDL. Policy import extensions process policy assertions by finding instances of a particular policy assertion type, making corresponding changes to the or objects and then removing the policy assertions from the corresponding instance. diff --git a/docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md b/docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md index 1d2dbcf344c44..6ac162778f3f2 100644 --- a/docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md +++ b/docs/framework/wcf/extending/publishing-and-retrieving-metadata-over-a-custom-binding.md @@ -16,17 +16,17 @@ ms.author: "erikre" manager: "erikre" --- # Publishing and Retrieving Metadata Over a Custom Binding -The provides support for adding metadata endpoint to a service. These metadata endpoints can respond to HTTP GET requests at a URL that has a `?wsdl` querystring and to WS-Transfer GET requests as defined in the WS-MetadataExchange (MEX) specification. MEX endpoints implement the contract. +The provides support for adding metadata endpoint to a service. These metadata endpoints can respond to HTTP GET requests at a URL that has a `?wsdl` querystring and to WS-Transfer GET requests as defined in the WS-MetadataExchange (MEX) specification. MEX endpoints implement the contract. ## Publishing Metadata Over a Custom Binding - The HTTP GET metadata endpoints and HTTPS GET metadata endpoints are enabled by setting the or properties to `true`. The bindings for these endpoints cannot be configured. + The HTTP GET metadata endpoints and HTTPS GET metadata endpoints are enabled by setting the or properties to `true`. The bindings for these endpoints cannot be configured. - The contract, however, can be used with any endpoint, including those that use custom bindings, because endpoints are identical to any other [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] service endpoint. If you know how to modify the configuration of a system-provided binding, or you know how to configure a , then you can configure a binding for use with an endpoint. + The contract, however, can be used with any endpoint, including those that use custom bindings, because endpoints are identical to any other [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] service endpoint. If you know how to modify the configuration of a system-provided binding, or you know how to configure a , then you can configure a binding for use with an endpoint. ## Retrieving Metadata Over a Custom Binding Metadata can be retrieved from HTTP Get and HTTPS Get metadata endpoints using standard HTTP or HTTPS GET requests. - To retrieve metadata from a MEX metadata endpoint you can generally use one of the standard MEX bindings supported by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)]. The type and the Svcutil.exe tool automatically select one of these standard MEX bindings based on the address of the specified metadata endpoint. + To retrieve metadata from a MEX metadata endpoint you can generally use one of the standard MEX bindings supported by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)]. The type and the Svcutil.exe tool automatically select one of these standard MEX bindings based on the address of the specified metadata endpoint. If a MEX metadata endpoint uses a different binding than one of the standard MEX bindings, you can configure the binding used by the using code or by providing an client endpoint configuration. The Svcutil.exe tool automatically loads from its configuration file an client endpoint configuration that has the same name as the URI scheme for the metadata endpoint address. diff --git a/docs/framework/wcf/extending/service-channel-level-programming.md b/docs/framework/wcf/extending/service-channel-level-programming.md index 3d8015ee18ed0..6de3df95d6467 100644 --- a/docs/framework/wcf/extending/service-channel-level-programming.md +++ b/docs/framework/wcf/extending/service-channel-level-programming.md @@ -16,7 +16,7 @@ ms.author: "erikre" manager: "erikre" --- # Service Channel-Level Programming -This topic describes how to write a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] service application without using the and its associated object model. +This topic describes how to write a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] service application without using the and its associated object model. ## Receiving Messages To be ready to receive and process messages, the following steps are required: @@ -34,21 +34,21 @@ This topic describes how to write a [!INCLUDE[indigo1](../../../../includes/indi #### Creating a Binding The first step in listening for and receiving messages is creating a binding. [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] ships with several built-in or system-provided bindings that can be used directly by instantiating one of them. In addition, you can also create your own custom binding by instantiating a CustomBinding class which is what the code in listing 1 does. - The code example below creates an instance of and adds an to its Elements collection which is a collection of binding elements that are used to build the channel stack. In this example, because the elements collection has only the , the resulting channel stack has only the HTTP transport channel. + The code example below creates an instance of and adds an to its Elements collection which is a collection of binding elements that are used to build the channel stack. In this example, because the elements collection has only the , the resulting channel stack has only the HTTP transport channel. #### Building a ChannelListener - After creating a binding, we call `System.ServiceModel.Channels.Binding.BuildChannelListener` to build the channel listener where the type parameter is the channel shape to create. In this example we are using because we want to listen for incoming messages in a request/reply message exchange pattern. + After creating a binding, we call `System.ServiceModel.Channels.Binding.BuildChannelListener` to build the channel listener where the type parameter is the channel shape to create. In this example we are using because we want to listen for incoming messages in a request/reply message exchange pattern. - is used for receiving request messages and sending back reply messages. Calling returns an , which can be used to receive the request message and to send back a reply message. + is used for receiving request messages and sending back reply messages. Calling returns an , which can be used to receive the request message and to send back a reply message. When creating the listener, we pass the network address on which it listens, in this case `http://localhost:8080/channelapp`. In general, each transport channel supports one or possibly several address schemes, for example, the HTTP transport supports both http and https schemes. - We also pass an empty when creating the listener. A binding parameter is a mechanism to pass parameters that control how the listener should be built. In our example, we are not using any such parameters so we pass an empty collection. + We also pass an empty when creating the listener. A binding parameter is a mechanism to pass parameters that control how the listener should be built. In our example, we are not using any such parameters so we pass an empty collection. #### Listening for Incoming Messages - We then call on the listener and start accepting channels. The behavior of depends on whether the transport is connection-oriented or connection-less. For connection-oriented transports, blocks until a new connection request comes in at which point it returns a new channel that represents that new connection. For connection-less transports, such as HTTP, returns immediately with the one and only channel that the transport listener creates. + We then call on the listener and start accepting channels. The behavior of depends on whether the transport is connection-oriented or connection-less. For connection-oriented transports, blocks until a new connection request comes in at which point it returns a new channel that represents that new connection. For connection-less transports, such as HTTP, returns immediately with the one and only channel that the transport listener creates. - In this example, the listener returns a channel that implements . To receive messages on this channel we first call on it to place it in a state ready for communication. We then call which blocks until a message arrives. + In this example, the listener returns a channel that implements . To receive messages on this channel we first call on it to place it in a state ready for communication. We then call which blocks until a message arrives. #### Reading the Request and Sending a Reply When returns a , we get the received message using its property. We write out the message’s action and body content, (which we assume is a string). diff --git a/docs/framework/wcf/extending/understanding-state-changes.md b/docs/framework/wcf/extending/understanding-state-changes.md index 40906327bd5fd..765e5d00f590f 100644 --- a/docs/framework/wcf/extending/understanding-state-changes.md +++ b/docs/framework/wcf/extending/understanding-state-changes.md @@ -52,13 +52,13 @@ Figure 2. The CommunicationObject implementation of the ICommunicationObject sta ### Derived Object Callbacks In addition to the five events, declares eight protected virtual methods designed to allow a derived object to be called back before and after state transitions occur. - The and methods have three such callbacks associated with each of them. For example, corresponding to there is , , and . Associated with are the , , and methods. + The and methods have three such callbacks associated with each of them. For example, corresponding to there is , , and . Associated with are the , , and methods. - Similarly, the method has a corresponding . + Similarly, the method has a corresponding . - While , , and have no default implementation, the other callbacks do have a default implementation which is necessary for state machine correctness. If you override those methods be sure to call the base implementation or correctly replace it. + While , , and have no default implementation, the other callbacks do have a default implementation which is necessary for state machine correctness. If you override those methods be sure to call the base implementation or correctly replace it. - , and fire the corresponding , and events. and set the object state to Opened and Closed respectively then fire the corresponding and events. + , and fire the corresponding , and events. and set the object state to Opened and Closed respectively then fire the corresponding and events. ### State Transition Methods provides implementations of Abort, Close and Open. It also provides a Fault method which causes a state transition to the Faulted state. Figure 2 shows the state machine with each transition labeled by the method that causes it (unlabeled transitions happen inside the implementation of the method that caused the last labeled transition). @@ -143,14 +143,14 @@ Override the OnAbort method to implement custom terminate logic such as terminat |State|Has Abort been called?|Exception| |-----------|----------------------------|---------------| -|Created|N/A|| -|Opening|N/A|| -|Opened|N/A|| -|Closing|Yes|| -|Closing|No|| -|Closed|Yes| in the case that an object was closed by a previous and explicit call of Abort. If you call Close on the object then an is thrown.| -|Closed|No|| -|Faulted|N/A|| +|Created|N/A|| +|Opening|N/A|| +|Opened|N/A|| +|Closing|Yes|| +|Closing|No|| +|Closed|Yes| in the case that an object was closed by a previous and explicit call of Abort. If you call Close on the object then an is thrown.| +|Closed|No|| +|Faulted|N/A|| ### Timeouts Several of the methods we discussed take timeout parameters. These are Close, Open (certain overloads and asynchronous versions), OnClose and OnOpen. These methods are designed to allow for lengthy operations (for example, blocking on input/output while gracefully closing down a connection) so the timeout parameter indicates how long such operations can take before being interrupted. Implementations of any of these methods should use the supplied timeout value to ensure it returns to the caller within that timeout. Implementations of other methods that do not take a timeout are not designed for lengthy operations and should not block on input/output. diff --git a/docs/framework/wcf/feature-details/accessing-services-using-a-client.md b/docs/framework/wcf/feature-details/accessing-services-using-a-client.md index 008712dc451a4..3b2a6650998d5 100644 --- a/docs/framework/wcf/feature-details/accessing-services-using-a-client.md +++ b/docs/framework/wcf/feature-details/accessing-services-using-a-client.md @@ -41,12 +41,12 @@ Client applications must create, configure, and use [!INCLUDE[indigo2](../../../ Open clients explicitly or implicitly by calling the first operation. > [!NOTE] -> Trying to explicitly detect faulted sessionful channels is not typically useful, because when you are notified depends upon the session implementation. For example, because the (with the reliable session disabled) surfaces the session of the TCP connection, if you listen to the event on the service or the client you are likely to be notified quickly in the event of a network failure. But reliable sessions (established by bindings in which the is enabled) are designed to insulate services from small network failures. If the session can be reestablished within a reasonable period of time, the same binding—configured for reliable sessions—might not fault until the interruption continued for a longer period of time. +> Trying to explicitly detect faulted sessionful channels is not typically useful, because when you are notified depends upon the session implementation. For example, because the (with the reliable session disabled) surfaces the session of the TCP connection, if you listen to the event on the service or the client you are likely to be notified quickly in the event of a network failure. But reliable sessions (established by bindings in which the is enabled) are designed to insulate services from small network failures. If the session can be reestablished within a reasonable period of time, the same binding—configured for reliable sessions—might not fault until the interruption continued for a longer period of time. - Most of the system-provided bindings (which expose channels to the application layer) use sessions by default, but the does not. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Using Sessions](../../../../docs/framework/wcf/using-sessions.md). + Most of the system-provided bindings (which expose channels to the application layer) use sessions by default, but the does not. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Using Sessions](../../../../docs/framework/wcf/using-sessions.md). ### The Proper Use of Sessions - Sessions provide a way to know if the entire message exchange is complete, and if both sides considered it successful. It is recommended that a calling application open the channel, use it, and close the channel inside one try block. If a session channel is open, and the method is called once, and that call returns successfully, then the session was successful. Successful in this case means that all delivery guarantees the binding specified were met, and the other side did not call on the channel before calling . + Sessions provide a way to know if the entire message exchange is complete, and if both sides considered it successful. It is recommended that a calling application open the channel, use it, and close the channel inside one try block. If a session channel is open, and the method is called once, and that call returns successfully, then the session was successful. Successful in this case means that all delivery guarantees the binding specified were met, and the other side did not call on the channel before calling . The following section provides an example of this client approach. @@ -62,14 +62,14 @@ Client applications must create, configure, and use [!INCLUDE[indigo2](../../../ [!code-vb[FaultContractAttribute#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/client.vb#3)] > [!NOTE] -> Checking the value of the property is a race condition and is not recommended to determine whether to reuse or close a channel. +> Checking the value of the property is a race condition and is not recommended to determine whether to reuse or close a channel. - Datagram channels never fault even if exceptions occur when they are closed. In addition, non-duplex clients that fail to authenticate using a secure conversation typically throw a . However if the duplex client using a secure conversation fails to authenticate, the client receives a instead. + Datagram channels never fault even if exceptions occur when they are closed. In addition, non-duplex clients that fail to authenticate using a secure conversation typically throw a . However if the duplex client using a secure conversation fails to authenticate, the client receives a instead. For more complete information about working with error information at the application level, see [Specifying and Handling Faults in Contracts and Services](../../../../docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md). [Expected Exceptions](../../../../docs/framework/wcf/samples/expected-exceptions.md) describes expected exceptions and shows how to handle them. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] how to handle errors when developing channels, see [Handling Exceptions and Faults](../../../../docs/framework/wcf/extending/handling-exceptions-and-faults.md). ### Client Blocking and Performance - When an application synchronously calls a request-reply operation, the client blocks until a return value is received or an exception (such as a ) is thrown. This behavior is similar to local behavior. When an application synchronously invokes an operation on a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client object or channel, the client does not return until the channel layer can write the data to the network or until an exception is thrown. And while the one-way message exchange pattern (specified by marking an operation with set to `true`) can make some clients more responsive, one-way operations can also block, depending upon the binding and what messages have already been sent. One-way operations are only about the message exchange, no more and no less. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][One-Way Services](../../../../docs/framework/wcf/feature-details/one-way-services.md). + When an application synchronously calls a request-reply operation, the client blocks until a return value is received or an exception (such as a ) is thrown. This behavior is similar to local behavior. When an application synchronously invokes an operation on a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client object or channel, the client does not return until the channel layer can write the data to the network or until an exception is thrown. And while the one-way message exchange pattern (specified by marking an operation with set to `true`) can make some clients more responsive, one-way operations can also block, depending upon the binding and what messages have already been sent. One-way operations are only about the message exchange, no more and no less. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][One-Way Services](../../../../docs/framework/wcf/feature-details/one-way-services.md). Large data chunks can slow client processing no matter what the message exchange pattern. To understand how to handle these issues, see [Large Data and Streaming](../../../../docs/framework/wcf/feature-details/large-data-and-streaming.md). @@ -80,15 +80,15 @@ Client applications must create, configure, and use [!INCLUDE[indigo2](../../../ ### Enabling the User to Select Credentials Dynamically The interface enables applications to display a user interface that enables the user to choose credentials with which a channel is created before the timeout timers start. - Application developers can make use of an inserted in two ways. The client application can call either or (or an asynchronous version) prior to opening the channel (the *explicit* approach) or call the first operation (the *implicit* approach). + Application developers can make use of an inserted in two ways. The client application can call either or (or an asynchronous version) prior to opening the channel (the *explicit* approach) or call the first operation (the *implicit* approach). If using the implicit approach, the application must call the first operation on a or extension. If it calls anything other than the first operation, an exception is thrown. If using the explicit approach, the application must perform the following steps in order: -1. Call either or (or an asynchronous version). +1. Call either or (or an asynchronous version). -2. When the initializers have returned, call either the method on the object or on the object returned from the property. +2. When the initializers have returned, call either the method on the object or on the object returned from the property. 3. Call operations. diff --git a/docs/framework/wcf/feature-details/choosing-a-message-encoder.md b/docs/framework/wcf/feature-details/choosing-a-message-encoder.md index d0417e9e2bec6..2a2d0a6f10bb0 100644 --- a/docs/framework/wcf/feature-details/choosing-a-message-encoder.md +++ b/docs/framework/wcf/feature-details/choosing-a-message-encoder.md @@ -69,7 +69,7 @@ The IgnoreWhitespace setting is ignored. ## Compression and the Binary Encoder -Beginning with WCF 4.5 the WCF binary encoder adds support for compression. This enables you to use the gzip/deflate algorithm for sending compressed messages from a WCF client and also respond with compressed messages from a self-hosted WCF service. This feature enables compression on both the HTTP and TCP transports. An IIS hosted WCF service can always be enabled for sending compressed responses by configuring the IIS host server. The type of compression is configured with the property. This property is set to one of the enum values: +Beginning with WCF 4.5 the WCF binary encoder adds support for compression. This enables you to use the gzip/deflate algorithm for sending compressed messages from a WCF client and also respond with compressed messages from a self-hosted WCF service. This feature enables compression on both the HTTP and TCP transports. An IIS hosted WCF service can always be enabled for sending compressed responses by configuring the IIS host server. The type of compression is configured with the property. This property is set to one of the enum values: * `CompressionFormat.Deflate` * `CompressionFormat.GZip` diff --git a/docs/framework/wcf/feature-details/client-architecture.md b/docs/framework/wcf/feature-details/client-architecture.md index 28145a42de2b9..6911cbc2d2458 100644 --- a/docs/framework/wcf/feature-details/client-architecture.md +++ b/docs/framework/wcf/feature-details/client-architecture.md @@ -23,25 +23,25 @@ Applications use [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client - An automatically generated client implementation of a service contract, which turns calls from your application code into outgoing messages, and turns response messages into output parameters and return values that your application can retrieve. -- An implementation of a control interface () that groups together various interfaces and provides access to control functionality, most notably the ability to close the client session and dispose the channel. +- An implementation of a control interface () that groups together various interfaces and provides access to control functionality, most notably the ability to close the client session and dispose the channel. - A client channel that is built based on the configuration settings specified by the used binding. - Applications can create such clients on demand, either through a or by creating an instance of a derived class as it is generated by the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md). These ready-built client classes encapsulate and delegate to a client channel implementation that is dynamically constructed by a . Therefore, the client channel and the channel factory that produces them are the focal point of interest for this discussion. + Applications can create such clients on demand, either through a or by creating an instance of a derived class as it is generated by the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md). These ready-built client classes encapsulate and delegate to a client channel implementation that is dynamically constructed by a . Therefore, the client channel and the channel factory that produces them are the focal point of interest for this discussion. ## Client Objects and Client Channels - The base interface of [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] clients is the interface, which exposes core client functionality as well as the basic communication object functionality of , the context functionality of , and the extensible behavior of . + The base interface of [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] clients is the interface, which exposes core client functionality as well as the basic communication object functionality of , the context functionality of , and the extensible behavior of . - The interface, however, does not define a service contract itself. Those are declared by the service contract interface (typically generated from service metadata using a tool like the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md)). [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client types extend both and the target service contract interface to enable applications to call operations directly and also have access to client-side run-time functionality. Creating an [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client provides [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] objects with the information necessary to create a run time that can connect and interact with the configured service endpoint. + The interface, however, does not define a service contract itself. Those are declared by the service contract interface (typically generated from service metadata using a tool like the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md)). [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client types extend both and the target service contract interface to enable applications to call operations directly and also have access to client-side run-time functionality. Creating an [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client provides [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] objects with the information necessary to create a run time that can connect and interact with the configured service endpoint. As mentioned earlier, the two [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client types must be configured before you can use them. The simplest [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client types are objects that derive from (or if the service contract is a duplex contract). You can create these types by using a constructor, configured programmatically, or by using a configuration file, and then called directly to invoke service operations. For a basic overview of objects, see [WCF Client Overview](../../../../docs/framework/wcf/wcf-client-overview.md). The second type is generated at run time from a call to the method. Applications concerned with tight control of the communication specifics typically use this client type, called a *client channel object*, because it enables more direct interaction than the underlying client run-time and channel system. ## Channel Factories - The class that is responsible for creating the underlying run time that supports client invocations is the class. Both [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client objects and [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client channel objects use a object to create instances; the derived client object encapsulates the handling of the channel factory, but for a number of scenarios it is perfectly reasonable to use the channel factory directly. The common scenario for this is if you want to repeatedly create new client channels from an existing factory. If you are using a client object, you can obtain the underlying channel factory from a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client object by calling the property. + The class that is responsible for creating the underlying run time that supports client invocations is the class. Both [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client objects and [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client channel objects use a object to create instances; the derived client object encapsulates the handling of the channel factory, but for a number of scenarios it is perfectly reasonable to use the channel factory directly. The common scenario for this is if you want to repeatedly create new client channels from an existing factory. If you are using a client object, you can obtain the underlying channel factory from a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client object by calling the property. - The important thing to remember about channel factories is that they create new instances of client channels for the configuration provided to them prior to calling . Once you call (or , , or any operation on a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client object), you cannot modify the channel factory and expect to get channels to different service instances, even if you are merely changing the target endpoint address. If you want to create a client object or client channel with a different configuration, you must create a new channel factory first. + The important thing to remember about channel factories is that they create new instances of client channels for the configuration provided to them prior to calling . Once you call (or , , or any operation on a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client object), you cannot modify the channel factory and expect to get channels to different service instances, even if you are merely changing the target endpoint address. If you want to create a client object or client channel with a different configuration, you must create a new channel factory first. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] various issues using [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client objects and [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client channels, see [Accessing Services Using a WCF Client](../../../../docs/framework/wcf/feature-details/accessing-services-using-a-client.md). @@ -59,7 +59,7 @@ Applications use [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client [!code-csharp[C_GeneratedCodeFiles#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#13)] #### Creating a New WCF Client Channel Object - To use a client channel to connect to an `ISampleService` service, use the generated contract interface (or the helper version) directly with a channel factory, passing the type of the contract interface as the type parameter. Once a channel factory for a particular contract has been created and configured, you can call the method to return client channel objects that you can use to communicate with an `ISampleService` service. + To use a client channel to connect to an `ISampleService` service, use the generated contract interface (or the helper version) directly with a channel factory, passing the type of the contract interface as the type parameter. Once a channel factory for a particular contract has been created and configured, you can call the method to return client channel objects that you can use to communicate with an `ISampleService` service. When created, the client channel objects implement and the contract interface. Therefore, you can use them directly to call operations that interact with a service that supports that contract. diff --git a/docs/framework/wcf/feature-details/config-wcf-service-with-aspnet-web-service.md b/docs/framework/wcf/feature-details/config-wcf-service-with-aspnet-web-service.md index 53f25bdbcf20a..5efed120ec644 100644 --- a/docs/framework/wcf/feature-details/config-wcf-service-with-aspnet-web-service.md +++ b/docs/framework/wcf/feature-details/config-wcf-service-with-aspnet-web-service.md @@ -16,9 +16,9 @@ ms.author: "erikre" manager: "erikre" --- # How to: Configure WCF Service to Interoperate with ASP.NET Web Service Clients -To configure a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] service endpoint to be interoperable with [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] Web service clients, use the type as the binding type for your service endpoint. +To configure a [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] service endpoint to be interoperable with [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] Web service clients, use the type as the binding type for your service endpoint. - You can optionally enable support for HTTPS and transport-level client authentication on the binding. [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] Web service clients do not support MTOM message encoding, so the property should be left as its default value, which is . ASP.Net Web Service clients do not support WS-Security, so the should be set to . + You can optionally enable support for HTTPS and transport-level client authentication on the binding. [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] Web service clients do not support MTOM message encoding, so the property should be left as its default value, which is . ASP.Net Web Service clients do not support WS-Security, so the should be set to . To make the metadata for a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service available to [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] Web service proxy generation tools (that is, [Web Services Description Language Tool (Wsdl.exe)](http://go.microsoft.com/fwlink/?LinkId=73833), [Web Services Discovery Tool (Disco.exe)](http://go.microsoft.com/fwlink/?LinkId=73834), and the Add Web Reference feature in Visual Studio), you should expose an HTTP/GET metadata endpoint. diff --git a/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md b/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md index 4fed0a29072dd..53a1f4b5da98b 100644 --- a/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md +++ b/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md @@ -63,7 +63,7 @@ manager: "erikre" > When the client and service are running on the same computer and the client is running under a system account (for example, `Local System` or `Network Service`), the client cannot be impersonated when a secure session is established with stateful Security Context tokens. A Windows Form or console application typically runs under the currently logged-in account, so that account can be impersonated by default. However, when the client is an [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] page and that page is hosted in [!INCLUDE[iis601](../../../../includes/iis601-md.md)] or [!INCLUDE[iisver](../../../../includes/iisver-md.md)], then the client does run under the `Network Service` account by default. All of the system-provided bindings that support secure sessions use a stateless security context token (SCT) by default. However, if the client is an [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] page, and secure sessions with stateful SCTs are used, the client cannot be impersonated. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] using stateful SCTs in a secure session, see [How to: Create a Security Context Token for a Secure Session](../../../../docs/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session.md). ## Impersonation in a Service Method: Declarative Model - Most impersonation scenarios involve executing the service method in the caller context. [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] provides an impersonation feature that makes this easy to do by allowing the user to specify the impersonation requirement in the attribute. For example, in the following code, the [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] infrastructure impersonates the caller before executing the `Hello` method. Any attempt to access native resources inside the `Hello` method succeed only if the access control list (ACL) of the resource allows the caller access privileges. To enable impersonation, set the property to one of the enumeration values, either or , as shown in the following example. + Most impersonation scenarios involve executing the service method in the caller context. [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] provides an impersonation feature that makes this easy to do by allowing the user to specify the impersonation requirement in the attribute. For example, in the following code, the [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] infrastructure impersonates the caller before executing the `Hello` method. Any attempt to access native resources inside the `Hello` method succeed only if the access control list (ACL) of the resource allows the caller access privileges. To enable impersonation, set the property to one of the enumeration values, either or , as shown in the following example. > [!NOTE] > When a service has higher credentials than the remote client, the credentials of the service are used if the property is set to . That is, if a low-privileged user provides its credentials, a higher-privileged service executes the method with the credentials of the service, and can use resources that the low-privileged user would otherwise not be able to use. diff --git a/docs/framework/wcf/feature-details/discovery-find-and-findcriteria.md b/docs/framework/wcf/feature-details/discovery-find-and-findcriteria.md index 5b1de7c07be96..20567a2971ace 100644 --- a/docs/framework/wcf/feature-details/discovery-find-and-findcriteria.md +++ b/docs/framework/wcf/feature-details/discovery-find-and-findcriteria.md @@ -32,15 +32,15 @@ A discovery find operation is initiated by a client to discover one or more serv - - Specifies the matching algorithm to use while matching the scopes in the Probe message with that of the endpoint. There are five supported scope-matching rules: - - does a basic case-sensitive string comparison. + - does a basic case-sensitive string comparison. - - matches by segments separated by "/". A search for http://contoso/building1 matches a service with scope http://contoso/building/floor1. Note that it does not match http://contoso/building100 because the last two segments do not match. + - matches by segments separated by "/". A search for http://contoso/building1 matches a service with scope http://contoso/building/floor1. Note that it does not match http://contoso/building100 because the last two segments do not match. - - matches scopes by segments using an LDAP URL. + - matches scopes by segments using an LDAP URL. - - matches scopes exactly using a UUID string. + - matches scopes exactly using a UUID string. - - matches only those services that do not specify a scope. + - matches only those services that do not specify a scope. If a scope-matching rule is not specified, is used. diff --git a/docs/framework/wcf/feature-details/duplex-services.md b/docs/framework/wcf/feature-details/duplex-services.md index d57583b4f85be..2cbe429f76424 100644 --- a/docs/framework/wcf/feature-details/duplex-services.md +++ b/docs/framework/wcf/feature-details/duplex-services.md @@ -18,7 +18,7 @@ manager: "erikre" # Duplex Services A duplex service contract is a message exchange pattern in which both endpoints can send messages to the other independently. A duplex service, therefore, can send messages back to the client endpoint, providing event-like behavior. Duplex communication occurs when a client connects to a service and provides the service with a channel on which the service can send messages back to the client. Note that the event-like behavior of duplex services only works within a session. - To create a duplex contract you create a pair of interfaces. The first is the service contract interface that describes the operations that a client can invoke. That service contract must specify a *callback contract* in the property. The callback contract is the interface that defines the operations that the service can call on the client endpoint. A duplex contract does not require a session, although the system-provided duplex bindings make use of them. + To create a duplex contract you create a pair of interfaces. The first is the service contract interface that describes the operations that a client can invoke. That service contract must specify a *callback contract* in the property. The callback contract is the interface that defines the operations that the service can call on the client endpoint. A duplex contract does not require a session, although the system-provided duplex bindings make use of them. The following is an example of a duplex contract. diff --git a/docs/framework/wcf/feature-details/encryption-of-digital-signatures.md b/docs/framework/wcf/feature-details/encryption-of-digital-signatures.md index 672a7fdf9ea82..cb4cb06e61659 100644 --- a/docs/framework/wcf/feature-details/encryption-of-digital-signatures.md +++ b/docs/framework/wcf/feature-details/encryption-of-digital-signatures.md @@ -30,7 +30,7 @@ By default, a message is signed and encrypted, and the signature is digitally en 2. Add either an or a to the binding collection. -3. Set the property to , or set the property to . +3. Set the property to , or set the property to . [!INCLUDE[crabout](../../../../includes/crabout-md.md)] creating custom bindings, see [Creating User-Defined Bindings](../../../../docs/framework/wcf/extending/creating-user-defined-bindings.md). [!INCLUDE[crabout](../../../../includes/crabout-md.md)] creating a custom binding for a specific authentication mode, see [How to: Create a SecurityBindingElement for a Specified Authentication Mode](../../../../docs/framework/wcf/feature-details/how-to-create-a-securitybindingelement-for-a-specified-authentication-mode.md). diff --git a/docs/framework/wcf/feature-details/exporting-and-importing-metadata.md b/docs/framework/wcf/feature-details/exporting-and-importing-metadata.md index 9368d237bfecf..2e8a30a5dff1e 100644 --- a/docs/framework/wcf/feature-details/exporting-and-importing-metadata.md +++ b/docs/framework/wcf/feature-details/exporting-and-importing-metadata.md @@ -21,9 +21,9 @@ manager: "erikre" In [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)], exporting metadata is the process of describing service endpoints and projecting them into a parallel, standardized representation that clients can use to understand how to use the service. Importing service metadata is the process of generating instances or parts from service metadata. ## Exporting Metadata - To export metadata from instances, use an implementation of the abstract class. The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. + To export metadata from instances, use an implementation of the abstract class. The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. - The type generates Web Services Description Language (WSDL) metadata with attached policy expressions encapsulated in a instance. You can use a instance to iteratively export metadata for objects and objects. You can also export a collection of objects and associate them with a specific service name. + The type generates Web Services Description Language (WSDL) metadata with attached policy expressions encapsulated in a instance. You can use a instance to iteratively export metadata for objects and objects. You can also export a collection of objects and associate them with a specific service name. > [!NOTE] > You can only use the `WsdlExporter` to export metadata from `ContractDescription` instances that contain common language runtime (CLR) type information, such as a `ContractDescription` instance created using the `ContractDescription.GetContract` method or created as part of the `ServiceDescription` for a `ServiceHost` instance. You cannot use the `WsdlExporter` to export metadata from `ContractDescription` instances imported from service metadata or constructed without type information. @@ -31,7 +31,7 @@ In [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)], exporting metadata i ## Importing Metadata ### Importing WSDL Documents - To import service metadata in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], use an implementation of the abstract class. The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The type imports WSDL metadata with attached policies bundled in a object. + To import service metadata in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], use an implementation of the abstract class. The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The type imports WSDL metadata with attached policies bundled in a object. The type gives you control over how to import the metadata. You can import all of the endpoints, all of the bindings, or all of the contracts. You can import all of the endpoints associated with a specific WSDL service, binding, or port type. You can also import the endpoint for a specific WSDL port, the binding for a specific WSDL binding or the contract for a specific WSDL port type. diff --git a/docs/framework/wcf/feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md b/docs/framework/wcf/feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md index 535bfa4c52a7d..44b5d832dce87 100644 --- a/docs/framework/wcf/feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md +++ b/docs/framework/wcf/feature-details/how-to-call-operations-asynchronously-using-a-channel-factory.md @@ -16,7 +16,7 @@ ms.author: "erikre" manager: "erikre" --- # How to: Call Operations Asynchronously Using a Channel Factory -This topic covers how a client can access a service operation asynchronously when using a -based client application. (When using a object to invoke a service you can use the event-driven asynchronous calling model. For more information, see [How to: Call Service Operations Asynchronously](../../../../docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md). For more information about the event-based asynchronous calling model, see [Multithreaded Programming with the Event-based Asynchronous Pattern](../../../../docs/standard/asynchronous-programming-patterns/multithreaded-programming-with-the-event-based-asynchronous-pattern.md).) +This topic covers how a client can access a service operation asynchronously when using a -based client application. (When using a object to invoke a service you can use the event-driven asynchronous calling model. For more information, see [How to: Call Service Operations Asynchronously](../../../../docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md). For more information about the event-based asynchronous calling model, see [Multithreaded Programming with the Event-based Asynchronous Pattern](../../../../docs/standard/asynchronous-programming-patterns/multithreaded-programming-with-the-event-based-asynchronous-pattern.md).) The service in this topic implements the `ICalculator` interface. The client can call the operations on this interface asynchronously, which means that operations like `Add` are split into two methods, `BeginAdd` and `EndAdd`, the former of which initiates the call and the latter of which retrieves the result when the operation completes. For an example showing how to implement an operation asynchronously in a service, see [How to: Implement an Asynchronous Service Operation](../../../../docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md). For details about synchronous and asynchronous operations, see [Synchronous and Asynchronous Operations](../../../../docs/framework/wcf/synchronous-and-asynchronous-operations.md). diff --git a/docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md b/docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md index 32fb5c551c95a..6c8780e4d9fa4 100644 --- a/docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md +++ b/docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md @@ -43,7 +43,7 @@ This topic covers how a client can access a service operation asynchronously. Th [!code-csharp[EventAsync#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/eventasync/cs/generatedclient.cs#2)] [!code-vb[EventAsync#2](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/eventasync/vb/generatedclient.vb#2)] - - types for each operation (of the form <`operationName`>`CompletedEventArgs`) for use with the event-based asynchronous calling approach. For example: + - types for each operation (of the form <`operationName`>`CompletedEventArgs`) for use with the event-based asynchronous calling approach. For example: [!code-csharp[EventAsync#3](../../../../samples/snippets/csharp/VS_Snippets_CFX/eventasync/cs/generatedclient.cs#3)] [!code-vb[EventAsync#3](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/eventasync/vb/generatedclient.vb#3)] @@ -53,7 +53,7 @@ This topic covers how a client can access a service operation asynchronously. Th [!code-csharp[EventAsync#4](../../../../samples/snippets/csharp/VS_Snippets_CFX/eventasync/cs/client.cs#4)] [!code-vb[EventAsync#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/eventasync/vb/client.vb#4)] -3. Prior to calling the operation, use a new generic of type <`operationName`>`EventArgs` to add the handler method (created in the preceding step) to the <`operationName`>`Completed` event. Then call the <`operationName`>`Async` method. For example: +3. Prior to calling the operation, use a new generic of type <`operationName`>`EventArgs` to add the handler method (created in the preceding step) to the <`operationName`>`Completed` event. Then call the <`operationName`>`Async` method. For example: [!code-csharp[EventAsync#5](../../../../samples/snippets/csharp/VS_Snippets_CFX/eventasync/cs/client.cs#5)] [!code-vb[EventAsync#5](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/eventasync/vb/client.vb#5)] diff --git a/docs/framework/wcf/feature-details/how-to-control-service-instancing.md b/docs/framework/wcf/feature-details/how-to-control-service-instancing.md index 7be84ded806b9..7c23a25fa988d 100644 --- a/docs/framework/wcf/feature-details/how-to-control-service-instancing.md +++ b/docs/framework/wcf/feature-details/how-to-control-service-instancing.md @@ -19,7 +19,7 @@ ms.author: "erikre" manager: "erikre" --- # How to: Control Service Instancing -Setting the instance mode of a service enables you to specify when a (and its associated user-defined service object) is created. See the enumeration for the possible modes. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] behaviors, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). For working examples, see [Behaviors](../../../../docs/framework/wcf/samples/behaviors.md). +Setting the instance mode of a service enables you to specify when a (and its associated user-defined service object) is created. See the enumeration for the possible modes. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] behaviors, see [Configuring and Extending the Runtime with Behaviors](../../../../docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). For working examples, see [Behaviors](../../../../docs/framework/wcf/samples/behaviors.md). ### To control the service instance lifetime using code diff --git a/docs/framework/wcf/feature-details/how-to-create-a-service-that-requires-sessions.md b/docs/framework/wcf/feature-details/how-to-create-a-service-that-requires-sessions.md index b1c0aee524a32..2be173c1b8e74 100644 --- a/docs/framework/wcf/feature-details/how-to-create-a-service-that-requires-sessions.md +++ b/docs/framework/wcf/feature-details/how-to-create-a-service-that-requires-sessions.md @@ -22,26 +22,26 @@ Sessions create a shared state between two or more endpoints that enables useful 1. Create a service contract with at least one operation. For an example of how to create a service contract, see [How to: Define a Service Contract](../../../../docs/framework/wcf/how-to-define-a-wcf-service-contract.md). -2. Modify the that declares the contract by setting the property to either: +2. Modify the that declares the contract by setting the property to either: - - if this contract must be run within a session. + - if this contract must be run within a session. - - if this contract can be run within a session. + - if this contract can be run within a session. - - if this contract must not be run within a session. + - if this contract must not be run within a session. -3. Configure your service endpoint to use a binding that supports sessions. The following configuration example shows the use of the , which supports a WS`-`ReliableMessaging session. +3. Configure your service endpoint to use a binding that supports sessions. The following configuration example shows the use of the , which supports a WS`-`ReliableMessaging session. [!code-xml[SCA.Session#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/sca.session/cs/hostapplication.exe.config#2)] ## Example - The following example code shows how to specify a contract-level session requirement and use a configuration file to support that requirement with the binding. + The following example code shows how to specify a contract-level session requirement and use a configuration file to support that requirement with the binding. [!code-csharp[SCA.Session#1](../../../../samples/snippets/csharp/VS_Snippets_CFX/sca.session/cs/services.cs#1)] [!code-vb[SCA.Session#1](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/sca.session/vb/services.vb#1)] [!code-xml[SCA.Session#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/sca.session/cs/hostapplication.exe.config#2)] ## See Also - - - + + + diff --git a/docs/framework/wcf/feature-details/how-to-disable-encryption-of-digital-signatures.md b/docs/framework/wcf/feature-details/how-to-disable-encryption-of-digital-signatures.md index a227e19076e14..06b16e88f78a9 100644 --- a/docs/framework/wcf/feature-details/how-to-disable-encryption-of-digital-signatures.md +++ b/docs/framework/wcf/feature-details/how-to-disable-encryption-of-digital-signatures.md @@ -21,7 +21,7 @@ By default, a message is signed and the signature is digitally encrypted. This i Therefore, disable encryption of the signature only when the value of the content is low or the set of possible content values is large and nondeterministic, and the performance gain is more important than mitigating the attack described above. > [!NOTE] -> If there is nothing in the message that is encrypted, the signature element is not encrypted, even when the or property is set to . This behavior occurs even with system-provided bindings; all system-provided bindings have the message protection order set to `SignBeforeEncryptAndEncryptSignature`. However, the Web Services Description Language (WSDL) [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] generates will still contain the `` assertion. +> If there is nothing in the message that is encrypted, the signature element is not encrypted, even when the or property is set to . This behavior occurs even with system-provided bindings; all system-provided bindings have the message protection order set to `SignBeforeEncryptAndEncryptSignature`. However, the Web Services Description Language (WSDL) [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] generates will still contain the `` assertion. ### To disable digital signing @@ -29,7 +29,7 @@ By default, a message is signed and the signature is digitally encrypted. This i 2. Add either an or a to the binding collection. -3. Set the property to , or set the property to . +3. Set the property to , or set the property to . ## See Also [Security Capabilities with Custom Bindings](../../../../docs/framework/wcf/feature-details/security-capabilities-with-custom-bindings.md) diff --git a/docs/framework/wcf/feature-details/how-to-implement-a-discovery-proxy.md b/docs/framework/wcf/feature-details/how-to-implement-a-discovery-proxy.md index f7993f69ccaa0..3e4810d86c9f8 100644 --- a/docs/framework/wcf/feature-details/how-to-implement-a-discovery-proxy.md +++ b/docs/framework/wcf/feature-details/how-to-implement-a-discovery-proxy.md @@ -231,7 +231,7 @@ This topic explains how to implement a discovery proxy. [!INCLUDE[crabout](../.. ### To define the methods that implement the discovery proxy functionality -1. Override the method. This method is called when the discovery proxy receives an online announcement message. +1. Override the method. This method is called when the discovery proxy receives an online announcement message. ``` // OnBeginOnlineAnnouncement method is called when a Hello message is received by the Proxy @@ -242,7 +242,7 @@ This topic explains how to implement a discovery proxy. [!INCLUDE[crabout](../.. } ``` -2. Override the method. This method is called when the discovery proxy finishes processing an announcement message. +2. Override the method. This method is called when the discovery proxy finishes processing an announcement message. ``` protected override void OnEndOnlineAnnouncement(IAsyncResult result) @@ -251,7 +251,7 @@ This topic explains how to implement a discovery proxy. [!INCLUDE[crabout](../.. } ``` -3. Override the method. This method is called with the discovery proxy receives an offline announcement message. +3. Override the method. This method is called with the discovery proxy receives an offline announcement message. ``` // OnBeginOfflineAnnouncement method is called when a Bye message is received by the Proxy @@ -262,7 +262,7 @@ This topic explains how to implement a discovery proxy. [!INCLUDE[crabout](../.. } ``` -4. Override the method. This method is called when the discovery proxy finishes processing an offline announcement message. +4. Override the method. This method is called when the discovery proxy finishes processing an offline announcement message. ``` protected override void OnEndOfflineAnnouncement(IAsyncResult result) @@ -271,7 +271,7 @@ This topic explains how to implement a discovery proxy. [!INCLUDE[crabout](../.. } ``` -5. Override the method. This method is called when the discovery proxy receives a find request. +5. Override the method. This method is called when the discovery proxy receives a find request. ``` // OnBeginFind method is called when a Probe request message is received by the Proxy @@ -290,7 +290,7 @@ This topic explains how to implement a discovery proxy. [!INCLUDE[crabout](../.. } ``` -6. Override the method. This method is called when the discovery proxy finishes processing a find request. +6. Override the method. This method is called when the discovery proxy finishes processing a find request. ``` protected override void OnEndFind(IAsyncResult result) @@ -299,7 +299,7 @@ This topic explains how to implement a discovery proxy. [!INCLUDE[crabout](../.. } ``` -7. Override the method. This method is called when the discovery proxy receives a resolve message. +7. Override the method. This method is called when the discovery proxy receives a resolve message. ``` // OnBeginFind method is called when a Resolve request message is received by the Proxy @@ -316,7 +316,7 @@ This topic explains how to implement a discovery proxy. [!INCLUDE[crabout](../.. } ``` -8. Override the method. This method is called when the discovery proxy finishes processing a resolve message. +8. Override the method. This method is called when the discovery proxy finishes processing a resolve message. ``` protected override EndpointDiscoveryMetadata OnEndResolve(IAsyncResult result) diff --git a/docs/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.md b/docs/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.md index 093f8811ccb4b..e163ce8efa980 100644 --- a/docs/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.md +++ b/docs/framework/wcf/feature-details/how-to-retrieve-metadata-and-implement-a-compliant-service.md @@ -24,7 +24,7 @@ Often, the same person does not design and implement services. In environments w 1. Use the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) against metadata files or a metadata endpoint to generate a code file. -2. Search for the portion of the output code file that contains the interface of interest (in case there is more than one) that is marked with the attribute. The following code example shows the two interfaces generated by [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md). The first (`ISampleService`) is the service contract interface that you implement to create a compliant service. The second (`ISampleServiceChannel`) is a helper interface for client use that extends both the service contract interface and and is for use in a client application. +2. Search for the portion of the output code file that contains the interface of interest (in case there is more than one) that is marked with the attribute. The following code example shows the two interfaces generated by [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md). The first (`ISampleService`) is the service contract interface that you implement to create a compliant service. The second (`ISampleServiceChannel`) is a helper interface for client use that extends both the service contract interface and and is for use in a client application. [!code-csharp[ClientProxyCodeSample#2](../../../../samples/snippets/csharp/VS_Snippets_CFX/clientproxycodesample/cs/proxycode.cs#2)] @@ -47,9 +47,9 @@ Often, the same person does not design and implement services. In environments w - The service contract interface that, when implemented, complies with the contract requirements (`ISampleService`). -- The helper interface for client use that extends both the service contract interface and and is for use in a client application (`ISampleServiceChannel`). +- The helper interface for client use that extends both the service contract interface and and is for use in a client application (`ISampleServiceChannel`). -- The helper class that extends and is for use in a client application (`SampleServiceClient`). +- The helper class that extends and is for use in a client application (`SampleServiceClient`). - The configuration file generated from the service. diff --git a/docs/framework/wcf/feature-details/how-to-secure-metadata-endpoints.md b/docs/framework/wcf/feature-details/how-to-secure-metadata-endpoints.md index fb9e7319b0d2a..d5414cc27e71f 100644 --- a/docs/framework/wcf/feature-details/how-to-secure-metadata-endpoints.md +++ b/docs/framework/wcf/feature-details/how-to-secure-metadata-endpoints.md @@ -91,9 +91,9 @@ Metadata for a service can contain sensitive information about your application ## Compiling the Code The code example uses the following namespaces: -- +- -- +- ## See Also diff --git a/docs/framework/wcf/feature-details/importing-schema-to-generate-classes.md b/docs/framework/wcf/feature-details/importing-schema-to-generate-classes.md index 86652b5d6bd1a..e493b0f454db6 100644 --- a/docs/framework/wcf/feature-details/importing-schema-to-generate-classes.md +++ b/docs/framework/wcf/feature-details/importing-schema-to-generate-classes.md @@ -77,7 +77,7 @@ To generate classes from schemas that are usable with [!INCLUDE[indigo1](../../. #### Adding the SerializableAttribute (GenerateSerializable or the /serializable switch) This corresponds to the **/serializable** switch on the `Svcutil.exe` tool. - Sometimes it is important for the types generated from the schema to be usable with [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] runtime serialization engines (for example, the and the classes). This is useful when using types for [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] remoting. To enable this, you must apply the attribute to the generated types in addition to the regular attribute. The attribute is generated automatically if the `GenerateSerializable` import option is set to `true`. + Sometimes it is important for the types generated from the schema to be usable with [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] runtime serialization engines (for example, the and the classes). This is useful when using types for [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] remoting. To enable this, you must apply the attribute to the generated types in addition to the regular attribute. The attribute is generated automatically if the `GenerateSerializable` import option is set to `true`. The following example shows the `Vehicle` class generated with the `GenerateSerializable` import option set to `true`. diff --git a/docs/framework/wcf/feature-details/large-data-and-streaming.md b/docs/framework/wcf/feature-details/large-data-and-streaming.md index 09238661b6e20..01a91bedb877d 100644 --- a/docs/framework/wcf/feature-details/large-data-and-streaming.md +++ b/docs/framework/wcf/feature-details/large-data-and-streaming.md @@ -125,7 +125,7 @@ class MyData The effect on the MTOM encoding is the same whether you use an explicit data contract, as shown in the preceding example, use a parameter list in an operation, have nested data contracts, or transfer a data contract object inside a collection. Byte arrays are always candidates for optimization and are optimized if the optimization thresholds are being met. > [!NOTE] -> You should not be using derived types inside of data contracts. Stream data should be communicated using the streaming model, explained in the following "Streaming Data" section. +> You should not be using derived types inside of data contracts. Stream data should be communicated using the streaming model, explained in the following "Streaming Data" section. ## Streaming Data When you have a large amount of data to transfer, the streaming transfer mode in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] is a feasible alternative to the default behavior of buffering and processing messages in memory in their entirety. diff --git a/docs/framework/wcf/feature-details/metadata-architecture-overview.md b/docs/framework/wcf/feature-details/metadata-architecture-overview.md index 90a1753a81782..120238533a218 100644 --- a/docs/framework/wcf/feature-details/metadata-architecture-overview.md +++ b/docs/framework/wcf/feature-details/metadata-architecture-overview.md @@ -24,7 +24,7 @@ manager: "erikre" [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] uses the class to describe endpoints in a service. You can use [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] to generate metadata for service endpoints or import service metadata to generate instances. - [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] represents the metadata for a service as an instance of the type, the structure of which is strongly tied to the metadata serialization format defined in WS-MetadataExchange. The type bundles the actual service metadata, such as Web Services Description Language (WSDL) documents, XML schema documents, or WS-Policy expressions, as a collection of instances. Each instance contains a specific metadata dialect and an identifier. A can contain the following items in its property: + [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] represents the metadata for a service as an instance of the type, the structure of which is strongly tied to the metadata serialization format defined in WS-MetadataExchange. The type bundles the actual service metadata, such as Web Services Description Language (WSDL) documents, XML schema documents, or WS-Policy expressions, as a collection of instances. Each instance contains a specific metadata dialect and an identifier. A can contain the following items in its property: - Raw metadata. @@ -32,29 +32,29 @@ manager: "erikre" - A instance. - A instances point to another metadata exchange (MEX) endpoint and instances point to a metadata document using an HTTP URL. [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] supports using WSDL documents to describe service endpoints, service contracts, bindings, message exchange patterns, messages and fault messages implemented by a service. Data types used by the service are described in WSDL documents using XML schema. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Schema Import and Export](../../../../docs/framework/wcf/feature-details/schema-import-and-export.md). You can use [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] to export and import WSDL extensions for service behavior, contract behaviors, and binding elements that extend the functionality of a service. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Exporting Custom Metadata for a WCF Extension](../../../../docs/framework/wcf/extending/exporting-custom-metadata-for-a-wcf-extension.md). + A instances point to another metadata exchange (MEX) endpoint and instances point to a metadata document using an HTTP URL. [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] supports using WSDL documents to describe service endpoints, service contracts, bindings, message exchange patterns, messages and fault messages implemented by a service. Data types used by the service are described in WSDL documents using XML schema. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Schema Import and Export](../../../../docs/framework/wcf/feature-details/schema-import-and-export.md). You can use [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] to export and import WSDL extensions for service behavior, contract behaviors, and binding elements that extend the functionality of a service. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Exporting Custom Metadata for a WCF Extension](../../../../docs/framework/wcf/extending/exporting-custom-metadata-for-a-wcf-extension.md). ## Exporting Service Metadata - In [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], *metadata export* is the process of describing service endpoints and projecting them into a parallel, standardized representation that clients can use to understand how to use the service. To export metadata from instances, use an implementation of the abstract class. A implementation generates metadata that is encapsulated in a instance. + In [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], *metadata export* is the process of describing service endpoints and projecting them into a parallel, standardized representation that clients can use to understand how to use the service. To export metadata from instances, use an implementation of the abstract class. A implementation generates metadata that is encapsulated in a instance. - The class provides a framework for generating policy expressions that describe the capabilities and requirements of an endpoint binding and its associated operations, messages, and faults. These policy expressions are captured in a instance. A implementation can then attach these policy expressions to the metadata it generates. + The class provides a framework for generating policy expressions that describe the capabilities and requirements of an endpoint binding and its associated operations, messages, and faults. These policy expressions are captured in a instance. A implementation can then attach these policy expressions to the metadata it generates. - The calls into each that implements the interface in the binding of a when generating a object for the implementation to use. You can export new policy assertions by implementing the interface on your custom implementations of the type. + The calls into each that implements the interface in the binding of a when generating a object for the implementation to use. You can export new policy assertions by implementing the interface on your custom implementations of the type. - The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The type generates WSDL metadata with attached policy expressions. + The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The type generates WSDL metadata with attached policy expressions. To export custom WSDL metadata or WSDL extensions for endpoint behaviors, contract behaviors, or binding elements in a service endpoint, you can implement the interface. The looks at a instance for binding elements, operation behaviors, contract behaviors, and endpoint behaviors that implement the interface when generating the WSDL document. ## Publishing Service Metadata [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] services publish metadata by exposing one or more metadata endpoints. Publishing service metadata makes service metadata available using standardized protocols, such as MEX and HTTP/GET requests. Metadata endpoints are similar to other service endpoints in that they have an address, a binding, and a contract. You can add metadata endpoints to a service host in configuration or in code. - To publish metadata endpoints for a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service, you must first add an instance of the service behavior to the service. Adding a instance to your service augments your service with the ability to publish metadata by exposing one or more metadata endpoints. Once you add the service behavior you can then expose metadata endpoints that support the MEX protocol or metadata endpoints that respond to HTTP/GET requests. + To publish metadata endpoints for a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service, you must first add an instance of the service behavior to the service. Adding a instance to your service augments your service with the ability to publish metadata by exposing one or more metadata endpoints. Once you add the service behavior you can then expose metadata endpoints that support the MEX protocol or metadata endpoints that respond to HTTP/GET requests. To add metadata endpoints that use the MEX protocol, add service endpoints to your service host that use the service contract named IMetadataExchange.[!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] defines the interface that has this service contract name. WS-MetadataExchange endpoints, or MEX endpoints, can use one of the four default bindings exposed by the static factory methods on the class to match the default bindings used by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] tools, such as Svcutil.exe. You can also configure MEX metadata endpoints using a custom binding. - The uses a to export metadata for all service endpoints in your service. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] exporting metadata from a service, see [Exporting and Importing Metadata](../../../../docs/framework/wcf/feature-details/exporting-and-importing-metadata.md). + The uses a to export metadata for all service endpoints in your service. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] exporting metadata from a service, see [Exporting and Importing Metadata](../../../../docs/framework/wcf/feature-details/exporting-and-importing-metadata.md). - The augments your service host by adding a instance as an extension to your service host. The provides the implementation for the metadata publishing protocols. You can also use the to get the service's metadata at runtime by accessing the property. + The augments your service host by adding a instance as an extension to your service host. The provides the implementation for the metadata publishing protocols. You can also use the to get the service's metadata at runtime by accessing the property. > [!CAUTION] > If you add a MEX endpoint in your application configuration file and then attempt to add the to your service host in code you get the following exception: @@ -73,25 +73,25 @@ manager: "erikre" > - Set one of the operations' namespaces to a different namespace using the property. ## Retrieving Service Metadata - [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] can retrieve service metadata using standardized protocols such as WS-MetadataExchange and HTTP. Both of these protocols are supported by the type. You retrieve service metadata using the type by providing an address and an optional binding. The binding used by a instance can be one of the default bindings from the static class, a user-supplied binding, or a binding loaded from an endpoint configuration for the `IMetadataExchange` contract. The can also resolve HTTP URL references to metadata using the type. + [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] can retrieve service metadata using standardized protocols such as WS-MetadataExchange and HTTP. Both of these protocols are supported by the type. You retrieve service metadata using the type by providing an address and an optional binding. The binding used by a instance can be one of the default bindings from the static class, a user-supplied binding, or a binding loaded from an endpoint configuration for the `IMetadataExchange` contract. The can also resolve HTTP URL references to metadata using the type. - By default, a instance is tied to a single instance. You can change or replace the instance used by a by overriding the virtual method. Similarly, you can change or replace the instance used by a to make HTTP/GET requests by overriding the virtual method. + By default, a instance is tied to a single instance. You can change or replace the instance used by a by overriding the virtual method. Similarly, you can change or replace the instance used by a to make HTTP/GET requests by overriding the virtual method. - You can retrieve service metadata using WS-MetadataExchange or HTTP/GET requests by using the Svcutil.exe tool and passing the **/target:metadata** switch and an address. Svcutil.exe downloads the metadata at the specified address and saves the files to disk. Svcutil.exe uses a instance internally and loads an MEX endpoint configuration (from the application configuration file) whose name matches the scheme of the address passed to Svcutil.exe, if one exists. Otherwise, Svcutil.exe defaults to using one of the bindings defined by the static factory type. + You can retrieve service metadata using WS-MetadataExchange or HTTP/GET requests by using the Svcutil.exe tool and passing the **/target:metadata** switch and an address. Svcutil.exe downloads the metadata at the specified address and saves the files to disk. Svcutil.exe uses a instance internally and loads an MEX endpoint configuration (from the application configuration file) whose name matches the scheme of the address passed to Svcutil.exe, if one exists. Otherwise, Svcutil.exe defaults to using one of the bindings defined by the static factory type. ## Importing Service Metadata - In [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], metadata import is the process of generating an abstract representation of a service or its component parts from its metadata. For example, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] can import instances, instances or instances from a WSDL document for a service. To import service metadata in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], use an implementation of the abstract class. Types that derive from the class implement support for importing metadata formats that take advantage of the WS-Policy import logic in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. + In [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], metadata import is the process of generating an abstract representation of a service or its component parts from its metadata. For example, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] can import instances, instances or instances from a WSDL document for a service. To import service metadata in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], use an implementation of the abstract class. Types that derive from the class implement support for importing metadata formats that take advantage of the WS-Policy import logic in [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. - A implementation collects the policy expressions attached to the service metadata in a object. The then processes the policies as part of importing the metadata by calling the implementations of the interface in the property. + A implementation collects the policy expressions attached to the service metadata in a object. The then processes the policies as part of importing the metadata by calling the implementations of the interface in the property. - You can add support for importing new policy assertions to a by adding your own implementation of the interface to the collection on a instance. Alternatively, you can register your policy import extension in your client application configuration file. + You can add support for importing new policy assertions to a by adding your own implementation of the interface to the collection on a instance. Alternatively, you can register your policy import extension in your client application configuration file. - The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The type imports WSDL metadata with attached policies that are bundled in a object. + The type is the implementation of the abstract class included with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)]. The type imports WSDL metadata with attached policies that are bundled in a object. - You can add support for importing WSDL extensions by implementing the interface and then adding your implementation to the property on your instance. The can also load implementations of the interface registered in your client application configuration file. + You can add support for importing WSDL extensions by implementing the interface and then adding your implementation to the property on your instance. The can also load implementations of the interface registered in your client application configuration file. ## Dynamic Bindings - You can dynamically update the binding that you use to create a channel to a service endpoint in the event that the binding for the endpoint changes or you want to create a channel to an endpoint that uses the same contract but has a different binding. You can use the static class to retrieve and import metadata at runtime for service endpoints that implement a specific contract. You can then use the imported objects to create a client or channel factory to the desired endpoint. + You can dynamically update the binding that you use to create a channel to a service endpoint in the event that the binding for the endpoint changes or you want to create a channel to an endpoint that uses the same contract but has a different binding. You can use the static class to retrieve and import metadata at runtime for service endpoints that implement a specific contract. You can then use the imported objects to create a client or channel factory to the desired endpoint. ## See Also diff --git a/docs/framework/wcf/feature-details/one-way-services.md b/docs/framework/wcf/feature-details/one-way-services.md index 7b2d825a089fe..789d3f521b46e 100644 --- a/docs/framework/wcf/feature-details/one-way-services.md +++ b/docs/framework/wcf/feature-details/one-way-services.md @@ -52,13 +52,13 @@ public interface IOneWayCalculator ## Clients Blocking with One-Way Operations It is important to realize that while some one-way applications return as soon as the outbound data is written to the network connection, in several scenarios the implementation of a binding or of a service can cause a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client to block using one-way operations. In [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client applications, the [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client object does not return until the outbound data has been written to the network connection. This is true for all message exchange patterns, including one-way operations; this means that any problem writing the data to the transport prevents the client from returning. Depending upon the problem, the result could be an exception or a delay in sending messages to the service. - For example, if the transport cannot find the endpoint, a exception is thrown without much delay. However, it is also possible that the service is unable to read the data off the wire for some reason, which prevents the client transport send operation from returning. In these cases, if the period on the client transport binding is exceeded, a is thrown—but not until the timeout period has been exceeded. It is also possible to fire so many messages at a service that the service cannot process them past a certain point. In this case, too, the one-way client blocks until the service can process the messages or until an exception is thrown. + For example, if the transport cannot find the endpoint, a exception is thrown without much delay. However, it is also possible that the service is unable to read the data off the wire for some reason, which prevents the client transport send operation from returning. In these cases, if the period on the client transport binding is exceeded, a is thrown—but not until the timeout period has been exceeded. It is also possible to fire so many messages at a service that the service cannot process them past a certain point. In this case, too, the one-way client blocks until the service can process the messages or until an exception is thrown. - Another variation is the situation in which the service property is set to and the binding uses sessions. In this case, the dispatcher enforces ordering on the incoming messages (a requirement of sessions), which prevents subsequent messages from being read off the network until the service has processed the preceding message for that session. Again, the client blocks, but whether an exception occurs depends upon whether the service is able to process the waiting data prior to the timeout settings on the client. + Another variation is the situation in which the service property is set to and the binding uses sessions. In this case, the dispatcher enforces ordering on the incoming messages (a requirement of sessions), which prevents subsequent messages from being read off the network until the service has processed the preceding message for that session. Again, the client blocks, but whether an exception occurs depends upon whether the service is able to process the waiting data prior to the timeout settings on the client. You can mitigate some of this problem by inserting a buffer between the client object and the client transport's send operation. For example, using asynchronous calls or using an in-memory message queue can enable the client object to return quickly. Both approaches may increase functionality, but the size of the thread pool and the message queue still enforce limits. - It is recommended, instead, that you examine the various controls on the service as well as on the client, and then test your application scenarios to determine the best configuration on either side. For example, if the use of sessions is blocking the processing of messages on your service, you can set the property to so that each message can be processed by a different service instance, and set the to in order to allow more than one thread to dispatch messages at a time. Another approach is to increase the read quotas of the service and client bindings. + It is recommended, instead, that you examine the various controls on the service as well as on the client, and then test your application scenarios to determine the best configuration on either side. For example, if the use of sessions is blocking the processing of messages on your service, you can set the property to so that each message can be processed by a different service instance, and set the to in order to allow more than one thread to dispatch messages at a time. Another approach is to increase the read quotas of the service and client bindings. ## See Also [One-Way](../../../../docs/framework/wcf/samples/one-way.md) diff --git a/docs/framework/wcf/feature-details/partial-trust-feature-compatibility.md b/docs/framework/wcf/feature-details/partial-trust-feature-compatibility.md index c1da5e826c1b5..d0deb707c770b 100644 --- a/docs/framework/wcf/feature-details/partial-trust-feature-compatibility.md +++ b/docs/framework/wcf/feature-details/partial-trust-feature-compatibility.md @@ -137,9 +137,9 @@ manager: "erikre" The following members of the enumeration should not be specified: -- +- -- +- When using tracing in a partial trust environment, ensure that the application has sufficient permissions to store the output of the trace listener. For example, when using the to write trace output to a text file, ensure that the application has the necessary FileIOPermission required to successfully write to the trace file. diff --git a/docs/framework/wcf/feature-details/publishing-metadata.md b/docs/framework/wcf/feature-details/publishing-metadata.md index 690c91c204852..8156d8b3cf48b 100644 --- a/docs/framework/wcf/feature-details/publishing-metadata.md +++ b/docs/framework/wcf/feature-details/publishing-metadata.md @@ -21,17 +21,17 @@ manager: "erikre" [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] services publish metadata by publishing one or more metadata endpoints. Publishing service metadata makes the metadata available using standardized protocols, such as WS-MetadataExchange (MEX) and HTTP/GET requests. Metadata endpoints are similar to other service endpoints in that they have an address, a binding, and a contract, and they can be added to a service host through configuration or imperative code. ## Publishing Metadata Endpoints - To publish metadata endpoints for a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service, you first must add the service behavior to the service. Adding a instance allows your service to expose metadata endpoints. Once you add the service behavior, you can then expose metadata endpoints that support the MEX protocol or that respond to HTTP/GET requests. + To publish metadata endpoints for a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service, you first must add the service behavior to the service. Adding a instance allows your service to expose metadata endpoints. Once you add the service behavior, you can then expose metadata endpoints that support the MEX protocol or that respond to HTTP/GET requests. - The uses a to export metadata for all service endpoints in your service. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] exporting metadata from a service, see [Exporting and Importing Metadata](../../../../docs/framework/wcf/feature-details/exporting-and-importing-metadata.md). + The uses a to export metadata for all service endpoints in your service. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] exporting metadata from a service, see [Exporting and Importing Metadata](../../../../docs/framework/wcf/feature-details/exporting-and-importing-metadata.md). - The adds a instance as an extension to your service host. The provides the implementation for the metadata publishing protocols. You can also use the to get the service's metadata at runtime by accessing the property. + The adds a instance as an extension to your service host. The provides the implementation for the metadata publishing protocols. You can also use the to get the service's metadata at runtime by accessing the property. ### MEX Metadata Endpoints To add metadata endpoints that use the MEX protocol, add service endpoints to your service host that use the `IMetadataExchange` service contract. [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] includes an interface with this service contract name that you can use as part of the [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] programming model. WS-MetadataExchange endpoints, or MEX endpoints, can use one of the four default bindings that the static factory methods expose on the class to match the default bindings used by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] tools such as Svcutil.exe. You can also configure MEX metadata endpoints using your own custom binding. ### HTTP GET Metadata Endpoints - To add a metadata endpoint to your service that responds to HTTP/GET requests, set the property on the to `true`. You can also configure a metadata endpoint that uses HTTPS by setting the property on the to `true`. + To add a metadata endpoint to your service that responds to HTTP/GET requests, set the property on the to `true`. You can also configure a metadata endpoint that uses HTTPS by setting the property on the to `true`. ## In This Section [How to: Publish Metadata for a Service Using a Configuration File](../../../../docs/framework/wcf/feature-details/how-to-publish-metadata-for-a-service-using-a-configuration-file.md) diff --git a/docs/framework/wcf/feature-details/retrieving-metadata.md b/docs/framework/wcf/feature-details/retrieving-metadata.md index c9c4cbfa9a32e..87c7281ac3291 100644 --- a/docs/framework/wcf/feature-details/retrieving-metadata.md +++ b/docs/framework/wcf/feature-details/retrieving-metadata.md @@ -21,22 +21,22 @@ manager: "erikre" Metadata retrieval is the process of requesting and retrieving metadata from a metadata endpoint, such as a WS-MetadataExchange (MEX) metadata endpoint or an HTTP/GET metadata endpoint. ## Retrieving Metadata from the Command Line Using Svcutil.exe - You can retrieve service metadata using WS-MetadataExchange or HTTP/GET requests by using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) tool and passing the `/target:metadata` switch and an address. Svcutil.exe downloads the metadata at the specified address and saves the file to disk. Svcutil.exe uses a instance internally and loads from configuration the endpoint configuration whose name matches the scheme of the address passed to Svcutil.exe as input. + You can retrieve service metadata using WS-MetadataExchange or HTTP/GET requests by using the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) tool and passing the `/target:metadata` switch and an address. Svcutil.exe downloads the metadata at the specified address and saves the file to disk. Svcutil.exe uses a instance internally and loads from configuration the endpoint configuration whose name matches the scheme of the address passed to Svcutil.exe as input. ## Retrieving Metadata Programmatically Using the MetadataExchangeClient - [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] can retrieve service metadata using standardized protocols such as WS-MetadataExchange and HTTP/GET requests. Both of these protocols are supported by the type. You retrieve service metadata using the type by providing an address for the metadata endpoint and an optional binding. The binding used by a instance can be one of the default bindings from the static class, a user-supplied binding, or a binding loaded from an endpoint configuration for the `IMetadataExchange` contract. The can also resolve HTTP URL references to metadata using the type. + [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] can retrieve service metadata using standardized protocols such as WS-MetadataExchange and HTTP/GET requests. Both of these protocols are supported by the type. You retrieve service metadata using the type by providing an address for the metadata endpoint and an optional binding. The binding used by a instance can be one of the default bindings from the static class, a user-supplied binding, or a binding loaded from an endpoint configuration for the `IMetadataExchange` contract. The can also resolve HTTP URL references to metadata using the type. - By default, a instance is tied to a single instance. You can change or replace the instance used by a by overriding the virtual method. Similarly, you can change or replace the instance used by a to make HTTP/GET requests by overriding the virtual method. + By default, a instance is tied to a single instance. You can change or replace the instance used by a by overriding the virtual method. Similarly, you can change or replace the instance used by a to make HTTP/GET requests by overriding the virtual method. ## In This Section [How to: Use Svcutil.exe to Download Metadata Documents](../../../../docs/framework/wcf/feature-details/how-to-use-svcutil-exe-to-download-metadata-documents.md) Demonstrates how to use Svcutil.exe to download metadata documents. [How to: Use MetadataResolver to Obtain Binding Metadata Dynamically](../../../../docs/framework/wcf/feature-details/how-to-use-metadataresolver-to-obtain-binding-metadata-dynamically.md) - Demonstrates how to use the to obtain binding metadata dynamically at runtime. + Demonstrates how to use the to obtain binding metadata dynamically at runtime. [How to: Use MetadataExchangeClient to Retrieve Metadata](../../../../docs/framework/wcf/feature-details/how-to-use-metadataexchangeclient-to-retrieve-metadata.md) - Demonstrates how to use the class to download metadata files into a object that contains objects to write to files or for other uses. + Demonstrates how to use the class to download metadata files into a object that contains objects to write to files or for other uses. ## See Also diff --git a/docs/framework/wcf/feature-details/selecting-a-credential-type.md b/docs/framework/wcf/feature-details/selecting-a-credential-type.md index 6d134e7e4f036..614af4b418686 100644 --- a/docs/framework/wcf/feature-details/selecting-a-credential-type.md +++ b/docs/framework/wcf/feature-details/selecting-a-credential-type.md @@ -104,18 +104,18 @@ manager: "erikre" [!INCLUDE[crabout](../../../../includes/crabout-md.md)] credentials and secure sessions, see [Security Considerations for Secure Sessions](../../../../docs/framework/wcf/feature-details/security-considerations-for-secure-sessions.md). ## See Also - - - - - - - - - - - - + + + + + + + + + + + + [Security Concepts](../../../../docs/framework/wcf/feature-details/security-concepts.md) [Securing Services and Clients](../../../../docs/framework/wcf/feature-details/securing-services-and-clients.md) [Programming WCF Security](../../../../docs/framework/wcf/feature-details/programming-wcf-security.md) diff --git a/docs/framework/wcf/feature-details/servicemodel-attributes-and-servicedescription-reference.md b/docs/framework/wcf/feature-details/servicemodel-attributes-and-servicedescription-reference.md index 0018bd4daf85f..f3cb55c5e7264 100644 --- a/docs/framework/wcf/feature-details/servicemodel-attributes-and-servicedescription-reference.md +++ b/docs/framework/wcf/feature-details/servicemodel-attributes-and-servicedescription-reference.md @@ -16,16 +16,16 @@ ms.author: "erikre" manager: "erikre" --- # ServiceModel Attributes and ServiceDescription Reference -The *description tree* is the hierarchy of types (starting with the class) that together describe every aspect of a service. [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] uses a description tree to build a valid service runtime, to publish Web Services Description Language (WSDL), XML Schema definition language (XSD), and policy assertions (metadata) about the service that clients can use to connect to and use the service, and to generate various code and configuration file representations of the description tree values. +The *description tree* is the hierarchy of types (starting with the class) that together describe every aspect of a service. [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] uses a description tree to build a valid service runtime, to publish Web Services Description Language (WSDL), XML Schema definition language (XSD), and policy assertions (metadata) about the service that clients can use to connect to and use the service, and to generate various code and configuration file representations of the description tree values. This topic describes how contract-related properties are obtained from the service contract, and how they are implemented and added to the description tree. In some cases, attribute values are converted into behavior properties and behavior is then inserted into the description tree. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] how the description tree values are converted into metadata, see [ServiceDescription and WSDL Reference](../../../../docs/framework/wcf/feature-details/servicedescription-and-wsdl-reference.md). ## Mapping Operations to the Description Tree In [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] applications, service contracts are modeled by interfaces (or classes) that use attributes to mark the interface or class and its methods as a grouping of operations. When a class is opened, any service contracts and implementations are reflected over and merged with configuration information into a description tree. - There are two types of operation models: the *parameter* model and the *message contract* model. The parameter model uses managed methods that do not have a parameter or return value type that is marked by the class. In this model, developers control the serialization of parameters and return values, but [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] generates the values that are used to populate the description tree for the service and its contract. + There are two types of operation models: the *parameter* model and the *message contract* model. The parameter model uses managed methods that do not have a parameter or return value type that is marked by the class. In this model, developers control the serialization of parameters and return values, but [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] generates the values that are used to populate the description tree for the service and its contract. - Bindings specified in configuration files are loaded directly into the property. + Bindings specified in configuration files are loaded directly into the property. |ServiceBehaviorAttribute Property|Description Tree Value Affected| |---------------------------------------|-------------------------------------| diff --git a/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md b/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md index ce02716a8166a..ece60461a877a 100644 --- a/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md +++ b/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md @@ -21,7 +21,7 @@ A *session* is a correlation of all messages sent between two endpoints. *Instan This topic describes these settings, how to use them, and the various interactions between them. ## Sessions - When a service contract sets the property to , that contract is saying that all calls (that is, the underlying message exchanges that support the calls) must be part of the same conversation. If a contract specifies that it allows sessions but does not require one, clients can connect and either establish a session or not. If the session ends and a message is sent over the same session-based channel an exception is thrown. + When a service contract sets the property to , that contract is saying that all calls (that is, the underlying message exchanges that support the calls) must be part of the same conversation. If a contract specifies that it allows sessions but does not require one, clients can connect and either establish a session or not. If the session ends and a message is sent over the same session-based channel an exception is thrown. [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] sessions have the following main conceptual features: @@ -33,7 +33,7 @@ A *session* is a correlation of all messages sent between two endpoints. *Instan - There is no general data store associated with a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] session. - If you are familiar with the class in [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] applications and the functionality it provides, you might notice the following differences between that kind of session and [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] sessions: + If you are familiar with the class in [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] applications and the functionality it provides, you might notice the following differences between that kind of session and [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] sessions: - [!INCLUDE[vstecasp](../../../../includes/vstecasp-md.md)] sessions are always server-initiated. @@ -44,7 +44,7 @@ A *session* is a correlation of all messages sent between two endpoints. *Instan Client applications and service applications interact with sessions in different ways. Client applications initiate sessions and then receive and process the messages sent within the session. Service applications can use sessions as an extensibility point to add additional behavior. This is done by working directly with the or implementing a custom instance context provider. ## Instancing - The instancing behavior (set by using the property) controls how the is created in response to incoming messages. By default, each is associated with one user-defined service object, so (in the default case) setting the property also controls the instancing of user-defined service objects. The enumeration defines the instancing modes. + The instancing behavior (set by using the property) controls how the is created in response to incoming messages. By default, each is associated with one user-defined service object, so (in the default case) setting the property also controls the instancing of user-defined service objects. The enumeration defines the instancing modes. The following instancing modes are available: @@ -64,20 +64,20 @@ public class CalculatorService : ICalculatorInstance } ``` - And while the property controls how often the is released, the and properties control when the service object is released. + And while the property controls how often the is released, the and properties control when the service object is released. ### Well-Known Singleton Services - One variation on single instance service objects is sometimes useful: you can create a service object yourself and create the service host using that object. To do so, you must also set the property to or an exception is thrown when the service host is opened. + One variation on single instance service objects is sometimes useful: you can create a service object yourself and create the service host using that object. To do so, you must also set the property to or an exception is thrown when the service host is opened. - Use the constructor to create such a service. It provides an alternative to implementing a custom when you wish to provide a specific object instance for use by a singleton service. You can use this overload when your service implementation type is difficult to construct (for example, if it does not implement a default parameterless public constructor). + Use the constructor to create such a service. It provides an alternative to implementing a custom when you wish to provide a specific object instance for use by a singleton service. You can use this overload when your service implementation type is difficult to construct (for example, if it does not implement a default parameterless public constructor). - Note that when an object is provided to this constructor, some features related to the [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] instancing behavior work differently. For example, calling has no effect when a singleton object instance is provided. Similarly, any other instance-release mechanism is ignored. The always behaves as if the property is set to for all operations. + Note that when an object is provided to this constructor, some features related to the [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] instancing behavior work differently. For example, calling has no effect when a singleton object instance is provided. Similarly, any other instance-release mechanism is ignored. The always behaves as if the property is set to for all operations. ### Sharing InstanceContext Objects You can also control which sessionful channel or call is associated with which object by performing that association yourself. ## Concurrency - Concurrency is the control of the number of threads active in an at any one time. This is controlled by using the with the enumeration. + Concurrency is the control of the number of threads active in an at any one time. This is controlled by using the with the enumeration. The following three concurrency modes are available: @@ -103,9 +103,9 @@ public class CalculatorService : ICalculatorConcurrency ``` ## Sessions Interact with InstanceContext Settings - Sessions and interact depending upon the combination of the value of the enumeration in a contract and the property on the service implementation, which controls the association between channels and specific service objects. + Sessions and interact depending upon the combination of the value of the enumeration in a contract and the property on the service implementation, which controls the association between channels and specific service objects. - The following table shows the result of an incoming channel either supporting sessions or not supporting sessions given a service's combination of the values of the property and the property. + The following table shows the result of an incoming channel either supporting sessions or not supporting sessions given a service's combination of the values of the property and the property. |InstanceContextMode value|||| |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/docs/framework/wcf/feature-details/syndication-extensibility.md b/docs/framework/wcf/feature-details/syndication-extensibility.md index 2a5533c4a3348..5b23a6d05488a 100644 --- a/docs/framework/wcf/feature-details/syndication-extensibility.md +++ b/docs/framework/wcf/feature-details/syndication-extensibility.md @@ -33,7 +33,7 @@ The Syndication API is designed to provide a format-neutral programming model th A key feature of syndication protocols is extensibility. Both Atom 1.0 and RSS 2.0, add attributes and elements to syndication feeds that are not defined in the specifications. The [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] syndication programming model provides the following ways of working with custom attributes and extensions, loosely-typed access and deriving a new class. ## Loosely Typed Access - Adding extensions by deriving a new class requires writing additional code. Another option is accessing extensions in a loosely-typed way. All of the types defined in the syndication abstract data model contain properties named `AttributeExtensions` and `ElementExtensions` (with one exception, has an `AttributeExtensions` property but no `ElementExtensions` property). These properties are collections of extensions not processed by the `TryParseAttribute` and `TryParseElement` methods respectively. You can access these unprocessed extensions by calling on the `ElementExtensions` property of , , , , and . This set of methods finds all extensions with the specified name and namespace, deserializes them individually into instances of `TExtension` and returns them as a collection of `TExtension` objects. + Adding extensions by deriving a new class requires writing additional code. Another option is accessing extensions in a loosely-typed way. All of the types defined in the syndication abstract data model contain properties named `AttributeExtensions` and `ElementExtensions` (with one exception, has an `AttributeExtensions` property but no `ElementExtensions` property). These properties are collections of extensions not processed by the `TryParseAttribute` and `TryParseElement` methods respectively. You can access these unprocessed extensions by calling on the `ElementExtensions` property of , , , , and . This set of methods finds all extensions with the specified name and namespace, deserializes them individually into instances of `TExtension` and returns them as a collection of `TExtension` objects. ## Deriving a New Class You can derive a new class from any of the existing abstract data model classes. Do this when implementing an application in which most of the feeds you are working with have a particular extension. In this topic, most of the feeds that the program works with contain a `MyExtension` extension. To provide an improved programming experience, do the following steps: diff --git a/docs/framework/wcf/feature-details/understanding-generated-client-code.md b/docs/framework/wcf/feature-details/understanding-generated-client-code.md index 8e6319617476e..f9ce24789a407 100644 --- a/docs/framework/wcf/feature-details/understanding-generated-client-code.md +++ b/docs/framework/wcf/feature-details/understanding-generated-client-code.md @@ -34,7 +34,7 @@ The [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framewor - Identifying the helper service contract channel interface. ### Finding Service Contract Interfaces - To locate the interfaces that model service contracts, search for interfaces that are marked with the attribute. Often this attribute can be difficult to locate with a quick read due to the presence of other attributes and the explicit properties set on the attribute itself. Remember that the service contract interface and the client contract interface are two different types. The following code example shows the original service contract. + To locate the interfaces that model service contracts, search for interfaces that are marked with the attribute. Often this attribute can be difficult to locate with a quick read due to the presence of other attributes and the explicit properties set on the attribute itself. Remember that the service contract interface and the client contract interface are two different types. The following code example shows the original service contract. [!code-csharp[C_GeneratedCodeFiles#22](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#22)] @@ -42,10 +42,10 @@ The [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framewor [!code-csharp[C_GeneratedCodeFiles#12](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#12)] - You can use the generated service contract interface along with the class to create a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] channel object with which to invoke service operations. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][How to: Use the ChannelFactory](../../../../docs/framework/wcf/feature-details/how-to-use-the-channelfactory.md). + You can use the generated service contract interface along with the class to create a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] channel object with which to invoke service operations. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][How to: Use the ChannelFactory](../../../../docs/framework/wcf/feature-details/how-to-use-the-channelfactory.md). ### Finding WCF Client Classes - To locate the [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client class that implements the service contract you want to use, search for an extension of , where the type parameter is the service contract interface that you previously located and that extends that interface. The following code example shows the class of type `ISampleService`. + To locate the [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] client class that implements the service contract you want to use, search for an extension of , where the type parameter is the service contract interface that you previously located and that extends that interface. The following code example shows the class of type `ISampleService`. [!code-csharp[C_GeneratedCodeFiles#14](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#14)] @@ -66,7 +66,7 @@ The [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framewor In this case the data type is the detail type thrown by a specific exception on the client, a where the detail type parameter is `microsoft.wcf.documentation.SampleFault`. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] data types, see [Specifying Data Transfer in Service Contracts](../../../../docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md). [!INCLUDE[crabout](../../../../includes/crabout-md.md)] handling exceptions in clients, see [Sending and Receiving Faults](../../../../docs/framework/wcf/sending-and-receiving-faults.md). ### Finding Callback Contracts for Duplex Services - If you locate a service contract for which the contract interface specifies a value for the property, then that contract specifies a duplex contract. Duplex contracts require the client application to create a callback class that implements the callback contract and pass an instance of that class to the or used to communicate with the service. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] duplex clients, see [How to: Access Services with a Duplex Contract](../../../../docs/framework/wcf/feature-details/how-to-access-services-with-a-duplex-contract.md). + If you locate a service contract for which the contract interface specifies a value for the property, then that contract specifies a duplex contract. Duplex contracts require the client application to create a callback class that implements the callback contract and pass an instance of that class to the or used to communicate with the service. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] duplex clients, see [How to: Access Services with a Duplex Contract](../../../../docs/framework/wcf/feature-details/how-to-access-services-with-a-duplex-contract.md). The following contract specifies a callback contract of type `SampleDuplexHelloCallback`. @@ -79,7 +79,7 @@ The [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framewor [!code-vb[C_GeneratedCodeFiles#4](../../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_generatedcodefiles/vb/duplexproxycode.vb#4)] ### Finding Service Contract Channel Interfaces - When using the class with a service contract interface, you must cast to the interface to explicitly open, close, or abort the channel. To make it easier to work with, the Svcutil.exe tool also generates a helper interface that implements both the service contract interface and to enable you to interact with the client channel infrastructure without having to cast. The following code shows the definition of a helper client channel that implements the preceding service contract. + When using the class with a service contract interface, you must cast to the interface to explicitly open, close, or abort the channel. To make it easier to work with, the Svcutil.exe tool also generates a helper interface that implements both the service contract interface and to enable you to interact with the client channel infrastructure without having to cast. The following code shows the definition of a helper client channel that implements the preceding service contract. [!code-csharp[C_GeneratedCodeFiles#13](../../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#13)] diff --git a/docs/framework/wcf/feature-details/unsupported-scenarios.md b/docs/framework/wcf/feature-details/unsupported-scenarios.md index 6372c7f008ac9..03f56909554ef 100644 --- a/docs/framework/wcf/feature-details/unsupported-scenarios.md +++ b/docs/framework/wcf/feature-details/unsupported-scenarios.md @@ -34,7 +34,7 @@ For various reasons, [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] doe - A state-based security context token (SCT) is created (by default, creation is disabled). - The state-based SCT can only be created using a custom binding. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][How to: Create a Security Context Token for a Secure Session](../../../../docs/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session.md).) In code, the token is enabled by creating a security binding element (either or ) using the or the method and setting the `requireCancellation` parameter to `false`. The parameter refers to the caching of the SCT. Setting the value to `false` enables the state-based SCT feature. + The state-based SCT can only be created using a custom binding. [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][How to: Create a Security Context Token for a Secure Session](../../../../docs/framework/wcf/feature-details/how-to-create-a-security-context-token-for-a-secure-session.md).) In code, the token is enabled by creating a security binding element (either or ) using the or the method and setting the `requireCancellation` parameter to `false`. The parameter refers to the caching of the SCT. Setting the value to `false` enables the state-based SCT feature. Alternatively, in configuration, the token is enabled by creating a <`customBinding`>, then adding a <`security`> element, and setting the `authenticationMode` attribute to SecureConversation and the `requireSecurityContextCancellation` attribute to `true`. diff --git a/docs/framework/wcf/feature-details/using-message-contracts.md b/docs/framework/wcf/feature-details/using-message-contracts.md index 23fe7f78954c4..a189ce1def70f 100644 --- a/docs/framework/wcf/feature-details/using-message-contracts.md +++ b/docs/framework/wcf/feature-details/using-message-contracts.md @@ -118,7 +118,7 @@ public class BankingTransaction By default, the namespace is the same as the namespace of the service contract that the message is participating in, and the name is determined by the member name to which the or the attributes are applied. - You can change these defaults by manipulating the and (on the parent class of the and attributes). + You can change these defaults by manipulating the and (on the parent class of the and attributes). Consider the class in the following code example. @@ -160,7 +160,7 @@ public class BankingTransaction > Having more than one message body part in messages that are not wrapped is not compliant with WS-I Basic Profile 1.1 and is not recommended when designing new message contracts. However, it may be necessary to have more than one unwrapped message body part in certain specific interoperability scenarios. If you are going to transmit more than one piece of data in a message body, it is recommended to use the default (wrapped) mode. Having more than one message header in unwrapped messages is completely acceptable. ## Using Custom Types Inside Message Contracts - Each individual message header and message body part is serialized (turned into XML) using the chosen serialization engine for the service contract where the message is used. The default serialization engine, the `XmlFormatter`, can handle any type that has a data contract, either explicitly (by having the ) or implicitly (by being a primitive type, having the , and so on). [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Using Data Contracts](../../../../docs/framework/wcf/feature-details/using-data-contracts.md). + Each individual message header and message body part is serialized (turned into XML) using the chosen serialization engine for the service contract where the message is used. The default serialization engine, the `XmlFormatter`, can handle any type that has a data contract, either explicitly (by having the ) or implicitly (by being a primitive type, having the , and so on). [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Using Data Contracts](../../../../docs/framework/wcf/feature-details/using-data-contracts.md). In the preceding example, the `Operation` and `BankingTransactionData` types must have a data contract, and `transactionDate` is serializable because is a primitive (and so has an implicit data contract). @@ -219,7 +219,7 @@ public class BankingDepositLog ## Signing and Encrypting Parts of the Message A message contract can indicate whether the headers and/or body of the message should be digitally signed and encrypted. - This is done by setting the property on the and attributes. The property is an enumeration of the type and can be set to (no encryption or signature), (digital signature only), or (both encryption and a digital signature). The default is . + This is done by setting the property on the and attributes. The property is an enumeration of the type and can be set to (no encryption or signature), (digital signature only), or (both encryption and a digital signature). The default is . For these security features to work, you must properly configure the binding and behaviors. If you use these security features without the proper configuration (for example, attempting to sign a message without supplying your credentials), an exception is thrown at validation time. @@ -245,7 +245,7 @@ public class PatientRecord In this example, the `recordID` header is not protected, `patientName` is `signed`, and `SSN` is encrypted and signed. At least one body part, `medicalHistory`, has applied, and thus the entire message body is encrypted and signed, even though the comments and diagnosis body parts specify lower protection levels. ## SOAP Action - SOAP and related Web services standards define a property called `Action` that can be present for every SOAP message sent. The operation's and properties control the value of this property. + SOAP and related Web services standards define a property called `Action` that can be present for every SOAP message sent. The operation's and properties control the value of this property. ## SOAP Header Attributes The SOAP standard defines the following attributes that may exist on a header: @@ -258,7 +258,7 @@ public class PatientRecord The `Actor` or `Role` attribute specifies the Uniform Resource Identifier (URI) of the node for which a given header is intended. The `MustUnderstand` attribute specifies whether the node processing the header must understand it. The `Relay` attribute specifies whether the header is to be relayed to downstream nodes. [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] does not perform any processing of these attributes on incoming messages, except for the `MustUnderstand` attribute, as specified in the "Message Contract Versioning" section later in this topic. However, it allows you to read and write these attributes as necessary, as in the following description. - When sending a message, these attributes are not emitted by default. You can change this in two ways. First, you may statically set the attributes to any desired values by changing the , , and properties, as shown in the following code example. (Note that there is no `Role` property; setting the property emits the `Role` attribute if you are using SOAP 1.2). + When sending a message, these attributes are not emitted by default. You can change this in two ways. First, you may statically set the attributes to any desired values by changing the , , and properties, as shown in the following code example. (Note that there is no `Role` property; setting the property emits the `Role` attribute if you are using SOAP 1.2). ```csharp [MessageContract] @@ -309,7 +309,7 @@ bt.documentApprover.MustUnderstand = false; // override the static default of 't When a message is received and then sent back, the SOAP attribute settings only go round-trip for headers of the type. ## Order of SOAP Body Parts - In some circumstances, you may need to control the order of the body parts. The order of the body elements is alphabetical by default, but can be controlled by the property. This property has the same semantics as the property, except for the behavior in inheritance scenarios (in message contracts, base type body members are not sorted before the derived type body members). [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Data Member Order](../../../../docs/framework/wcf/feature-details/data-member-order.md). + In some circumstances, you may need to control the order of the body parts. The order of the body elements is alphabetical by default, but can be controlled by the property. This property has the same semantics as the property, except for the behavior in inheritance scenarios (in message contracts, base type body members are not sorted before the derived type body members). [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)][Data Member Order](../../../../docs/framework/wcf/feature-details/data-member-order.md). In the following example, `amount` would normally come first because it is first alphabetically. However, the property puts it into the third position. @@ -342,7 +342,7 @@ public class BankingTransaction - All of the message headers in the inheritance hierarchy are collected together to form the full set of headers for the message. -- All of the message body parts in the inheritance hierarchy are collected together to form the full message body. The body parts are ordered according to the usual ordering rules (by property and then alphabetical), with no relevance to their place in the inheritance hierarchy. Using message contract inheritance where message body parts occur at multiple levels of the inheritance tree is strongly discouraged. If a base class and a derived class define a header or a body part with the same name, the member from the base-most class is used to store the value of that header or body part. +- All of the message body parts in the inheritance hierarchy are collected together to form the full message body. The body parts are ordered according to the usual ordering rules (by property and then alphabetical), with no relevance to their place in the inheritance hierarchy. Using message contract inheritance where message body parts occur at multiple levels of the inheritance tree is strongly discouraged. If a base class and a derived class define a header or a body part with the same name, the member from the base-most class is used to store the value of that header or body part. Consider the classes in the following code example. @@ -376,7 +376,7 @@ public class PatientRecord : PersonRecord - When using the same message contract in multiple operations, multiple message types are generated in the WSDL document. The names are made unique by adding the numbers "2", "3", and so on, for subsequent uses. When importing back the WSDL, multiple message contract types are created and are identical except for their names. ## SOAP Encoding Considerations - [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] allows you to use the legacy SOAP encoding style of XML, however, its use is not recommended. When using this style (by setting the `Use` property to `Encoded` on the applied to the service contract), the following additional considerations apply: + [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] allows you to use the legacy SOAP encoding style of XML, however, its use is not recommended. When using this style (by setting the `Use` property to `Encoded` on the applied to the service contract), the following additional considerations apply: - The message headers are not supported; this means that the attribute and the array attribute are incompatible with SOAP encoding. diff --git a/docs/framework/wcf/feature-details/web-services-protocols-supported-by-system-provided-interoperability-bindings.md b/docs/framework/wcf/feature-details/web-services-protocols-supported-by-system-provided-interoperability-bindings.md index 3568a72a4eb96..da87388667b5e 100644 --- a/docs/framework/wcf/feature-details/web-services-protocols-supported-by-system-provided-interoperability-bindings.md +++ b/docs/framework/wcf/feature-details/web-services-protocols-supported-by-system-provided-interoperability-bindings.md @@ -20,7 +20,7 @@ ms.author: "erikre" manager: "erikre" --- # Web Services Protocols Supported by System-Provided Interoperability Bindings -[!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] is built to interoperate with Web services that support a set of specifications known as Web services specifications. To simplify service configuration for interoperability best practices, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] introduces three interoperable system-provided bindings: , , and . For interoperability with Organization for the Advancement of Structured Information Standards (OASIS) standards, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] includes one interoperable system-provided binding: . For metadata publication, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] includes two interoperable system-provided bindings: [\](../../../../docs/framework/configure-apps/file-schema/wcf/mexhttpbinding.md) and [\](../../../../docs/framework/configure-apps/file-schema/wcf/mexhttpsbinding.md). This topic lists specifications that system-provided interoperable bindings support. +[!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] is built to interoperate with Web services that support a set of specifications known as Web services specifications. To simplify service configuration for interoperability best practices, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] introduces three interoperable system-provided bindings: , , and . For interoperability with Organization for the Advancement of Structured Information Standards (OASIS) standards, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] includes one interoperable system-provided binding: . For metadata publication, [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] includes two interoperable system-provided bindings: [\](../../../../docs/framework/configure-apps/file-schema/wcf/mexhttpbinding.md) and [\](../../../../docs/framework/configure-apps/file-schema/wcf/mexhttpsbinding.md). This topic lists specifications that system-provided interoperable bindings support. ## Web Services Protocols Supported by basicHttpBinding, wsHttpBinding, ws2007HttpBinding, and wsDualHttpBinding Bindings @@ -92,7 +92,7 @@ manager: "erikre" [!INCLUDE[crdefault](../../../../includes/crdefault-md.md)] [Federation](../../../../docs/framework/wcf/feature-details/federation.md) . ## System-Provided Metadata Bindings - The following tables describe the protocols supported by the system-provided interoperable metadata bindings exposed by the class. + The following tables describe the protocols supported by the system-provided interoperable metadata bindings exposed by the class. ### mexHttpBinding The [\](../../../../docs/framework/configure-apps/file-schema/wcf/mexhttpbinding.md) binding supports the following protocols. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] using this binding, see [Publishing Metadata](../../../../docs/framework/wcf/feature-details/publishing-metadata.md). diff --git a/docs/framework/wcf/feature-details/working-with-certificates.md b/docs/framework/wcf/feature-details/working-with-certificates.md index a2635f3effbc5..74544682bf173 100644 --- a/docs/framework/wcf/feature-details/working-with-certificates.md +++ b/docs/framework/wcf/feature-details/working-with-certificates.md @@ -70,10 +70,10 @@ To program [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] security, X.5 |Class|Property| |-----------|--------------| -||| -||| -||| -||| +||| +||| +||| +||| You can also set the property using configuration. The following elements are used to specify the validation mode: diff --git a/docs/framework/wcf/how-to-declare-faults-in-service-contracts.md b/docs/framework/wcf/how-to-declare-faults-in-service-contracts.md index 966f5f4bb3512..f9a0c74cef824 100644 --- a/docs/framework/wcf/how-to-declare-faults-in-service-contracts.md +++ b/docs/framework/wcf/how-to-declare-faults-in-service-contracts.md @@ -24,7 +24,7 @@ In managed code, exceptions are thrown when error conditions occur. In [!INCLUDE 2. Select an operation that can specify an error condition about which clients can expect to be notified. To decide which error conditions justify returning SOAP faults to clients, see [Specifying and Handling Faults in Contracts and Services](../../../docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md). -3. Apply a to the selected operation and pass a serializable fault type to the constructor. For details about creating and using serializable types, see [Specifying Data Transfer in Service Contracts](../../../docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md). The following example shows how to specify that the `SampleMethod` operation can result in a `GreetingFault`. +3. Apply a to the selected operation and pass a serializable fault type to the constructor. For details about creating and using serializable types, see [Specifying Data Transfer in Service Contracts](../../../docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md). The following example shows how to specify that the `SampleMethod` operation can result in a `GreetingFault`. [!code-csharp[FaultContractAttribute#4](../../../samples/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/services.cs#4)] [!code-vb[FaultContractAttribute#4](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb#4)] @@ -36,7 +36,7 @@ In managed code, exceptions are thrown when error conditions occur. In [!INCLUDE #### Throw the specified SOAP fault in the operation -1. When a -specified error condition occurs in an operation, throw a new where the specified SOAP fault is the type parameter. The following example shows how to throw the `GreetingFault` in the `SampleMethod` shown in the preceding procedure and in the following Code section. +1. When a -specified error condition occurs in an operation, throw a new where the specified SOAP fault is the type parameter. The following example shows how to throw the `GreetingFault` in the `SampleMethod` shown in the preceding procedure and in the following Code section. [!code-csharp[FaultContractAttribute#5](../../../samples/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/services.cs#5)] [!code-vb[FaultContractAttribute#5](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb#5)] @@ -48,5 +48,5 @@ In managed code, exceptions are thrown when error conditions occur. In [!INCLUDE [!code-vb[FaultContractAttribute#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb#1)] ## See Also - - + + diff --git a/docs/framework/wcf/how-to-host-a-wcf-service-in-a-managed-application.md b/docs/framework/wcf/how-to-host-a-wcf-service-in-a-managed-application.md index 1c623be42a2c3..ba6fcb28e8252 100644 --- a/docs/framework/wcf/how-to-host-a-wcf-service-in-a-managed-application.md +++ b/docs/framework/wcf/how-to-host-a-wcf-service-in-a-managed-application.md @@ -21,7 +21,7 @@ manager: "erikre" # How to: Host a WCF Service in a Managed Application To host a service inside a managed application, embed the code for the service inside the managed application code, define an endpoint for the service either imperatively in code, declaratively through configuration, or using default endpoints, and then create an instance of . - To start receiving messages, call on . This creates and opens the listener for the service. Hosting a service in this way is often referred to as "self-hosting" because the managed application is doing the hosting work itself. To close the service, call on . + To start receiving messages, call on . This creates and opens the listener for the service. Hosting a service in this way is often referred to as "self-hosting" because the managed application is doing the hosting work itself. To close the service, call on . A service can also be hosted in a managed Windows service, in Internet Information Services (IIS), or in Windows Process Activation Service (WAS). [!INCLUDE[crabout](../../../includes/crabout-md.md)] hosting options for a service, see [Hosting Services](../../../docs/framework/wcf/hosting-services.md). diff --git a/docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md b/docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md index d844c2556796e..49d36048e2b74 100644 --- a/docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md +++ b/docs/framework/wcf/how-to-implement-an-asynchronous-service-operation.md @@ -20,9 +20,9 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a service ### Implement a service operation asynchronously -1. In your service contract, declare an asynchronous method pair according to the .NET asynchronous design guidelines. The `Begin` method takes a parameter, a callback object, and a state object, and returns a and a matching `End` method that takes a and returns the return value. For more information about asynchronous calls, see [Asynchronous Programming Design Patterns](http://go.microsoft.com/fwlink/?LinkId=248221). +1. In your service contract, declare an asynchronous method pair according to the .NET asynchronous design guidelines. The `Begin` method takes a parameter, a callback object, and a state object, and returns a and a matching `End` method that takes a and returns the return value. For more information about asynchronous calls, see [Asynchronous Programming Design Patterns](http://go.microsoft.com/fwlink/?LinkId=248221). -2. Mark the `Begin` method of the asynchronous method pair with the attribute and set the property to `true`. For example, the following code performs steps 1 and 2. +2. Mark the `Begin` method of the asynchronous method pair with the attribute and set the property to `true`. For example, the following code performs steps 1 and 2. [!code-csharp[C_SyncAsyncClient#6](../../../samples/snippets/csharp/VS_Snippets_CFX/c_syncasyncclient/cs/services.cs#6)] [!code-vb[C_SyncAsyncClient#6](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_syncasyncclient/vb/services.vb#6)] @@ -43,7 +43,7 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a service 3. An asynchronous `BeginServiceAsyncMethod`/`EndServiceAsyncMethod` operation pair. -2. A service implementation using a object. +2. A service implementation using a object. [!code-csharp[C_SyncAsyncClient#1](../../../samples/snippets/csharp/VS_Snippets_CFX/c_syncasyncclient/cs/services.cs#1)] [!code-vb[C_SyncAsyncClient#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/c_syncasyncclient/vb/services.vb#1)] diff --git a/docs/framework/wcf/how-to-restrict-access-with-the-principalpermissionattribute-class.md b/docs/framework/wcf/how-to-restrict-access-with-the-principalpermissionattribute-class.md index 1741e03e6b3ee..05fa91f44f0b1 100644 --- a/docs/framework/wcf/how-to-restrict-access-with-the-principalpermissionattribute-class.md +++ b/docs/framework/wcf/how-to-restrict-access-with-the-principalpermissionattribute-class.md @@ -64,7 +64,7 @@ Controlling the access to resources on a Windows-domain computer is a basic secu 1. Apply the class to the method you want to restrict access to. -2. Set the action of the attribute to . +2. Set the action of the attribute to . 3. Set the `Name` property to a string that consists of the subject name and the certificate's thumbprint. Separate the two values with a semicolon and a space, as shown in the following example: diff --git a/docs/framework/wcf/introduction-to-extensibility.md b/docs/framework/wcf/introduction-to-extensibility.md index 6a545093f82d2..aac5771c1bee4 100644 --- a/docs/framework/wcf/introduction-to-extensibility.md +++ b/docs/framework/wcf/introduction-to-extensibility.md @@ -54,9 +54,9 @@ The [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] application model is de To create channels that support custom transports or protocol functionality, see [Extending the Channel Layer](../../../docs/framework/wcf/extending/extending-the-channel-layer.md). ### Extending the Service Hosting System - To modify the service-wide application model, you must extend class. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Extending ServiceHost and the Service Model Layer](../../../docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md). + To modify the service-wide application model, you must extend class. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Extending ServiceHost and the Service Model Layer](../../../docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md). - To modify the relationship between the hosting application domain and the service host, you must extend the class. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Extending Hosting Using ServiceHostFactory](../../../docs/framework/wcf/extending/extending-hosting-using-servicehostfactory.md). + To modify the relationship between the hosting application domain and the service host, you must extend the class. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Extending Hosting Using ServiceHostFactory](../../../docs/framework/wcf/extending/extending-hosting-using-servicehostfactory.md). ## See Also [Extending WCF](../../../docs/framework/wcf/extending/extending-wcf.md) diff --git a/docs/framework/wcf/samples/custom-wsdl-publication.md b/docs/framework/wcf/samples/custom-wsdl-publication.md index 28aa2a3519df5..fa767a9c223db 100644 --- a/docs/framework/wcf/samples/custom-wsdl-publication.md +++ b/docs/framework/wcf/samples/custom-wsdl-publication.md @@ -18,13 +18,13 @@ manager: "erikre" # Custom WSDL Publication This sample demonstrates how to: -- Implement a on a custom attribute to export attribute properties as WSDL annotations. +- Implement a on a custom attribute to export attribute properties as WSDL annotations. -- Implement to import the custom WSDL annotations. +- Implement to import the custom WSDL annotations. -- Implement and on a custom contract behavior and a custom operation behavior, respectively, to write imported annotations as comments in the CodeDom for the imported contract and operation. +- Implement and on a custom contract behavior and a custom operation behavior, respectively, to write imported annotations as comments in the CodeDom for the imported contract and operation. -- Use the to download the WSDL, a to import the WSDL using the custom WSDL importer, and the to generate [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client code with the WSDL annotations as /// and ''' comments in C# and Visual Basic. +- Use the to download the WSDL, a to import the WSDL using the custom WSDL importer, and the to generate [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] client code with the WSDL annotations as /// and ''' comments in C# and Visual Basic. > [!NOTE] > The setup procedure and build instructions for this sample are located at the end of this topic. diff --git a/docs/framework/wcf/samples/instancing-initialization.md b/docs/framework/wcf/samples/instancing-initialization.md index c45189da51de0..c115fa502a7e7 100644 --- a/docs/framework/wcf/samples/instancing-initialization.md +++ b/docs/framework/wcf/samples/instancing-initialization.md @@ -29,7 +29,7 @@ This sample extends the [Pooling](../../../../docs/framework/wcf/samples/pooling ## IInstanceProvider In [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)], the EndpointDispatcher creates instances of a service class by using an instance provider that implements the interface. This interface has only two methods: -- : When a message arrives, the Dispatcher calls the method to create an instance of the service class to process the message. The frequency of the calls to this method is determined by the property. For example if the property is set to , a new instance of service class is created to process each message that arrives, so is called whenever a message arrives. +- : When a message arrives, the Dispatcher calls the method to create an instance of the service class to process the message. The frequency of the calls to this method is determined by the property. For example if the property is set to , a new instance of service class is created to process each message that arrives, so is called whenever a message arrives. - : When the service instance finishes processing the message, the EndpointDispatcher calls the method. As in the method, the frequency of the calls to this method is determined by the property. @@ -160,7 +160,7 @@ if (activeObjectsCount == 0) This sample uses a custom attribute. When the is constructed, it examines the attributes used in the service’s type definition and adds the available behaviors to the service description’s behaviors collection. - The interface has three methods: `,` `,` and . These methods are called by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] when the is being initialized. is called first; it allows the service to be inspected for inconsistencies. is called next; this method is only required in very advanced scenarios. is called last and is responsible for configuring the runtime. The following parameters are passed into : + The interface has three methods: `,` `,` and . These methods are called by [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] when the is being initialized. is called first; it allows the service to be inspected for inconsistencies. is called next; this method is only required in very advanced scenarios. is called last and is responsible for configuring the runtime. The following parameters are passed into : - `Description`: This parameter provides the service description for the entire service. This can be used to inspect description data about the service’s endpoints, contracts, bindings, and other data associated with the service. diff --git a/docs/framework/wcf/samples/metadata-extensibility.md b/docs/framework/wcf/samples/metadata-extensibility.md index 6aaa6ea96d917..be1b64ad67b3d 100644 --- a/docs/framework/wcf/samples/metadata-extensibility.md +++ b/docs/framework/wcf/samples/metadata-extensibility.md @@ -23,4 +23,4 @@ This section contains samples that demonstrate custom metadata. Demonstrates how to implement a service with a secure metadata endpoint that uses one of the non-metadata exchange bindings and how to configure [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) or clients to fetch the metadata from such a metadata endpoint. [Custom WSDL Publication](../../../../docs/framework/wcf/samples/custom-wsdl-publication.md) - Demonstrates how to implement a on a custom attribute to export attribute properties as WSDL annotations, among other functionality. + Demonstrates how to implement a on a custom attribute to export attribute properties as WSDL annotations, among other functionality. diff --git a/docs/framework/wcf/samples/operation-formatter-and-operation-selector.md b/docs/framework/wcf/samples/operation-formatter-and-operation-selector.md index f32e83c53299f..fd539c424281b 100644 --- a/docs/framework/wcf/samples/operation-formatter-and-operation-selector.md +++ b/docs/framework/wcf/samples/operation-formatter-and-operation-selector.md @@ -71,7 +71,7 @@ This sample demonstrates how [!INCLUDE[indigo1](../../../../includes/indigo1-md. ### Installing operation formatters Operation behaviors that specify formatters are unique. One such behavior is always implemented by default for every operation to create the necessary operation formatter. However, these behaviors look like just another operation behavior; they are not identifiable by any other attribute. To install a replacement behavior, the implementation must look for specific formatter behaviors that are installed by the [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] type loader by default and either replace it or add a compatible behavior to run after the default behavior. - These operation formatters behaviors can be set up programmatically prior to calling or by specifying an operation behavior that is executed after the default one. However, it cannot easily be set up by an endpoint behavior (and therefore by configuration) because the behavior model does not allow a behavior to replace other behaviors or otherwise modify the description tree. + These operation formatters behaviors can be set up programmatically prior to calling or by specifying an operation behavior that is executed after the default one. However, it cannot easily be set up by an endpoint behavior (and therefore by configuration) because the behavior model does not allow a behavior to replace other behaviors or otherwise modify the description tree. On the client: diff --git a/docs/framework/wcf/samples/wcf-analytic-tracing.md b/docs/framework/wcf/samples/wcf-analytic-tracing.md index 685b22c985d4c..99feced3193f5 100644 --- a/docs/framework/wcf/samples/wcf-analytic-tracing.md +++ b/docs/framework/wcf/samples/wcf-analytic-tracing.md @@ -16,14 +16,14 @@ ms.author: "erikre" manager: "erikre" --- # WCF Analytic Tracing -This sample demonstrates how to add your own tracing events into the stream of analytic traces that [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] writes to ETW in [!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)]. Analytic traces are meant to make it easy to get visibility into your services without paying a high performance penalty. This sample shows how to use the APIs to write events that integrate with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] services. +This sample demonstrates how to add your own tracing events into the stream of analytic traces that [!INCLUDE[indigo1](../../../../includes/indigo1-md.md)] writes to ETW in [!INCLUDE[netfx_current_long](../../../../includes/netfx-current-long-md.md)]. Analytic traces are meant to make it easy to get visibility into your services without paying a high performance penalty. This sample shows how to use the APIs to write events that integrate with [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] services. - [!INCLUDE[crabout](../../../../includes/crabout-md.md)] the APIs, see . + [!INCLUDE[crabout](../../../../includes/crabout-md.md)] the APIs, see . To learn more about event tracing in Windows, see [Improve Debugging and Performance Tuning with ETW](http://go.microsoft.com/fwlink/?LinkId=166488). ## Disposing EventProvider - This sample uses the class, which implements . When implementing tracing for a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service, it is likely that you may use the ’s resources for the lifetime of the service. For this reason, and for readability, this sample never disposes of the wrapped . If for some reason your service has different requirements for tracing and you must dispose of this resource, then you should modify this sample in accordance with the best practices for disposing of unmanaged resources. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] disposing unmanaged resources, see [Implementing a Dispose Method](http://go.microsoft.com/fwlink/?LinkId=166436). + This sample uses the class, which implements . When implementing tracing for a [!INCLUDE[indigo2](../../../../includes/indigo2-md.md)] service, it is likely that you may use the ’s resources for the lifetime of the service. For this reason, and for readability, this sample never disposes of the wrapped . If for some reason your service has different requirements for tracing and you must dispose of this resource, then you should modify this sample in accordance with the best practices for disposing of unmanaged resources. [!INCLUDE[crabout](../../../../includes/crabout-md.md)] disposing unmanaged resources, see [Implementing a Dispose Method](http://go.microsoft.com/fwlink/?LinkId=166436). ## Self-Hosting vs. Web Hosting For Web-hosted services, WCF’s analytic traces provide a field, called "HostReference", which is used to identify the service that is emitting the traces. The extensible user traces can participate in this model and this sample demonstrates best practices for doing so. The format of a Web host reference when the pipe ‘|’ character actually appears in the resulting string can be any one of the following: diff --git a/docs/framework/wcf/sending-and-receiving-faults.md b/docs/framework/wcf/sending-and-receiving-faults.md index 0ecbf8416bceb..12e1e6adf4d36 100644 --- a/docs/framework/wcf/sending-and-receiving-faults.md +++ b/docs/framework/wcf/sending-and-receiving-faults.md @@ -21,31 +21,31 @@ manager: "erikre" SOAP faults convey error condition information from a service to a client and in the duplex case from a client to a service in an interoperable way. Typically a service defines custom fault content and specifies which operations can return them. (For more information, see [Defining and Specifying Faults](../../../docs/framework/wcf/defining-and-specifying-faults.md).) This topic discusses how a service or duplex client can send those faults when the corresponding error condition has occurred and how a client or service application handles these faults. For an overview of error handling in [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, see [Specifying and Handling Faults in Contracts and Services](../../../docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md). ## Sending SOAP Faults - Declared SOAP faults are those in which an operation has a that specifies a custom SOAP fault type. Undeclared SOAP faults are those that are not specified in the contract for an operation. + Declared SOAP faults are those in which an operation has a that specifies a custom SOAP fault type. Undeclared SOAP faults are those that are not specified in the contract for an operation. ### Sending Declared Faults - To send a declared SOAP fault, detect the error condition for which the SOAP fault is appropriate and throw a new where the type parameter is a new object of the type specified in the for that operation. The following code example shows the use of to specify that the `SampleMethod` operation can return a SOAP fault with the detail type of `GreetingFault`. + To send a declared SOAP fault, detect the error condition for which the SOAP fault is appropriate and throw a new where the type parameter is a new object of the type specified in the for that operation. The following code example shows the use of to specify that the `SampleMethod` operation can return a SOAP fault with the detail type of `GreetingFault`. [!code-csharp[FaultContractAttribute#4](../../../samples/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/services.cs#4)] [!code-vb[FaultContractAttribute#4](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb#4)] - To convey the `GreetingFault` error information to the client, catch the appropriate error condition and throw a new of type `GreetingFault` with a new `GreetingFault` object as the argument, as in the following code example. If the client is an [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client application, it experiences this as a managed exception where the type is of type `GreetingFault`. + To convey the `GreetingFault` error information to the client, catch the appropriate error condition and throw a new of type `GreetingFault` with a new `GreetingFault` object as the argument, as in the following code example. If the client is an [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client application, it experiences this as a managed exception where the type is of type `GreetingFault`. [!code-csharp[FaultContractAttribute#5](../../../samples/snippets/csharp/VS_Snippets_CFX/faultcontractattribute/cs/services.cs#5)] [!code-vb[FaultContractAttribute#5](../../../samples/snippets/visualbasic/VS_Snippets_CFX/faultcontractattribute/vb/services.vb#5)] ### Sending Undeclared Faults - Sending undeclared faults can be very useful to quickly diagnose and debug problems in [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] applications, but its usefulness as a debugging tool is limited. More generally, when debugging it is recommended that you use the property. When you set this value to true, clients experience such faults as exceptions of type . + Sending undeclared faults can be very useful to quickly diagnose and debug problems in [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] applications, but its usefulness as a debugging tool is limited. More generally, when debugging it is recommended that you use the property. When you set this value to true, clients experience such faults as exceptions of type . > [!IMPORTANT] -> Because managed exceptions can expose internal application information, setting or to `true` can permit [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. +> Because managed exceptions can expose internal application information, setting or to `true` can permit [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. > -> Therefore, setting or to `true` is only recommended as a way of temporarily debugging a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients as objects) to obtain the debugging information properly. +> Therefore, setting or to `true` is only recommended as a way of temporarily debugging a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients as objects) to obtain the debugging information properly. - To send an undeclared SOAP fault, throw a object (that is, not the generic type ) and pass the string to the constructor. This is exposed to the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client applications as a thrown exception where the string is available by calling the method. + To send an undeclared SOAP fault, throw a object (that is, not the generic type ) and pass the string to the constructor. This is exposed to the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client applications as a thrown exception where the string is available by calling the method. > [!NOTE] -> If you declare a SOAP fault of type string, and then throw this in your service as a where the type parameter is a the string value is assigned to the property, and is not available from . +> If you declare a SOAP fault of type string, and then throw this in your service as a where the type parameter is a the string value is assigned to the property, and is not available from . ## Handling Faults In [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients, SOAP faults that occur during communication that are of interest to client applications are raised as managed exceptions. While there are many exceptions that can occur during the execution of any program, applications using the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client programming model can expect to handle exceptions of the following two types as a result of communication. @@ -60,17 +60,17 @@ SOAP faults convey error condition information from a service to a client and in The class has two important derived types, and the generic type. - exceptions are thrown when a listener receives a fault that is not expected or specified in the operation contract; usually this occurs when the application is being debugged and the service has the property set to `true`. + exceptions are thrown when a listener receives a fault that is not expected or specified in the operation contract; usually this occurs when the application is being debugged and the service has the property set to `true`. exceptions are thrown on the client when a fault that is specified in the operation contract is received in response to a two-way operation (that is, a method with an attribute with set to `false`). > [!NOTE] -> When an [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service has the or property set to `true` the client experiences this as an undeclared of type . Clients can either catch this specific fault or handle the fault in a catch block for . +> When an [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service has the or property set to `true` the client experiences this as an undeclared of type . Clients can either catch this specific fault or handle the fault in a catch block for . Typically, only , , and exceptions are of interest to clients and services. > [!NOTE] -> Other exceptions, of course, do occur. Unexpected exceptions include catastrophic failures like ; typically applications should not catch such methods. +> Other exceptions, of course, do occur. Unexpected exceptions include catastrophic failures like ; typically applications should not catch such methods. ### Catch Fault Exceptions in the Correct Order Because derives from , and derives from , it is important to catch these exceptions in the proper order. If, for example, you have a try/catch block in which you first catch , all specified and unspecified SOAP faults are handled there; any subsequent catch blocks to handle a custom exception are never invoked. @@ -86,9 +86,9 @@ SOAP faults convey error condition information from a service to a client and in - When the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object is recycled. -- When the client application calls . +- When the client application calls . -- When the client application calls . +- When the client application calls . - When the client application calls an operation that is a terminating operation for a session. @@ -110,6 +110,6 @@ SOAP faults convey error condition information from a service to a client and in ## See Also - + [Expected Exceptions](../../../docs/framework/wcf/samples/expected-exceptions.md) [Avoiding Problems with the Using Statement](../../../docs/framework/wcf/samples/avoiding-problems-with-the-using-statement.md) diff --git a/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md b/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md index 603890639701e..76f3f213f1d6c 100644 --- a/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md +++ b/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md @@ -25,7 +25,7 @@ manager: "erikre" Because [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] applications run under both types of error systems, any managed exception information that is sent to the client must be converted from exceptions into SOAP faults on the service, sent, and converted from SOAP faults to fault exceptions in [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients. In the case of duplex clients, client contracts can also send SOAP faults back to a service. In either case, you can use the default service exception behaviors, or you can explicitly control whether—and how—exceptions are mapped to fault messages. - Two types of SOAP faults can be sent: *declared* and *undeclared*. Declared SOAP faults are those in which an operation has a attribute that specifies a custom SOAP fault type. *Undeclared* SOAP faults are not specified in the contract for an operation. + Two types of SOAP faults can be sent: *declared* and *undeclared*. Declared SOAP faults are those in which an operation has a attribute that specifies a custom SOAP fault type. *Undeclared* SOAP faults are not specified in the contract for an operation. It is strongly recommended that service operations declare their faults by using the attribute to formally specify all SOAP faults that a client can expect to receive in the normal course of an operation. It is also recommended that you return in a SOAP fault only the information that a client must know to minimize information disclosure. @@ -48,15 +48,15 @@ manager: "erikre" [!INCLUDE[crdefault](../../../includes/crdefault-md.md)] [Sending and Receiving Faults](../../../docs/framework/wcf/sending-and-receiving-faults.md). ## Undeclared SOAP Faults and Debugging - Declared SOAP faults are extremely useful for building robust, interoperable, distributed applications. However, in some cases it is useful for a service (or duplex client) to send an undeclared SOAP fault, one that is not mentioned in the Web Services Description Language (WSDL) for that operation. For example, when developing a service, unexpected situations can occur in which it is useful for debugging purposes to send information back to the client. In addition, you can set the property or the property to `true` to permit [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients to obtain information about internal service operation exceptions. Both sending individual faults and setting the debugging behavior properties are described in [Sending and Receiving Faults](../../../docs/framework/wcf/sending-and-receiving-faults.md). + Declared SOAP faults are extremely useful for building robust, interoperable, distributed applications. However, in some cases it is useful for a service (or duplex client) to send an undeclared SOAP fault, one that is not mentioned in the Web Services Description Language (WSDL) for that operation. For example, when developing a service, unexpected situations can occur in which it is useful for debugging purposes to send information back to the client. In addition, you can set the property or the property to `true` to permit [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients to obtain information about internal service operation exceptions. Both sending individual faults and setting the debugging behavior properties are described in [Sending and Receiving Faults](../../../docs/framework/wcf/sending-and-receiving-faults.md). > [!IMPORTANT] -> Because managed exceptions can expose internal application information, setting or to `true` can permit [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. +> Because managed exceptions can expose internal application information, setting or to `true` can permit [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. > -> Therefore, setting or to `true` is recommended only as a way to temporarily debug a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients as objects) to obtain the debugging information properly. +> Therefore, setting or to `true` is recommended only as a way to temporarily debug a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] clients as objects) to obtain the debugging information properly. ## Customizing Error Handling with IErrorHandler - If you have special requirements to either customize the response message to the client when an application-level exception happens or perform some custom processing after the response message is returned, implement the interface. + If you have special requirements to either customize the response message to the client when an application-level exception happens or perform some custom processing after the response message is returned, implement the interface. ## Fault Serialization Issues When deserializing a fault contract, WCF first attempts to match the fault contract name in the SOAP message with the fault contract type. If it cannot find an exact match it will then search the list of available fault contracts in alphabetical order for a compatible type. If two fault contracts are compatible types (one is a subclass of another, for example) the wrong type may be used to de-serialize the fault. This only occurs if the fault contract does not specify a name, namespace, and action. To prevent this issue from occurring, always fully qualify fault contracts by specifying the name, namespace, and action attributes. Additionally if you have defined a number of related fault contracts derived from a shared base class, make sure to mark any new members with `[DataMember(IsRequired=true)]`. For more information on this `IsRequired` attribute see, . This will prevent a base class from being a compatible type and force the fault to be deserialized into the correct derived type. diff --git a/docs/framework/wcf/specifying-service-run-time-behavior.md b/docs/framework/wcf/specifying-service-run-time-behavior.md index 1ab7e00dc0057..4a06ae04f5084 100644 --- a/docs/framework/wcf/specifying-service-run-time-behavior.md +++ b/docs/framework/wcf/specifying-service-run-time-behavior.md @@ -23,7 +23,7 @@ Once you have designed a service contract ([Designing Service Contracts](../../. However, operation specifics, such as threading issues or instance management, are opaque to clients. Once you have implemented your service contract, you can configure a large number of operation characteristics by using *behaviors*. Behaviors are objects that modify the [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] runtime by either setting a runtime property or by inserting a customization type into the runtime. [!INCLUDE[crabout](../../../includes/crabout-md.md)] modifying the runtime by creating user-defined behaviors, see [Extending ServiceHost and the Service Model Layer](../../../docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md). - The and attributes are the most widely useful behaviors and expose the most commonly requested operation features. Because they are attributes, you apply them to the service or operation implementation. Other behaviors, such as the or , are typically applied using an application configuration file, although you can use them programmatically. + The and attributes are the most widely useful behaviors and expose the most commonly requested operation features. Because they are attributes, you apply them to the service or operation implementation. Other behaviors, such as the or , are typically applied using an application configuration file, although you can use them programmatically. This topic provides an overview of the and attributes, describes the various scopes at which behaviors can operate, and provides a quick description of many of the system-provided behaviors at the various scopes that may be of interest to [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] developers. @@ -48,7 +48,7 @@ Once you have designed a service contract ([Designing Service Contracts](../../. - Impersonation -- To use these attributes, mark the service or operation implementation with the attribute appropriate to that scope and set the properties. For example, the following code example shows an operation implementation that uses the property to require that callers of this operation support impersonation. +- To use these attributes, mark the service or operation implementation with the attribute appropriate to that scope and set the properties. For example, the following code example shows an operation implementation that uses the property to require that callers of this operation support impersonation. [!code-csharp[OperationBehaviorAttribute_Impersonation#1](../../../samples/snippets/csharp/VS_Snippets_CFX/operationbehaviorattribute_impersonation/cs/services.cs#1)] [!code-vb[OperationBehaviorAttribute_Impersonation#1](../../../samples/snippets/visualbasic/VS_Snippets_CFX/operationbehaviorattribute_impersonation/vb/services.vb#1)] @@ -58,16 +58,16 @@ Once you have designed a service contract ([Designing Service Contracts](../../. ### Well-Known Singleton Services You can use the and attributes to control certain lifetimes, both of the and of the service objects that implement the operations. - For example, the property controls how often the is released, and the and properties control when the service object is released. + For example, the property controls how often the is released, and the and properties control when the service object is released. - However, you can also create a service object yourself and create the service host using that object. To do so, you must also set the property to or an exception is thrown when the service host is opened. + However, you can also create a service object yourself and create the service host using that object. To do so, you must also set the property to or an exception is thrown when the service host is opened. - Use the constructor to create such a service. It provides an alternative to implementing a custom when you wish to provide a specific object instance for use by a singleton service. You can use this overload when your service implementation type is difficult to construct (for example, if it does not implement a default public constructor that has no parameters). + Use the constructor to create such a service. It provides an alternative to implementing a custom when you wish to provide a specific object instance for use by a singleton service. You can use this overload when your service implementation type is difficult to construct (for example, if it does not implement a default public constructor that has no parameters). - Note that when an object is provided to this constructor, some features related to the [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] instancing behavior work differently. For example, calling has no effect when a well-known object instance is provided. Similarly, any other instance release mechanism is ignored. The class always behaves as if the property is set to for all operations. + Note that when an object is provided to this constructor, some features related to the [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] instancing behavior work differently. For example, calling has no effect when a well-known object instance is provided. Similarly, any other instance release mechanism is ignored. The class always behaves as if the property is set to for all operations. ## Other Service, Endpoint, Contract, and Operation Behaviors - Service behaviors, such as the attribute, operate across an entire service. For example, if you set the property to you must handle thread synchronization issues inside each operation in that service yourself. Endpoint behaviors operate across an endpoint; many of the system-provided endpoint behaviors are for client functionality. Contract behaviors operate at the contract level, and operation behaviors modify operation delivery. + Service behaviors, such as the attribute, operate across an entire service. For example, if you set the property to you must handle thread synchronization issues inside each operation in that service yourself. Endpoint behaviors operate across an endpoint; many of the system-provided endpoint behaviors are for client functionality. Contract behaviors operate at the contract level, and operation behaviors modify operation delivery. Many of these behaviors are implemented on attributes, and you make use of them as you do the and attributes—by applying them to the appropriate service class or operation implementation. Other behaviors, such as the or objects, are typically applied using an application configuration file, although they can also be used programmatically. @@ -117,7 +117,7 @@ Once you have designed a service contract ([Designing Service Contracts](../../. ### Operation Behaviors The following operation behaviors specify serialization and transaction controls for operations. -- . Represents the run-time behavior of the . +- . Represents the run-time behavior of the . - . Controls run-time behavior of the `XmlSerializer` and associates it with an operation. diff --git a/docs/framework/wcf/synchronous-and-asynchronous-operations.md b/docs/framework/wcf/synchronous-and-asynchronous-operations.md index f957bdb21a93d..32eb7b52450fd 100644 --- a/docs/framework/wcf/synchronous-and-asynchronous-operations.md +++ b/docs/framework/wcf/synchronous-and-asynchronous-operations.md @@ -167,7 +167,7 @@ svcutil http://localhost:8000/servicemodelsamples/service/mex /async /tcv:Versio When this is done, Svcutil.exe generates a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client class with the event infrastructure that enables the calling application to implement and assign an event handler to receive the response and take the appropriate action. For a complete example, see [How to: Call Service Operations Asynchronously](../../../docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md). - The event-based asynchronous model, however, is only available in [!INCLUDE[netfx35_long](../../../includes/netfx35-long-md.md)]. In addition, it is not supported even in [!INCLUDE[netfx35_short](../../../includes/netfx35-short-md.md)] when a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client channel is created by using a . With [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client channel objects, you must use objects to invoke your operations asynchronously. To use this approach, specify the **/async** command option with the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md), as in the following example. + The event-based asynchronous model, however, is only available in [!INCLUDE[netfx35_long](../../../includes/netfx35-long-md.md)]. In addition, it is not supported even in [!INCLUDE[netfx35_short](../../../includes/netfx35-short-md.md)] when a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client channel is created by using a . With [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client channel objects, you must use objects to invoke your operations asynchronously. To use this approach, specify the **/async** command option with the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md), as in the following example. ``` svcutil http://localhost:8000/servicemodelsamples/service/mex /async @@ -178,7 +178,7 @@ svcutil http://localhost:8000/servicemodelsamples/service/mex /async In either case, applications can invoke an operation asynchronously even if the service is implemented synchronously, in the same way that an application can use the same pattern to invoke asynchronously a local synchronous method. How the operation is implemented is not significant to the client; when the response message arrives, its content is dispatched to the client's asynchronous <`End`> method and the client retrieves the information. ### One-Way Message Exchange Patterns - You can also create an asynchronous message exchange pattern in which one-way operations (operations for which the is `true` have no correlated response) can be sent in either direction by the client or service independently of the other side. (This uses the duplex message exchange pattern with one-way messages.) In this case, the service contract specifies a one-way message exchange that either side can implement as asynchronous calls or implementations, or not, as appropriate. Generally, when the contract is an exchange of one-way messages, the implementations can largely be asynchronous because once a message is sent the application does not wait for a reply and can continue doing other work. + You can also create an asynchronous message exchange pattern in which one-way operations (operations for which the is `true` have no correlated response) can be sent in either direction by the client or service independently of the other side. (This uses the duplex message exchange pattern with one-way messages.) In this case, the service contract specifies a one-way message exchange that either side can implement as asynchronous calls or implementations, or not, as appropriate. Generally, when the contract is an exchange of one-way messages, the implementations can largely be asynchronous because once a message is sent the application does not wait for a reply and can continue doing other work. ### Event-based Asynchronous Clients and Message Contracts The design guidelines for the event-based asynchronous model state that if more than one value is returned, one value is returned as the `Result` property and the others are returned as properties on the object. One result of this is that if a client imports metadata using the event-based asynchronous command options and the operation returns more than one value, the default object returns one value as the `Result` property and the remainder are properties of the object. diff --git a/docs/framework/wcf/using-sessions.md b/docs/framework/wcf/using-sessions.md index 0c14683a55e65..08312bc76ee27 100644 --- a/docs/framework/wcf/using-sessions.md +++ b/docs/framework/wcf/using-sessions.md @@ -33,7 +33,7 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a *session - There is no general data store associated with a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] session. - If you are familiar with the class in [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)] applications and the functionality it provides, you might notice the following differences between that kind of session and [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] sessions: + If you are familiar with the class in [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)] applications and the functionality it provides, you might notice the following differences between that kind of session and [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] sessions: - [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)] sessions are always server-initiated. @@ -52,7 +52,7 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a *session - How to understand and control the creation and termination of the session and the relationship of the session to the service instance. ## Default Execution Behavior Using Sessions - A binding that attempts to initiate a session is called a *session-based* binding. Service contracts specify that they require, permit, or refuse session-based bindings by setting the property on the service contract interface (or class) to one of the enumeration values. By default, the value of this property is , which means that if a client uses a session-based binding with a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service implementation, the service establishes and uses the session provided. + A binding that attempts to initiate a session is called a *session-based* binding. Service contracts specify that they require, permit, or refuse session-based bindings by setting the property on the service contract interface (or class) to one of the enumeration values. By default, the value of this property is , which means that if a client uses a session-based binding with a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service implementation, the service establishes and uses the session provided. When a [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service accepts a client session, the following features are enabled by default: @@ -65,18 +65,18 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a *session [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] provides the following types of session-based application behavior: -- The supports security-based sessions, in which both ends of communication have agreed upon a specific secure conversation. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Securing Services](../../../docs/framework/wcf/securing-services.md). For example, the binding, which contains support for both security sessions and reliable sessions, by default uses only a secure session that encrypts and digitally signs messages. +- The supports security-based sessions, in which both ends of communication have agreed upon a specific secure conversation. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Securing Services](../../../docs/framework/wcf/securing-services.md). For example, the binding, which contains support for both security sessions and reliable sessions, by default uses only a secure session that encrypts and digitally signs messages. -- The binding supports TCP/IP-based sessions to ensure that all messages are correlated by the connection at the socket level. +- The binding supports TCP/IP-based sessions to ensure that all messages are correlated by the connection at the socket level. -- The element, which implements the WS-ReliableMessaging specification, provides support for reliable sessions in which messages can be configured to be delivered in order and exactly once, ensuring messages are received even when messages travel across multiple nodes during the conversation. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Reliable Sessions](../../../docs/framework/wcf/feature-details/reliable-sessions.md). +- The element, which implements the WS-ReliableMessaging specification, provides support for reliable sessions in which messages can be configured to be delivered in order and exactly once, ensuring messages are received even when messages travel across multiple nodes during the conversation. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Reliable Sessions](../../../docs/framework/wcf/feature-details/reliable-sessions.md). -- The binding provides MSMQ datagram sessions. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Queues in WCF](../../../docs/framework/wcf/feature-details/queues-in-wcf.md). +- The binding provides MSMQ datagram sessions. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Queues in WCF](../../../docs/framework/wcf/feature-details/queues-in-wcf.md). Setting the property does not specify the type of session the contract requires, only that it requires one. ## Creating a Contract That Requires a Session - Creating a contract that requires a session states that the group of operations that the service contract declares must all be executed within the same session and that messages must be delivered in order. To assert the level of session support that a service contract requires, set the property on your service contract interface or class to the value of the enumeration to specify whether the contract: + Creating a contract that requires a session states that the group of operations that the service contract declares must all be executed within the same session and that messages must be delivered in order. To assert the level of session support that a service contract requires, set the property on your service contract interface or class to the value of the enumeration to specify whether the contract: - Requires a session. @@ -84,7 +84,7 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a *session - Prohibits a session. - Setting the property does not, however, specify the type of session-based behavior the contract requires. It instructs [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] to confirm at runtime that the configured binding (which creates the communication channel) for the service does, does not, or can establish a session when implementing a service. Again, the binding can satisfy that requirement with any type of session-based behavior it chooses—security, transport, reliable, or some combination. The exact behavior depends on the value selected. If the configured binding of the service does not conform to the value of , an exception is thrown. Bindings and the channels they create that support sessions are said to be session-based. + Setting the property does not, however, specify the type of session-based behavior the contract requires. It instructs [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] to confirm at runtime that the configured binding (which creates the communication channel) for the service does, does not, or can establish a session when implementing a service. Again, the binding can satisfy that requirement with any type of session-based behavior it chooses—security, transport, reliable, or some combination. The exact behavior depends on the value selected. If the configured binding of the service does not conform to the value of , an exception is thrown. Bindings and the channels they create that support sessions are said to be session-based. The following service contract specifies that all operations in the `ICalculatorSession` must be exchanged within a session. None of the operations returns a value to the caller except the `Equals` method. However, the `Equals` method takes no parameters and, therefore, can only return a non-zero value inside a session in which data has already been passed to the other operations. This contract requires a session to function properly. Without a session associated with a specific client, the service instance has no way of knowing what previous data this client has sent. @@ -109,7 +109,7 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a *session *Terminating operations*, conversely, are those that must be called as the last message in an existing session. In the default case, [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] recycles the service object and its context after the session with which the service was associated is closed. You can, therefore, create a kind of destructor by declaring terminating operations designed to perform a function appropriate to the end of the service instance. > [!NOTE] -> Although the default behavior bears a resemblance to local constructors and destructors, it is only a resemblance. Any [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service operation can be an initiating or terminating operation, or both at the same time. In addition, in the default case, initiating operations can be called any number of times in any order; no additional sessions are created once the session is established and associated with an instance unless you explicitly control the lifetime of the service instance (by manipulating the object). Finally, the state is associated with the session and not the service object. +> Although the default behavior bears a resemblance to local constructors and destructors, it is only a resemblance. Any [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] service operation can be an initiating or terminating operation, or both at the same time. In addition, in the default case, initiating operations can be called any number of times in any order; no additional sessions are created once the session is established and associated with an instance unless you explicitly control the lifetime of the service instance (by manipulating the object). Finally, the state is associated with the session and not the service object. For example, the `ICalculatorSession` contract used in the preceding example requires that the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object first call the `Clear` operation prior to any other operation and that the session with this [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object should terminate when it calls the `Equals` operation. The following code example shows a contract that enforces these requirements. `Clear` must be called first to initiate a session, and that session ends when `Equals` is called. @@ -118,17 +118,17 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a *session Services do not start sessions with clients. In [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client applications, a direct relationship exists between the lifetime of the session-based channel and the lifetime of the session itself. As such, clients create new sessions by creating new session-based channels and tear down existing sessions by closing session-based channels gracefully. A client starts a session with a service endpoint by calling one of the following: -- on the channel returned by a call to . +- on the channel returned by a call to . -- on the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object generated by the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md). +- on the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object generated by the [ServiceModel Metadata Utility Tool (Svcutil.exe)](../../../docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md). - An initiating operation on either type of [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object (by default, all operations are initiating). When the first operation is called, the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object automatically opens the channel and initiates a session. Typically a client ends a session with a service endpoint by calling one of the following: -- on the channel returned by a call to . +- on the channel returned by a call to . -- on the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object generated by Svcutil.exe. +- on the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object generated by Svcutil.exe. - A terminating operation on either type of [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object (by default, no operations are terminating; the contract must explicitly specify a terminating operation). When the first operation is called, the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object automatically opens the channel and initiates a session. @@ -137,7 +137,7 @@ In [!INCLUDE[indigo1](../../../includes/indigo1-md.md)] applications, a *session [!INCLUDE[crabout](../../../includes/crabout-md.md)] clients and sessions, see [Accessing Services Using a WCF Client](../../../docs/framework/wcf/feature-details/accessing-services-using-a-client.md). ## Sessions Interact with InstanceContext Settings - There is an interaction between the enumeration in a contract and the property, which controls the association between channels and specific service objects. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Sessions, Instancing, and Concurrency](../../../docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). + There is an interaction between the enumeration in a contract and the property, which controls the association between channels and specific service objects. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Sessions, Instancing, and Concurrency](../../../docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). ### Sharing InstanceContext Objects You can also control which session-based channel or call is associated with which object by performing that association yourself. For a complete example, see [InstanceContextSharing](http://msdn.microsoft.com/en-us/4a6a46d7-b7d7-4bb5-a0dd-03ffa3cbc230). diff --git a/docs/framework/wcf/wcf-client-overview.md b/docs/framework/wcf/wcf-client-overview.md index eba3209bfd8f0..c7b2c855a52ac 100644 --- a/docs/framework/wcf/wcf-client-overview.md +++ b/docs/framework/wcf/wcf-client-overview.md @@ -82,7 +82,7 @@ svcutil /language:vb /out:ClientCode.vb /config:app.config http://computerName/M [!code-xml[C_GeneratedCodeFiles#19](../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/common/client.exe.config#19)] - This configuration file specifies a target endpoint in the `` element. [!INCLUDE[crabout](../../../includes/crabout-md.md)] using multiple target endpoints, see the or the constructors. + This configuration file specifies a target endpoint in the `` element. [!INCLUDE[crabout](../../../includes/crabout-md.md)] using multiple target endpoints, see the or the constructors. ## Calling Operations Once you have a client object created and configured, create a try/catch block, call operations in the same way that you would if the object were local, and close the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client object. When the client application calls the first operation, [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] automatically opens the underlying channel, and the underlying channel is closed when the object is recycled. (Alternatively, you can also explicitly open and close the channel prior to or subsequent to calling other operations.) @@ -135,7 +135,7 @@ End Interface [!code-csharp[C_GeneratedCodeFiles#20](../../../samples/snippets/csharp/VS_Snippets_CFX/c_generatedcodefiles/cs/proxycode.cs#20)] ## Handling Errors - Exceptions can occur in a client application when opening the underlying client channel (whether explicitly or automatically by calling an operation), using the client or channel object to call operations, or when closing the underlying client channel. It is recommended at a minimum that applications expect to handle possible and exceptions in addition to any objects thrown as a result of SOAP faults returned by operations. SOAP faults specified in the operation contract are raised to client applications as a where the type parameter is the detail type of the SOAP fault. [!INCLUDE[crabout](../../../includes/crabout-md.md)] handling error conditions in a client application, see [Sending and Receiving Faults](../../../docs/framework/wcf/sending-and-receiving-faults.md). For a complete sample the shows how to handle errors in a client, see [Expected Exceptions](../../../docs/framework/wcf/samples/expected-exceptions.md). + Exceptions can occur in a client application when opening the underlying client channel (whether explicitly or automatically by calling an operation), using the client or channel object to call operations, or when closing the underlying client channel. It is recommended at a minimum that applications expect to handle possible and exceptions in addition to any objects thrown as a result of SOAP faults returned by operations. SOAP faults specified in the operation contract are raised to client applications as a where the type parameter is the detail type of the SOAP fault. [!INCLUDE[crabout](../../../includes/crabout-md.md)] handling error conditions in a client application, see [Sending and Receiving Faults](../../../docs/framework/wcf/sending-and-receiving-faults.md). For a complete sample the shows how to handle errors in a client, see [Expected Exceptions](../../../docs/framework/wcf/samples/expected-exceptions.md). ## Configuring and Securing Clients Configuring a client starts with the required loading of target endpoint information for the client or channel object, usually from a configuration file, although you can also load this information programmatically using the client constructors and properties. However, additional configuration steps are required to enable certain client behavior and for many security scenarios. @@ -151,15 +151,15 @@ End Interface - Implement a callback contract class. -- Create an instance of the callback contract implementation class and use it to create the object that you pass to the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client constructor. +- Create an instance of the callback contract implementation class and use it to create the object that you pass to the [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client constructor. - Invoke operations and handle operation callbacks. Duplex [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client objects function like their nonduplex counterparts, with the exception that they expose the functionality necessary to support callbacks, including the configuration of the callback service. - For example, you can control various aspects of callback object runtime behavior by using properties of the attribute on the callback class. Another example is the use of the class to enable the return of exception information to services that call the callback object. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Duplex Services](../../../docs/framework/wcf/feature-details/duplex-services.md). For a complete sample, see [Duplex](../../../docs/framework/wcf/samples/duplex.md). + For example, you can control various aspects of callback object runtime behavior by using properties of the attribute on the callback class. Another example is the use of the class to enable the return of exception information to services that call the callback object. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][Duplex Services](../../../docs/framework/wcf/feature-details/duplex-services.md). For a complete sample, see [Duplex](../../../docs/framework/wcf/samples/duplex.md). - On Windows XP computers running Internet Information Services (IIS) 5.1, duplex clients must specify a client base address using the class or an exception is thrown. The following code example shows how to do this in code. + On Windows XP computers running Internet Information Services (IIS) 5.1, duplex clients must specify a client base address using the class or an exception is thrown. The following code example shows how to do this in code. [!code-csharp[S_DualHttp#8](../../../samples/snippets/csharp/VS_Snippets_CFX/s_dualhttp/cs/program.cs#8)] [!code-vb[S_DualHttp#8](../../../samples/snippets/visualbasic/VS_Snippets_CFX/s_dualhttp/vb/module1.vb#8)] @@ -172,8 +172,8 @@ End Interface How operations are called is entirely up to the client developer. This is because the messages that make up an operation can be mapped to either synchronous or asynchronous methods when expressed in managed code. Therefore, if you want to build a client that calls operations asynchronously, you can use Svcutil.exe to generate asynchronous client code using the `/async` option. [!INCLUDE[crdefault](../../../includes/crdefault-md.md)][How to: Call Service Operations Asynchronously](../../../docs/framework/wcf/feature-details/how-to-call-wcf-service-operations-asynchronously.md). ## Calling Services Using WCF Client Channels - [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client types extend , which itself derives from interface to expose the underlying channel system. You can invoke services by using the target service contract with the class. For details, see [WCF Client Architecture](../../../docs/framework/wcf/feature-details/client-architecture.md). + [!INCLUDE[indigo2](../../../includes/indigo2-md.md)] client types extend , which itself derives from interface to expose the underlying channel system. You can invoke services by using the target service contract with the class. For details, see [WCF Client Architecture](../../../docs/framework/wcf/feature-details/client-architecture.md). ## See Also - - + + diff --git a/docs/framework/wcf/wcf-troubleshooting-quickstart.md b/docs/framework/wcf/wcf-troubleshooting-quickstart.md index 528082e4b4774..c70197dbc7ea7 100644 --- a/docs/framework/wcf/wcf-troubleshooting-quickstart.md +++ b/docs/framework/wcf/wcf-troubleshooting-quickstart.md @@ -172,7 +172,7 @@ public class MyServiceHost : ServiceHost ## I changed the first parameter of an operation from uppercase to lowercase; now my client throws an exception. What's happening? - The value of the parameter names in the operation signature are part of the contract and are case-sensitive. Use the attribute when you need to distinguish between the local parameter name and the metadata that describes the operation for client applications. + The value of the parameter names in the operation signature are part of the contract and are case-sensitive. Use the attribute when you need to distinguish between the local parameter name and the metadata that describes the operation for client applications. ## I’m using one of my tracing tools and I get an EndpointNotFoundException. What’s happening? diff --git a/docs/framework/whats-new/index.md b/docs/framework/whats-new/index.md index 6e495725cbe15..dcfdabcfe4183 100644 --- a/docs/framework/whats-new/index.md +++ b/docs/framework/whats-new/index.md @@ -88,7 +88,7 @@ The .NET Framework 4.7 adds the following network-related feature: **Default operating system support for TLS protocols*** -The TLS stack, which is used by and up-stack components such as HTTP, FTP, and SMTP, allows developers to use the default TLS protocols supported by the operating system. Developers need no longer hard-code a TLS version. +The TLS stack, which is used by and up-stack components such as HTTP, FTP, and SMTP, allows developers to use the default TLS protocols supported by the operating system. Developers need no longer hard-code a TLS version. #### ASP.NET @@ -101,9 +101,9 @@ Starting with the .NET Framework 4.7, ASP.NET adds a new set of APIs that allow - **Object Cache Store**. By using the new cache providers configuration section, developers can plug in new implementations of an object cache for an ASP.NET application by using the new **ICacheStoreProvider** interface. -- **Memory monitoring**. The default memory monitor in ASP.NET notifies applications when they are running close to the configured private bytes limit for the process, or when the machine is low on total available physical RAM. When these limits are near, notifications are fired. For some applications, notifications are fired too close to the configured limits to allow for useful reactions. Developers can now write their own memory monitors to replace the default by using the property. +- **Memory monitoring**. The default memory monitor in ASP.NET notifies applications when they are running close to the configured private bytes limit for the process, or when the machine is low on total available physical RAM. When these limits are near, notifications are fired. For some applications, notifications are fired too close to the configured limits to allow for useful reactions. Developers can now write their own memory monitors to replace the default by using the property. -- **Memory Limit Reactions**. By default, ASP.NET attempts to trim the object cache and periodically call when the private byte process limit is near. For some applications, the frequency of calls to or the amount of cache that is trimmed are inefficient. Developers can now replace or supplement the default behavior by subscribing **IObserver** implementations to the application's memory monitor. +- **Memory Limit Reactions**. By default, ASP.NET attempts to trim the object cache and periodically call when the private byte process limit is near. For some applications, the frequency of calls to or the amount of cache that is trimmed are inefficient. Developers can now replace or supplement the default behavior by subscribing **IObserver** implementations to the application's memory monitor. #### Windows Communication Foundation (WCF) @@ -126,7 +126,7 @@ WCF includes a number of code changes that eliminate race conditions, thereby im - Better support for mixing asynchronous and synchronous code in calls to **SocketConnection.BeginRead** and **SocketConnection.Read**. - Improved reliability when aborting a connection with **SharedConnectionListener** and **DuplexChannelBinder**. -- Improved reliability of serialization operations when calling the method. +- Improved reliability of serialization operations when calling the method. - Improved reliability when removing a waiter by calling the **ChannelSynchronizer.RemoveWaiter** method. @@ -151,7 +151,7 @@ You now have the option of using a touch/stylus stack based on [WM_POINTER messa **New implementation for WPF printing APIs** -WPF's printing APIs in the class call the Windows [Print Document Package API](https://msdn.microsoft.com/library/windows/desktop/hh448418(v=vs.85).aspx) instead of the deprecated [XPS Print API](https://msdn.microsoft.com/library/windows/desktop/ff686814(v=vs.85).aspx). For the impact of this change on application compatibility, see [Retargeting Changes in the .NET Framework 4.7](../migration-guide/retargeting-changes-in-the-net-framework-4-7.md). +WPF's printing APIs in the class call the Windows [Print Document Package API](https://msdn.microsoft.com/library/windows/desktop/hh448418(v=vs.85).aspx) instead of the deprecated [XPS Print API](https://msdn.microsoft.com/library/windows/desktop/ff686814(v=vs.85).aspx). For the impact of this change on application compatibility, see [Retargeting Changes in the .NET Framework 4.7](../migration-guide/retargeting-changes-in-the-net-framework-4-7.md). ## What's new in the .NET Framework 4.6.2 @@ -185,15 +185,15 @@ For a list of new APIs added to the .NET Framework 4.6.2, see [.NET Framework 4. In the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], ASP.NET includes the following enhancements: **Improved support for localized error messages in data annotation validators** - Data annotation validators enable you to perform validation by adding one or more attributes to a class property. The attribute's element defines the text of the error message if validation fails. Starting with the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], ASP.NET makes it easy to localize error messages. Error messages will be localized if: + Data annotation validators enable you to perform validation by adding one or more attributes to a class property. The attribute's element defines the text of the error message if validation fails. Starting with the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], ASP.NET makes it easy to localize error messages. Error messages will be localized if: -1. The is provided in the validation attribute. +1. The is provided in the validation attribute. 2. The resource file is stored in the App_LocalResources folder. 3. The name of the localized resources file has the form `DataAnnotation.Localization.{`*name*`}.resx`, where *name* is a culture name in the format *languageCode*`-`*country/regionCode* or *languageCode*. -4. The key name of the resource is the string assigned to the attribute, and its value is the localized error message. +4. The key name of the resource is the string assigned to the attribute, and its value is the localized error message. For example, the following data annotation attribute defines the default culture's error message for an invalid rating. @@ -225,7 +225,7 @@ End Class In addition, data annotation localization is extensible. Developers can plug in their own string localizer provider by implementing the interface to store localization string somewhere other than in a resource file. **Async support with session-state store providers** - ASP.NET now allows task-returning methods to be used with session-state store providers, thereby allowing ASP.NET apps to get the scalability benefits of async. To supports asynchronous operations with session state store providers, ASP.NET includes a new interface, , which inherits from and allows developers to implement their own session-state module and async session store providers. The interface is defined as follows: + ASP.NET now allows task-returning methods to be used with session-state store providers, thereby allowing ASP.NET apps to get the scalability benefits of async. To supports asynchronous operations with session state store providers, ASP.NET includes a new interface, , which inherits from and allows developers to implement their own session-state module and async session store providers. The interface is defined as follows: ```csharp public interface ISessionStateModule : IHttpModule { @@ -241,19 +241,19 @@ public interface ISessionStateModule : IHttpModule { The following APIs have been added to support asynchronous output-cache providers: -- The class, which inherits from and allows developers to implement an asynchronous output-cache provider. +- The class, which inherits from and allows developers to implement an asynchronous output-cache provider. - The class, which provides helper methods for configuring the output cache. -- 18 new methods in the class. These include , , , , , , , , , , , , , , and . +- 18 new methods in the class. These include , , , , , , , , , , , , , , and . -- 2 new methods in the class: and . +- 2 new methods in the class: and . -- 2 new methods in the class: and . +- 2 new methods in the class: and . -- 2 new methods in the class: and . +- 2 new methods in the class: and . -- In the class, the method. +- In the class, the method. - In the , the method. @@ -261,7 +261,7 @@ public interface ISessionStateModule : IHttpModule { ### Character categories Characters in the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] are classified based on the [Unicode Standard, Version 8.0.0](http://www.unicode.org/versions/Unicode8.0.0/). In [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] and [!INCLUDE[net_v461](../../../includes/net-v461-md.md)], characters were classified based on Unicode 6.3 character categories. - Support for Unicode 8.0 is limited to the classification of characters by the class and to types and methods that rely on it. These include the class, the overloaded method, and the [character classes](../../../docs/standard/base-types/character-classes-in-regular-expressions.md) recognized by the .NET Framework regular expression engine. Character and string comparison and sorting is unaffected by this change and continues to rely on the underlying operating system or, on Windows 7 systems, on character data provided by the .NET Framework. + Support for Unicode 8.0 is limited to the classification of characters by the class and to types and methods that rely on it. These include the class, the overloaded method, and the [character classes](../../../docs/standard/base-types/character-classes-in-regular-expressions.md) recognized by the .NET Framework regular expression engine. Character and string comparison and sorting is unaffected by this change and continues to rely on the underlying operating system or, on Windows 7 systems, on character data provided by the .NET Framework. For changes in character categories from Unicode 6.0 to Unicode 7.0, see [The Unicode Standard, Version 7.0.0](http://www.unicode.org/versions/Unicode7.0.0/) at The Unicode Consortium website. For changes from Unicode 7.0 to Unicode 8.0, see [The Unicode Standard, Version 8.0.0](http://www.unicode.org/versions/Unicode8.0.0/) at The Unicode Consortium website. @@ -270,9 +270,9 @@ public interface ISessionStateModule : IHttpModule { **Support for X509 certificates containing FIPS 186-3 DSA** The [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] adds support for DSA (Digital Signature Algorithm) X509 certificates whose keys exceed the FIPS 186-2 1024-bit limit. - In addition to supporting the larger key sizes of FIPS 186-3, the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] allows computing signatures with the SHA-2 family of hash algorithms (SHA256, SHA384, and SHA512). FIPS 186-3 support is provided by the new class. + In addition to supporting the larger key sizes of FIPS 186-3, the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] allows computing signatures with the SHA-2 family of hash algorithms (SHA256, SHA384, and SHA512). FIPS 186-3 support is provided by the new class. - In keeping with recent changes to the class in the .NET Framework 4.6 and the class in the .NET Framework 4.6.1, the abstract base class in [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] has additional methods to allow callers to use this functionality without casting. You can call the extension method to sign data, as the following example shows. + In keeping with recent changes to the class in the .NET Framework 4.6 and the class in the .NET Framework 4.6.1, the abstract base class in [!INCLUDE[net_v462](../../../includes/net-v462-md.md)] has additional methods to allow callers to use this functionality without casting. You can call the extension method to sign data, as the following example shows. ```csharp public static byte[] SignDataDsaSha384(byte[] data, X509Certificate2 cert) @@ -292,7 +292,7 @@ Public Shared Function SignDataDsaSha384(data As Byte(), cert As X509Certificate End Function ``` - And you can call the extension method to verify signed data, as the following example shows. + And you can call the extension method to verify signed data, as the following example shows. ```csharp public static bool VerifyDataDsaSha384(byte[] data, byte[] signature, X509Certificate2 cert) @@ -383,7 +383,7 @@ End Function ### SqlClient - .NET Framework Data Provider for SQL Server () includes the following new features in the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)]: + .NET Framework Data Provider for SQL Server () includes the following new features in the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)]: **Connection pooling and timeouts with Azure SQL databases** When connection pooling is enabled and a timeout or other login error occurs, an exception is cached, and the cached exception is thrown on any subsequent connection attempt for the next 5 seconds to 1 minute. For more details, see [SQL Server Connection Pooling (ADO.NET)](../../../docs/framework/data/adonet/sql-server-connection-pooling.md). @@ -412,9 +412,9 @@ End Function **Enhancements for Always Encrypted** SQLClient introduces two enhancements for Always Encrypted: -- To improve performance of parameterized queries against encrypted database columns, encryption metadata for query parameters is now cached. With the property set to `true` (which is the default value), if the same query is called multiple times, the client retrieves parameter metadata from the server only once. +- To improve performance of parameterized queries against encrypted database columns, encryption metadata for query parameters is now cached. With the property set to `true` (which is the default value), if the same query is called multiple times, the client retrieves parameter metadata from the server only once. -- Column encryption key entries in the key cache are now evicted after a configurable time interval, set using the property. +- Column encryption key entries in the key cache are now evicted after a configurable time interval, set using the property. ### Windows Communication Foundation @@ -503,9 +503,9 @@ For more information on the structure and time zone a **SSL 3.0 is not a default protocol** When using NetTcp with transport security and a credential type of certificate, SSL 3.0 is no longer a default protocol used for negotiating a secure connection. In most cases, there should be no impact to existing apps, because TLS 1.0 is included in the protocol list for NetTcp. All existing clients should be able to negotiate a connection using at least TLS 1.0. If Ssl3 is required, use one of the following configuration mechanisms to add it to the list of negotiated protocols. -- The property +- The property -- The property +- The property - The [\](../../../docs/framework/configure-apps/file-schema/wcf/transport-of-nettcpbinding.md) section of the [\](../../../docs/framework/configure-apps/file-schema/wcf/nettcpbinding.md) section @@ -518,7 +518,7 @@ For more information on the structure and time zone a **Group sorting** An application that uses a object to group data can now explicitly declare how to sort the groups. Explicit sorting addresses the problem of non-intuitive ordering that occurs when an app dynamically adds or removes groups, or when it changes the value of item properties involved in grouping. It can also improve the performance of the group creation process by moving comparisons of the grouping properties from the sort of the full collection to the sort of the groups. - To support group sorting, the new and properties describe how to sort the collection of groups produced by the object. This is analogous to the way the identically named properties describe how to sort the data items. + To support group sorting, the new and properties describe how to sort the collection of groups produced by the object. This is analogous to the way the identically named properties describe how to sort the data items. Two new static properties of the class, and , can be used for the most common cases. @@ -576,9 +576,9 @@ For more information on the structure and time zone a If this scenario is not enabled, running the application continues to generate an exception with the message, "This implementation is not part of the Windows Platform FIPS validated cryptographic algorithms." **Workflow Improvements when using Dynamic Update with Visual Studio Workflow Designer** - The Workflow Designer, FlowChart Activity Designer, and other Workflow Activity Designers now successfully load and display workflows that have been saved after calling the method. In versions of the .NET Framework before the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], loading a XAML file in Visual Studio for a workflow that has been saved after calling can result in the following issues: + The Workflow Designer, FlowChart Activity Designer, and other Workflow Activity Designers now successfully load and display workflows that have been saved after calling the method. In versions of the .NET Framework before the [!INCLUDE[net_v462](../../../includes/net-v462-md.md)], loading a XAML file in Visual Studio for a workflow that has been saved after calling can result in the following issues: -- The Workflow Designer can't load the XAML file correctly (when the is at the end of the line). +- The Workflow Designer can't load the XAML file correctly (when the is at the end of the line). - Flowchart Activity Designer or other Workflow Activity Designers may display all objects in their default locations as opposed to attached property values. @@ -696,19 +696,19 @@ For more information on the structure and time zone a ### Windows Workflow Foundation: Transactions - The method can now use a distributed transaction manager other than MSDTC to promote the transaction. You do this by specifying a GUID transaction promoter identifier to the new overload . If this operation is successful, there are limitations placed on the capabilities of the transaction. Once a non-MSDTC transaction promoter is enlisted, the following methods throw a because these methods require promotion to MSDTC: + The method can now use a distributed transaction manager other than MSDTC to promote the transaction. You do this by specifying a GUID transaction promoter identifier to the new overload . If this operation is successful, there are limitations placed on the capabilities of the transaction. Once a non-MSDTC transaction promoter is enlisted, the following methods throw a because these methods require promotion to MSDTC: -- +- -- +- -- +- -- +- Once a non-MSDTC transaction promoter is enlisted, it must be used for future durable enlistments by using protocols that it defines. The of the transaction promoter can be obtained by using the property. When the transaction promotes, the transaction promoter provides a array that represents the promoted token. An application can obtain the promoted token for a non-MSDTC promoted transaction with the method. - Users of the new overload must follow a specific call sequence in order for the promotion operation to complete successfully. These rules are documented in the method's documentation. + Users of the new overload must follow a specific call sequence in order for the promotion operation to complete successfully. These rules are documented in the method's documentation. ### Profiling @@ -742,7 +742,7 @@ For more information on the structure and time zone a - **Task-based API for Asynchronous Response Flushing** - ASP.NET now provides a simple task-based API for asynchronous response flushing, , that allows responses to be flushed asynchronously by using your language's `async/await` support. + ASP.NET now provides a simple task-based API for asynchronous response flushing, , that allows responses to be flushed asynchronously by using your language's `async/await` support. - `Model binding supports task-returning methods` @@ -762,7 +762,7 @@ For more information on the structure and time zone a [HTTP/2](http://www.wikipedia.org/wiki/HTTP/2) is a new version of the HTTP protocol that provides much better connection utilization (fewer round-trips between client and server), resulting in lower latency web page loading for users. Web pages (as opposed to services) benefit the most from HTTP/2, since the protocol optimizes for multiple artifacts being requested as part of a single experience. HTTP/2 support has been added to ASP.NET in the .NET Framework 4.6. Because networking functionality exists at multiple layers, new features were required in Windows, in IIS, and in ASP.NET to enable HTTP/2. You must be running on Windows 10 to use HTTP/2 with ASP.NET. - HTTP/2 is also supported and on by default for Windows 10 Universal Windows Platform (UWP) apps that use the API. + HTTP/2 is also supported and on by default for Windows 10 Universal Windows Platform (UWP) apps that use the API. In order to provide a way to use the [PUSH_PROMISE](http://http2.github.io/http2-spec/#PUSH_PROMISE) feature in ASP.NET applications, a new method with two overloads, and , has been added to the class. @@ -813,13 +813,13 @@ For more information on the structure and time zone a - **CultureInfo.CurrentCulture and CultureInfo.CurrentUICulture** - The and properties are now read-write rather than read-only. If you assign a new object to these properties, the current thread culture defined by the `Thread.CurrentThread.CurrentCulture` property and the current UI thread culture defined by the `Thread.CurrentThread.CurrentUICulture` properties also change. + The and properties are now read-write rather than read-only. If you assign a new object to these properties, the current thread culture defined by the `Thread.CurrentThread.CurrentCulture` property and the current UI thread culture defined by the `Thread.CurrentThread.CurrentUICulture` properties also change. - **Enhancements to garbage collection (GC)** The class now includes and methods that allow you to disallow garbage collection during the execution of a critical path. - A new overload of the method allows you to control whether both the small object heap and the large object heap are swept and compacted or swept only. + A new overload of the method allows you to control whether both the small object heap and the large object heap are swept and compacted or swept only. - **SIMD-enabled types** @@ -829,13 +829,13 @@ For more information on the structure and time zone a - **Cryptography updates** - The API is being updated to support the [Windows CNG cryptography APIs](https://msdn.microsoft.com/library/windows/desktop/aa376214.aspx). Previous versions of the .NET Framework have relied entirely on an [earlier version of the Windows Cryptography APIs](https://msdn.microsoft.com/library/windows/desktop/aa380255.aspx) as the basis for the implementation. We have had requests to support the CNG API, since it supports [modern cryptography algorithms](https://msdn.microsoft.com/library/windows/desktop/bb204775.aspx#suite_b_support), which are important for certain categories of apps. + The API is being updated to support the [Windows CNG cryptography APIs](https://msdn.microsoft.com/library/windows/desktop/aa376214.aspx). Previous versions of the .NET Framework have relied entirely on an [earlier version of the Windows Cryptography APIs](https://msdn.microsoft.com/library/windows/desktop/aa380255.aspx) as the basis for the implementation. We have had requests to support the CNG API, since it supports [modern cryptography algorithms](https://msdn.microsoft.com/library/windows/desktop/bb204775.aspx#suite_b_support), which are important for certain categories of apps. The .NET Framework 4.6 includes the following new enhancements to support the Windows CNG cryptography APIs: - A set of extension methods for X509 Certificates, `System.Security.Cryptography.X509Certificates.RSACertificateExtensions.GetRSAPublicKey(System.Security.Cryptography.X509Certificates.X509Certificate2)` and `System.Security.Cryptography.X509Certificates.RSACertificateExtensions.GetRSAPrivateKey(System.Security.Cryptography.X509Certificates.X509Certificate2)`, that return a CNG-based implementation rather than a CAPI-based implementation when possible. (Some smartcards, etc., still require CAPI, and the APIs handle the fallback). - - The class, which provides a CNG implementation of the RSA algorithm. + - The class, which provides a CNG implementation of the RSA algorithm. - Enhancements to the RSA API so that common actions no longer require casting. For example, encrypting data using an object requires code like the following in previous versions of the .NET Framework. @@ -851,13 +851,13 @@ For more information on the structure and time zone a The following new methods have been added to the structure to support converting date and time values to or from Unix time: - - + - - - + - - - + - - - + - - **Compatibility switches** @@ -903,9 +903,9 @@ For more information on the structure and time zone a For apps that target the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)], and objects inherit the culture and UI culture of the calling thread. The behavior of apps that target previous versions of the .NET Framework, or that do not target a specific version of the .NET Framework, is unaffected. For more information, see the "Culture and task-based asynchronous operations" section of the class topic. - The class allows you to represent ambient data that is local to a given asynchronous control flow, such as an `async` method. It can be used to persist data across threads. You can also define a callback method that is notified whenever the ambient data changes either because the property was explicitly changed, or because the thread encountered a context transition. + The class allows you to represent ambient data that is local to a given asynchronous control flow, such as an `async` method. It can be used to persist data across threads. You can also define a callback method that is notified whenever the ambient data changes either because the property was explicitly changed, or because the thread encountered a context transition. - Three convenience methods, , , and , have been added to the task-based asynchronous pattern (TAP) to return completed tasks in a particular state. + Three convenience methods, , , and , have been added to the task-based asynchronous pattern (TAP) to return completed tasks in a particular state. The class now supports asynchronous communication with its new . method. @@ -947,7 +947,7 @@ For more information on the structure and time zone a ``` - Support for automatically loading the right cursor based on DPI setting has been added to . + Support for automatically loading the right cursor based on DPI setting has been added to . - **Touch is better** @@ -955,7 +955,7 @@ For more information on the structure and time zone a - **Transparent child window support** - WPF in the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] supports transparent child windows in Windows 8.1 and above. This allows you to create non-rectangular and transparent child windows in your top-level windows. You can enable this feature by setting the property to `true`. + WPF in the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] supports transparent child windows in Windows 8.1 and above. This allows you to create non-rectangular and transparent child windows in your top-level windows. You can enable this feature by setting the property to `true`. - **Windows Communication Foundation (WCF)** @@ -982,7 +982,7 @@ For more information on the structure and time zone a - **Using a connection group name prefix** - Users can specify a string that WCF will use as a prefix achieve for the connection group name. Two messages with different prefixes are sent using different underlying HTTP connections. You set the prefix by adding a key/value pair to the message's property. The key is "HttpTransportConnectionGroupNamePrefix"; the value is the desired prefix. + Users can specify a string that WCF will use as a prefix achieve for the connection group name. Two messages with different prefixes are sent using different underlying HTTP connections. You set the prefix by adding a key/value pair to the message's property. The key is "HttpTransportConnectionGroupNamePrefix"; the value is the desired prefix. - **Using different channel factories** @@ -1030,13 +1030,13 @@ For more information on the structure and time zone a In the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)], two new APIs have been added to enable port reuse, which effectively removes the 64K limit on concurrent connections: - - The enumeration value. + - The enumeration value. - - The property. + - The property. - By default, the property is `false` unless the `HWRPortReuseOnSocketBind` value of the `HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319` registry key is set to 0x1. To enable local port reuse on HTTP connections, set the property to `true`. This causes all outgoing TCP socket connections from and to use a new Windows 10 socket option, [SO_REUSE_UNICASTPORT](https://msdn.microsoft.com/library/windows/desktop/ms740532.aspx), that enables local port reuse. + By default, the property is `false` unless the `HWRPortReuseOnSocketBind` value of the `HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319` registry key is set to 0x1. To enable local port reuse on HTTP connections, set the property to `true`. This causes all outgoing TCP socket connections from and to use a new Windows 10 socket option, [SO_REUSE_UNICASTPORT](https://msdn.microsoft.com/library/windows/desktop/ms740532.aspx), that enables local port reuse. - Developers writing a sockets-only application can specify the option when calling a method such as so that outbound sockets reuse local ports during binding. + Developers writing a sockets-only application can specify the option when calling a method such as so that outbound sockets reuse local ports during binding. - **Support for international domain names and PunyCode** @@ -1056,7 +1056,7 @@ For more information on the structure and time zone a - **Support for code page encodings** - [!INCLUDE[net_core](../../../includes/net-core-md.md)] primarily supports the Unicode encodings and by default provides limited support for code page encodings. You can add support for code page encodings available in the .NET Framework but unsupported in [!INCLUDE[net_core](../../../includes/net-core-md.md)] by registering code page encodings with the method. For more information, see . + [!INCLUDE[net_core](../../../includes/net-core-md.md)] primarily supports the Unicode encodings and by default provides limited support for code page encodings. You can add support for code page encodings available in the .NET Framework but unsupported in [!INCLUDE[net_core](../../../includes/net-core-md.md)] by registering code page encodings with the method. For more information, see . - **.NET Native** @@ -1075,11 +1075,11 @@ For more information on the structure and time zone a ## What's new in the .NET Framework 4.5.2 -- **New APIs for ASP.NET apps.** The new and methods let you inspect and modify response headers and status code as the response is being flushed to the client app. Consider using these methods instead of the and events; they are more efficient and reliable. +- **New APIs for ASP.NET apps.** The new and methods let you inspect and modify response headers and status code as the response is being flushed to the client app. Consider using these methods instead of the and events; they are more efficient and reliable. - The method lets you schedule small background work items. ASP.NET tracks these items and prevents IIS from abruptly terminating the worker process until all background work items have completed. This method can't be called outside an ASP.NET managed app domain. + The method lets you schedule small background work items. ASP.NET tracks these items and prevents IIS from abruptly terminating the worker process until all background work items have completed. This method can't be called outside an ASP.NET managed app domain. - The new and properties return Boolean values that indicate whether the response headers have been written. You can use these properties to make sure that calls to APIs such as (which throw exceptions if the headers have been written) will succeed. + The new and properties return Boolean values that indicate whether the response headers have been written. You can use these properties to make sure that calls to APIs such as (which throw exceptions if the headers have been written) will succeed. - **Resizing in Windows Forms controls.** This feature has been expanded. You can now use the system DPI setting to resize components of the following additional controls (for example, the drop-down arrow in combo boxes): @@ -1098,13 +1098,13 @@ For more information on the structure and time zone a ``` -- **New workflow feature.** A resource manager that's using the method (and therefore implementing the interface) can use the new method to request the following: +- **New workflow feature.** A resource manager that's using the method (and therefore implementing the interface) can use the new method to request the following: - Promote the transaction to a Microsoft Distributed Transaction Coordinator (MSDTC) transaction. - Replace with an , which is a durable enlistment that supports single phase commits. - This can be done within the same app domain, and doesn't require any extra unmanaged code to interact with MSDTC to perform the promotion. The new method can be called only when there's an outstanding call from to the `Promote` method that's implemented by the promotable enlistment. + This can be done within the same app domain, and doesn't require any extra unmanaged code to interact with MSDTC to perform the promotion. The new method can be called only when there's an outstanding call from to the `Promote` method that's implemented by the promotable enlistment. - **Profiling improvements.** The following new unmanaged profiling APIs provide more robust profiling: @@ -1130,7 +1130,7 @@ For more information on the structure and time zone a - **Promoting a transaction and converting it to a durable enlistment** - is a new API added to the .NET Framework 4.5.2 and 4.6: + is a new API added to the .NET Framework 4.5.2 and 4.6: ```csharp [System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.LinkDemand, Name = "FullTrust")] @@ -1140,7 +1140,7 @@ For more information on the structure and time zone a EnlistmentOptions enlistmentOptions) ``` - The method may be used by an enlistment that was previously created by in response to the method. It asks `System.Transactions` to promote the transaction to an MSDTC transaction and to "convert" the promotable enlistment to a durable enlistment. After this method completes successfully, the interface will no longer be referenced by `System.Transactions`, and any future notifications will arrive on the provided interface. The enlistment in question must act as a durable enlistment, supporting transaction logging and recovery. Refer to for details. In addition, the enlistment must support . This method can *only* be called while processing an call. If that is not the case, a exception is thrown. + The method may be used by an enlistment that was previously created by in response to the method. It asks `System.Transactions` to promote the transaction to an MSDTC transaction and to "convert" the promotable enlistment to a durable enlistment. After this method completes successfully, the interface will no longer be referenced by `System.Transactions`, and any future notifications will arrive on the provided interface. The enlistment in question must act as a durable enlistment, supporting transaction logging and recovery. Refer to for details. In addition, the enlistment must support . This method can *only* be called while processing an call. If that is not the case, a exception is thrown. [Back to top](#introduction) @@ -1170,7 +1170,7 @@ For more information on the structure and time zone a - Ability to collect diagnostics information to help developers improve the performance of server and cloud applications. For more information, see the and methods in the class. -- Ability to explicitly compact the large object heap (LOH) during garbage collection. For more information, see the property. +- Ability to explicitly compact the large object heap (LOH) during garbage collection. For more information, see the property. - Additional performance improvements such as ASP.NET app suspension, multi-core JIT improvements, and faster app startup after a .NET Framework update. For details, see the [.NET Framework 4.5.1 announcement](https://blogs.msdn.microsoft.com/dotnet/2013/06/26/announcing-the-net-framework-4-5-1-preview/) and the [ASP.NET app suspend](https://blogs.msdn.microsoft.com/dotnet/2013/10/09/asp-net-app-suspend-responsive-shared-net-web-hosting/) blog post. @@ -1219,7 +1219,7 @@ For more information on the structure and time zone a - Background just-in-time (JIT) compilation, which is optionally available on multi-core processors to improve application performance. See . -- Ability to limit how long the regular expression engine will attempt to resolve a regular expression before it times out. See the property. +- Ability to limit how long the regular expression engine will attempt to resolve a regular expression before it times out. See the property. - Ability to define the default culture for an application domain. See the class. @@ -1229,11 +1229,11 @@ For more information on the structure and time zone a - Better performance when retrieving resources. See [Packaging and Deploying Resources](../../../docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md). -- Zip compression improvements to reduce the size of a compressed file. See the namespace. +- Zip compression improvements to reduce the size of a compressed file. See the namespace. - Ability to customize a reflection context to override default reflection behavior through the class. -- Support for the 2008 version of the Internationalized Domain Names in Applications (IDNA) standard when the class is used on [!INCLUDE[win8](../../../includes/win8-md.md)]. +- Support for the 2008 version of the Internationalized Domain Names in Applications (IDNA) standard when the class is used on [!INCLUDE[win8](../../../includes/win8-md.md)]. - Delegation of string comparison to the operating system, which implements Unicode 6.0, when the .NET Framework is used on [!INCLUDE[win8](../../../includes/win8-md.md)]. When running on other platforms, the .NET Framework includes its own string comparison data, which implements Unicode 5.x. See the class and the Remarks section of the class. @@ -1277,7 +1277,7 @@ For more information on the structure and time zone a ### Networking - The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] provides a new programming interface for HTTP applications. For more information, see the new and namespaces. + The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] provides a new programming interface for HTTP applications. For more information, see the new and namespaces. Support is also included for a new programming interface for accepting and interacting with a WebSocket connection by using the existing and related classes. For more information, see the new namespace and the class. diff --git a/docs/framework/whats-new/obsolete-members.md b/docs/framework/whats-new/obsolete-members.md index e2d841cb9eea5..688b99272d5aa 100644 --- a/docs/framework/whats-new/obsolete-members.md +++ b/docs/framework/whats-new/obsolete-members.md @@ -97,637 +97,637 @@ The tables in this article list the type members that are obsolete in the |Type|Member|Message| |----------|------------|-------------| -|||The registry key only works on Win9x, which is no longer supported by the CLR. On NT-based operating systems, use the registry key or the registry proxy instead.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use Evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -||| has been deprecated. Please investigate the use of instead.| -||| has been deprecated. Please investigate the use of instead.| -||| has been deprecated. Please investigate the use of instead.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -||| has been deprecated because it does not provide a stable Id when managed threads are running on fibers (aka lightweight threads). To get a stable identifier for a managed thread, use the property.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -||| policy levels are obsolete and will be removed in a future release of the .NET Framework.| -||| has been deprecated. Please investigate the use of instead.| -||| has been deprecated. Please investigate the use of instead.| -||| has been deprecated. Please investigate the use of instead.| -||| has been deprecated. Please investigate the use of instead.| -|||The `provider` argument is not used. Please use .| -|||The `provider` argument is not used. Please use .| -|||This method has been deprecated. Please use instead.| -|||This method has been deprecated. Please use instead.| -|||Please use instead.| -|||Please use instead.| -|||Please use instead.| -|||Please use instead.| -|||Please use the property.| -|||Please use `KeyComparer` properties.| -|||Please use instead.| -|||The class has been deprecated.| -|||The class has been deprecated.| -|||The class has been deprecated.| -|||The class has been deprecated.| -|||The class has been deprecated.| -|||The class has been deprecated.| -|||The class has been deprecated.| -|||Do not create instances of the class. Call the static methods directly on this type instead.| -|||First deprecated in the .NET Framework 4.5.

This constructor has been deprecated. Please use a constructor that does not require a parameter.| -|||The recommended alternative is , which takes the importer interface pointer as an instead of an , and thus works on both 32-bit and 64-bit architectures.| -|||This value has been deprecated. Please use other values in .| -|||This value has been deprecated. Please use other values in .| -|||This constructor has been deprecated. Please use instead.| -|||This constructor has been deprecated. Please use instead, and optionally make a new with `ownsHandle`= `false` if needed.| -|||This constructor has been deprecated. Please use instead, and optionally make a new with `ownsHandle`= `false` if needed.| -|||This constructor has been deprecated. Please use instead, and optionally make a new with `ownsHandle`= `false` if needed.| -|||This property has been deprecated. Please use the property instead.| -|||Please use or instead.| -||| will be removed eventually. Please use `new ManualResetEvent(false)` instead.| -|||First deprecated in the .NET Framework 4.5.

Do not call or override this method.| -||| has been deprecated because it is not CLS Compliant. To get the current size, use .| -||| has been deprecated because it is not CLS Compliant. To get the maximum size, use .| -||| has been deprecated because it is not CLS Compliant. To get the current size, use .| -||| has been deprecated because it is not CLS Compliant. To get the maximum size, use .| -|||This property has been deprecated. Please use the property instead.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||This method has been deprecated. Please use instead.| -|||This method has been deprecated. Please use instead.| -|||This constructor has been deprecated. Please use instead.| -|||This constructor has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated.| -|||An alternate API is available: Emit the custom attribute instead.| -|||This API has been deprecated.| -|||An alternate API is available: Emit the custom attribute instead.| -|||This API has been deprecated.| -|||This API has been deprecated.| -|||An alternate API is available: Emit the custom attribute instead.| -|||Call instead.| -|||The method has been deprecated and will be removed in a future release.| -|||The method has been deprecated. Use the hosting API to perform this operation.| -|||Use instead.| -|||Use instead.| -|||Use instead.| -|||Use instead.| -|||The method has been deprecated and will be removed in a future release.| -|||This API did not perform any operation and will be removed in future versions of the CLR.| -|||Use of this member generates a compiler error.

Do not create instances of the class. Call the static methods directly on this type instead.| -|||Use instead.| -|||Use of this member generates a compiler error.

Do not create instances of the class. Call the static methods directly on this type instead.| -|||Use instead.| -|||Use of this method is not recommended. The existed for internal diagnostic purposes only.| -||| is obsolete and will be removed in a future release of the .NET Framework.| -||| is obsolete and will be removed in a future release of the .NET Framework.| -|||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| -|||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and should no longer be used.| -||| is obsolete and will be removed in a future release of the .NET Framework.| -||| is only used for .NET 2.0 transparency compatibility.| -|||Because execution permission checks can no longer be turned off, the property no longer has any effect.| -||| is obsolete and will be removed in a future release of the .NET Framework. Please use either the property or the property instead.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||This method is obsolete and will be removed in a future release of the .NET Framework.| -|||Because security can no longer be turned off, the property no longer has any effect.| -||| replaces for deriving key material from a password and is preferred in new applications.| -|||This method has been deprecated. Please use the property instead.| -|||This method has been deprecated. Please use the property instead.| -|||Please use the property instead.| -|||This permission is no longer used by the CLR.| -|||This API has been deprecated.| -|||This permission has been deprecated. The enumeration member does not include . Use to get full access.| -|||This permission is no longer used by the CLR.| -|||This API has been deprecated.| -|||Please use the property instead.| -||| is obsolete and will be removed in a future release of the .NET Framework.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -|||This method is obsolete. Please use instead.| -|||This method is obsolete. Please use instead.| -|||Evidence should not be treated as an . Please use the and methods rather than using .| -|||Evidence should not be treated as an . Please use and to iterate over the evidence to collect a count.| -|||This constructor is obsolete. Please use the constructor instead.| -||| is obsolete. Please use and instead.| -|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| -|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| -|||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| -|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| -|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| -|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| -|||This property is not 64-bit compatible. Use instead.| -|||This constructor is not 64-bit compatible. Use the constructor that takes an for the event handle.| -|||This method is not safe. Use instead.| -|||This method is not safe. Use instead.| -|||The property has been deprecated. Use , or instead.| -||| is no longer supported. Please use the class.| -||| has been deprecated. Please use other classes in , such as , , , and to synchronize threads or protect resources.| -||| is no longer supported. Please use the class.| -||| has been deprecated. Please use other classes in , such as , , , and , to synchronize threads or protect resources.| -||| has been deprecated. Please use instead.| -|||Use the property instead.| +|||The registry key only works on Win9x, which is no longer supported by the CLR. On NT-based operating systems, use the registry key or the registry proxy instead.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use Evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +||| has been deprecated. Please investigate the use of instead.| +||| has been deprecated. Please investigate the use of instead.| +||| has been deprecated. Please investigate the use of instead.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +||| has been deprecated because it does not provide a stable Id when managed threads are running on fibers (aka lightweight threads). To get a stable identifier for a managed thread, use the property.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Methods that use evidence to sandbox are obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +||| policy levels are obsolete and will be removed in a future release of the .NET Framework.| +||| has been deprecated. Please investigate the use of instead.| +||| has been deprecated. Please investigate the use of instead.| +||| has been deprecated. Please investigate the use of instead.| +||| has been deprecated. Please investigate the use of instead.| +|||The `provider` argument is not used. Please use .| +|||The `provider` argument is not used. Please use .| +|||This method has been deprecated. Please use instead.| +|||This method has been deprecated. Please use instead.| +|||Please use instead.| +|||Please use instead.| +|||Please use instead.| +|||Please use instead.| +|||Please use the property.| +|||Please use `KeyComparer` properties.| +|||Please use instead.| +|||The class has been deprecated.| +|||The class has been deprecated.| +|||The class has been deprecated.| +|||The class has been deprecated.| +|||The class has been deprecated.| +|||The class has been deprecated.| +|||The class has been deprecated.| +|||Do not create instances of the class. Call the static methods directly on this type instead.| +|||First deprecated in the .NET Framework 4.5.

This constructor has been deprecated. Please use a constructor that does not require a parameter.| +|||The recommended alternative is , which takes the importer interface pointer as an instead of an , and thus works on both 32-bit and 64-bit architectures.| +|||This value has been deprecated. Please use other values in .| +|||This value has been deprecated. Please use other values in .| +|||This constructor has been deprecated. Please use instead.| +|||This constructor has been deprecated. Please use instead, and optionally make a new with `ownsHandle`= `false` if needed.| +|||This constructor has been deprecated. Please use instead, and optionally make a new with `ownsHandle`= `false` if needed.| +|||This constructor has been deprecated. Please use instead, and optionally make a new with `ownsHandle`= `false` if needed.| +|||This property has been deprecated. Please use the property instead.| +|||Please use or instead.| +||| will be removed eventually. Please use `new ManualResetEvent(false)` instead.| +|||First deprecated in the .NET Framework 4.5.

Do not call or override this method.| +||| has been deprecated because it is not CLS Compliant. To get the current size, use .| +||| has been deprecated because it is not CLS Compliant. To get the maximum size, use .| +||| has been deprecated because it is not CLS Compliant. To get the current size, use .| +||| has been deprecated because it is not CLS Compliant. To get the maximum size, use .| +|||This property has been deprecated. Please use the property instead.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||This method has been deprecated. Please use instead.| +|||This method has been deprecated. Please use instead.| +|||This constructor has been deprecated. Please use instead.| +|||This constructor has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated.| +|||An alternate API is available: Emit the custom attribute instead.| +|||This API has been deprecated.| +|||An alternate API is available: Emit the custom attribute instead.| +|||This API has been deprecated.| +|||This API has been deprecated.| +|||An alternate API is available: Emit the custom attribute instead.| +|||Call instead.| +|||The method has been deprecated and will be removed in a future release.| +|||The method has been deprecated. Use the hosting API to perform this operation.| +|||Use instead.| +|||Use instead.| +|||Use instead.| +|||Use instead.| +|||The method has been deprecated and will be removed in a future release.| +|||This API did not perform any operation and will be removed in future versions of the CLR.| +|||Use of this member generates a compiler error.

Do not create instances of the class. Call the static methods directly on this type instead.| +|||Use instead.| +|||Use of this member generates a compiler error.

Do not create instances of the class. Call the static methods directly on this type instead.| +|||Use instead.| +|||Use of this method is not recommended. The existed for internal diagnostic purposes only.| +||| is obsolete and will be removed in a future release of the .NET Framework.| +||| is obsolete and will be removed in a future release of the .NET Framework.| +|||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| +|||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and should no longer be used.| +||| is obsolete and will be removed in a future release of the .NET Framework.| +||| is only used for .NET 2.0 transparency compatibility.| +|||Because execution permission checks can no longer be turned off, the property no longer has any effect.| +||| is obsolete and will be removed in a future release of the .NET Framework. Please use either the property or the property instead.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||This method is obsolete and will be removed in a future release of the .NET Framework.| +|||Because security can no longer be turned off, the property no longer has any effect.| +||| replaces for deriving key material from a password and is preferred in new applications.| +|||This method has been deprecated. Please use the property instead.| +|||This method has been deprecated. Please use the property instead.| +|||Please use the property instead.| +|||This permission is no longer used by the CLR.| +|||This API has been deprecated.| +|||This permission has been deprecated. The enumeration member does not include . Use to get full access.| +|||This permission is no longer used by the CLR.| +|||This API has been deprecated.| +|||Please use the property instead.| +||| is obsolete and will be removed in a future release of the .NET Framework.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +|||This method is obsolete. Please use instead.| +|||This method is obsolete. Please use instead.| +|||Evidence should not be treated as an . Please use the and methods rather than using .| +|||Evidence should not be treated as an . Please use and to iterate over the evidence to collect a count.| +|||This constructor is obsolete. Please use the constructor instead.| +||| is obsolete. Please use and instead.| +|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| +|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| +|||AppDomain policy levels are obsolete and will be removed in a future release of the .NET Framework.| +|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| +|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| +|||Because all GAC assemblies always get full trust, the full trust list is no longer meaningful. You should install any assemblies that are used in security policy in the GAC to ensure they are trusted.| +|||This property is not 64-bit compatible. Use instead.| +|||This constructor is not 64-bit compatible. Use the constructor that takes an for the event handle.| +|||This method is not safe. Use instead.| +|||This method is not safe. Use instead.| +|||The property has been deprecated. Use , or instead.| +||| is no longer supported. Please use the class.| +||| has been deprecated. Please use other classes in , such as , , , and to synchronize threads or protect resources.| +||| is no longer supported. Please use the class.| +||| has been deprecated. Please use other classes in , such as , , , and , to synchronize threads or protect resources.| +||| has been deprecated. Please use instead.| +|||Use the property instead.| ### Assembly: PresentationCore.dll |Type|Member|Message| |----------|------------|-------------| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -||| is an obsolete property and may be removed in a future release. The value of this property is not defined.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||This property is deprecated. Use the static method instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| -|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +||| is an obsolete property and may be removed in a future release. The value of this property is not defined.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||This property is deprecated. Use the static method instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| +|||Bitmap effects are deprecated and no longer function. Consider using where appropriate instead.| ### Assembly: PresentationFramework.dll |Type|Member|Message| |----------|------------|-------------| -|||Replaced by .| -|||Replaced by .| -|||Replaced by .| -|||Replaced by .| +|||Replaced by .| +|||Replaced by .| +|||Replaced by .| +|||Replaced by .| ### Assembly: System.Activities.dll |Type|Member|Message| |----------|------------|-------------| -|||First deprecated in the .NET Framework 4.5.

Don't use this constructor. Use or instead.| -|||First deprecated in the .NET Framework 4.5.

Don't use this constructor. Use or instead.| +|||First deprecated in the .NET Framework 4.5.

Don't use this constructor. Use or instead.| +|||First deprecated in the .NET Framework 4.5.

Don't use this constructor. Use or instead.| ### Assembly: System.Activities.Presentation.dll |Type|Member|Message| |----------|------------|-------------| -|||This method does not support dragging multiple items.| -|||First deprecated in the .NET Framework 4.5.

This method does not support dragging multiple items. Use instead.| -|||This method does not support dragging multiple items.| -|||First deprecated in the .NET Framework 4.5.

This method does not support dragging multiple items. Use instead.| -|||First deprecated in the .NET Framework 4.5.

This method does not support dragging multiple items. Use instead.| -|||This method does not support dragging multiple items.| -|||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| -|||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| -|||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| +|||This method does not support dragging multiple items.| +|||First deprecated in the .NET Framework 4.5.

This method does not support dragging multiple items. Use instead.| +|||This method does not support dragging multiple items.| +|||First deprecated in the .NET Framework 4.5.

This method does not support dragging multiple items. Use instead.| +|||First deprecated in the .NET Framework 4.5.

This method does not support dragging multiple items. Use instead.| +|||This method does not support dragging multiple items.| +|||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| +|||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| +|||First deprecated in the .NET Framework 4.5.

Don't use this property. Use instead.| ### Assembly: System.Core.dll |Type|Member|Message| |----------|------------|-------------| -|||First deprecated in the .NET Framework 4.5.

Incorrect value; use instead.| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| -|||Use a different constructor that does not take an argument. Then override the and properties to provide the values that would be specified to this constructor.| -|||Do not use this constructor. It will be removed in future releases.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| +|||First deprecated in the .NET Framework 4.5.

Incorrect value; use instead.| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||The second data source of a binary operator must be of type rather than . To fix this problem, use the extension method to convert the right data source to .| +|||Use a different constructor that does not take an argument. Then override the and properties to provide the values that would be specified to this constructor.| +|||Do not use this constructor. It will be removed in future releases.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| ### Assembly: System.Data.dll |Type|Member|Message| |----------|------------|-------------| -||| has been deprecated.| -||| has been deprecated. Use the constructor.| -|||Use of this member generates a compiler error.

This constructor has been deprecated. Pass the constructor a value of .| -|||Use of this member generates a compiler error.

This constructor has been deprecated. Pass the constructor a value of .| -||| has been deprecated. Use .| -|||Use of this member generates a compiler error.

has been deprecated. Pass the constructor a value of .| -|||Use of this member generates a compiler error.

has been deprecated. Pass the constructor a value of .| -||| has been deprecated. Use the method.| -|||Use of this member generates a compiler error.

has been deprecated. Pass the a value of .| -|||Use of this member generates a compiler error.

has been deprecated. Pass the a value of .| -|||The property has been deprecated. Use the method.| -|||The property has been deprecated. Use the method.| -|||Use of this constructor generates a compiler error.

has been deprecated. Pass the constructor a value of .| -|||Use of this constructor generates a compiler error.

has been deprecated. Pass the constructor a value of .| -||| has been deprecated. will ignore the 'connection reset' keyword and always reset the connection.| -||| has been deprecated. Use .| +||| has been deprecated.| +||| has been deprecated. Use the constructor.| +|||Use of this member generates a compiler error.

This constructor has been deprecated. Pass the constructor a value of .| +|||Use of this member generates a compiler error.

This constructor has been deprecated. Pass the constructor a value of .| +||| has been deprecated. Use .| +|||Use of this member generates a compiler error.

has been deprecated. Pass the constructor a value of .| +|||Use of this member generates a compiler error.

has been deprecated. Pass the constructor a value of .| +||| has been deprecated. Use the method.| +|||Use of this member generates a compiler error.

has been deprecated. Pass the a value of .| +|||Use of this member generates a compiler error.

has been deprecated. Pass the a value of .| +|||The property has been deprecated. Use the method.| +|||The property has been deprecated. Use the method.| +|||Use of this constructor generates a compiler error.

has been deprecated. Pass the constructor a value of .| +|||Use of this constructor generates a compiler error.

has been deprecated. Pass the constructor a value of .| +||| has been deprecated. will ignore the 'connection reset' keyword and always reset the connection.| +||| has been deprecated. Use .| ### Assembly: System.Data.Entity.dll |Type|Member|Message| |----------|------------|-------------| -|||This property is going away, please use the property instead.| -|||First deprecated in the .NET Framework 4.5.

Use instead.| -|||Use instead.| -|||Use instead.| +|||This property is going away, please use the property instead.| +|||First deprecated in the .NET Framework 4.5.

Use instead.| +|||Use instead.| +|||Use instead.| ### Assembly: System.Data.OracleClient.dll |Type|Member|Message| |----------|------------|-------------| -||| has been deprecated. Use the classes to explicitly set the precision of a decimal.| -||| has been deprecated. Use the classes to explicitly set the scale of a decimal.| -||| has been deprecated. Use .| +||| has been deprecated. Use the classes to explicitly set the precision of a decimal.| +||| has been deprecated. Use the classes to explicitly set the scale of a decimal.| +||| has been deprecated. Use .| ### Assembly: System.Design.dll |Type|Member|Message| |----------|------------|-------------| -|||This method has been deprecated. Use instead.| -|||This method has been deprecated. Use instead.| -|||The method has been replaced by .| -|||This method has been deprecated. Use `xref:System.ComponentModel.Design.Serialization.CodeDomSerializer.SerializeToExpression` or instead.| -|||Use of this property generates a compiler error.

Error: This property can no longer be referenced, and is included to support existing compiled applications. The design\-time element view architecture is no longer used.| -|||The recommended alternative is to use `ControlDesigner.SetViewFlags(ViewFlags.DesignTimeHtmlRequiresLoadComplete, true)`.| -|||The recommended alternative is .| -|||The recommended alternative is to use `System.Web.UI.Design.ControlDesigner.Tag.SetDirty` and `System.Web.UI.Design.ControlDesigner.Tag.IsDirty`.| -|||The recommended alternative is `System.Web.UI.Design.ControlDesigner.DataBindings.Contains`. The class allows more control of the data bindings associated with the control.| -|||The recommended alternative is to handle the `ControlDesigner.DataBindings.Changed` event. The collection returned by the `ControlDesigner.DataBindings` property allows more control of the data bindings associated with the control.| -|||The recommended alternative is , which is called when any property of the control is changed.| -|||Use of this method is not recommended because resizing is handled by the method.| -|||The recommended alternative is to inherit from instead and to use an . Regions allow for better control of the content in the designer.| -|||The recommended alternative is .| -|||Use of this property generates a compiler error.

Error: This property can no longer be referenced, and is included to support existing compiled applications. The design\-time element may not always provide access to the element in the markup. There are alternate methods on for handling client script and controls.| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is to handle the `HtmlControlDesigner.DataBindings.Changed` event. The collection returned by the property allows more control of the data bindings associated with the control.| -|||Use of this property is not recommended because code serialization is not supported.| -|||Use of this property is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because the **AutoFormat** dialog is launched by the designer host. The list of available AutoFormats is exposed by the property.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| -|||The recommended alternative is .| -|||This method has been deprecated. Use instead.| +|||This method has been deprecated. Use instead.| +|||This method has been deprecated. Use instead.| +|||The method has been replaced by .| +|||This method has been deprecated. Use `xref:System.ComponentModel.Design.Serialization.CodeDomSerializer.SerializeToExpression` or instead.| +|||Use of this property generates a compiler error.

Error: This property can no longer be referenced, and is included to support existing compiled applications. The design\-time element view architecture is no longer used.| +|||The recommended alternative is to use `ControlDesigner.SetViewFlags(ViewFlags.DesignTimeHtmlRequiresLoadComplete, true)`.| +|||The recommended alternative is .| +|||The recommended alternative is to use `System.Web.UI.Design.ControlDesigner.Tag.SetDirty` and `System.Web.UI.Design.ControlDesigner.Tag.IsDirty`.| +|||The recommended alternative is `System.Web.UI.Design.ControlDesigner.DataBindings.Contains`. The class allows more control of the data bindings associated with the control.| +|||The recommended alternative is to handle the `ControlDesigner.DataBindings.Changed` event. The collection returned by the `ControlDesigner.DataBindings` property allows more control of the data bindings associated with the control.| +|||The recommended alternative is , which is called when any property of the control is changed.| +|||Use of this method is not recommended because resizing is handled by the method.| +|||The recommended alternative is to inherit from instead and to use an . Regions allow for better control of the content in the designer.| +|||The recommended alternative is .| +|||Use of this property generates a compiler error.

Error: This property can no longer be referenced, and is included to support existing compiled applications. The design\-time element may not always provide access to the element in the markup. There are alternate methods on for handling client script and controls.| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is to handle the `HtmlControlDesigner.DataBindings.Changed` event. The collection returned by the property allows more control of the data bindings associated with the control.| +|||Use of this property is not recommended because code serialization is not supported.| +|||Use of this property is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because the **AutoFormat** dialog is launched by the designer host. The list of available AutoFormats is exposed by the property.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||Use of this method is not recommended because template editing is handled in . To support template editing, expose template data in the property and call `ControlDesigner.SetViewFlags(ViewFlags.TemplateEditing, true)`.| +|||The recommended alternative is .| +|||This method has been deprecated. Use instead.| ### Assembly: System.dll |Type|Member|Message| |----------|------------|-------------| -|||Callers should not use the interface and should instead use the methods directly on the class.| -|||Callers should not use the interface and should instead use the methods directly on the class.| -|||Callers should not use the interface and should instead use the methods directly on the class.| -|||Callers should not use the interface and should instead use the methods directly on the class.| -|||This event has been deprecated.| -|||The method has been deprecated. It is not used by the system.| -|||The method has been deprecated. It is not used by the system.| -|||The method has been deprecated. It is not used by the system.| -|||The method has been deprecated. Please use the or the static method to escape a Uri component or a string.| -|||The method has been deprecated. It is not used by the system.| -|||The method has been deprecated. It is not used by the system.| -|||The method has been deprecated. It is not used by the system.| -|||The method has been deprecated. Please use .| -|||The method has been deprecated. It is not used by the system.| -|||The method has been deprecated. Please use the or the static method to escape a Uri component or a string.| -|||The constructor has been deprecated. Please use . The `dontEscape` parameter is deprecated and is always `false`.| -|||The constructor has been deprecated. Please . The `dontEscape` parameter is deprecated and is always `false`.| -|||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| -|||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| -|||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| -|||CAS policy is obsolete and will be removed in a future release of the .NET Framework. Please see [Security Changes in the .NET Framework 4](http://go2.microsoft.com/fwlink/?LinkId=131738) for more information.| -|||CAS policy is obsolete and will be removed in a future release of the .NET Framework. Please see [Security Changes in the .NET Framework 4](http://go2.microsoft.com/fwlink/?LinkId=131738) for more information.| -|||Please use instead.| -|||Please use instead.| -|||Please use instead.| -|||Please use instead.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||This method has been deprecated. Use instead.| -|||This property has been deprecated. Use a type description provider to supply type information for COM types instead.| -|||This constructor is obsolete. Use instead.| -|||This value has been deprecated. Use instead.| -|||This value has been deprecated. It is no longer supported.| -|||This value has been deprecated. It is no longer supported.| -|||This value has been deprecated. Use instead.| -|||This value has been deprecated. Use class methods to determine valid values, or use a type converter.| -|||This value has been deprecated. Use instead.| -|||This value has been deprecated. Use instead.| -|||This class is obsolete. To create a new exception, create a .| -|||This class is obsolete. To create a new exception, create a .| -|||This class is obsolete. To create a new exception, create a .| -|||This class is obsolete. To create a new exception, create a .| -|||This class is obsolete. To create a new exception, create a .| -|||This class is obsolete. To create a new exception, create a .| -|||This class is obsolete. To create a new exception, create a .| -|||This class is obsolete. Use instead.| -|||This class is obsolete. Use instead| -|||This method is obsolete. It has been replaced by .| -|||This method is obsolete. It has been replaced by .| -|||This method has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This member has been deprecated. Please use instead.| -|||This member has been deprecated. Please use instead.| -|||This member has been deprecated. Please use instead.| -|||This constructor has been deprecated. Please use to get an instance of this collection instead.| -|||This constructor has been deprecated. Please use to get an instance of this collection instead.| -|||This field has been deprecated and is not used. Use machine.config or an application configuration file to set the size of the file mapping.| -|||This method has been deprecated. Please use instead.| -|||This method has been deprecated. Please use instead.| -|||This class has been deprecated. Use the performance counters through the class instead.| -|||This class has been deprecated. Use the performance counters through the class instead.| -|||This class has been deprecated. Use the performance counters through the class instead.| -|||This member has been deprecated. Use instead.| -|||This member has been deprecated. Use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||This property has been deprecated. Please use instead.| -|||Serialization is obsoleted for this type.| -||| is obsoleted for this type, please use instead.| -||| is obsoleted for this type, please use instead.| -||| is obsoleted for this type, please use instead.| -||| is obsoleted for this type, please use instead.| -||| is obsoleted for this type, please use instead.| -||| is obsoleted for this type, please use instead.| -||| is obsoleted for this type, please use instead.| -||| is obsoleted for this type, please use instead.| -|||Serialization is obsoleted for this type.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||Serialization is obsoleted for this type.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||Serialization is obsoleted for this type.| -|||This property has been deprecated. It is address family dependent. Please use the method to perform comparisons instead.| -||| is obsoleted for this type. Please use instead.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||This method has been deprecated. Please use the proxy selected for you by default.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||| is obsoleted for this type. Please use instead, which can accept multiple addresses.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||| is obsoleted for this type. Please use instead.| -||| is obsoleted for this type. Please use instead.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||This method has been deprecated. Please use instead.| -|||First deprecated in the .NET Framework 4.5.

This member is for internal use only and will be removed in a future version of the .NET Framework. Do not call it.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

Use to add claims to a .| +|||Callers should not use the interface and should instead use the methods directly on the class.| +|||Callers should not use the interface and should instead use the methods directly on the class.| +|||Callers should not use the interface and should instead use the methods directly on the class.| +|||Callers should not use the interface and should instead use the methods directly on the class.| +|||This event has been deprecated.| +|||The method has been deprecated. It is not used by the system.| +|||The method has been deprecated. It is not used by the system.| +|||The method has been deprecated. It is not used by the system.| +|||The method has been deprecated. Please use the or the static method to escape a Uri component or a string.| +|||The method has been deprecated. It is not used by the system.| +|||The method has been deprecated. It is not used by the system.| +|||The method has been deprecated. It is not used by the system.| +|||The method has been deprecated. Please use .| +|||The method has been deprecated. It is not used by the system.| +|||The method has been deprecated. Please use the or the static method to escape a Uri component or a string.| +|||The constructor has been deprecated. Please use . The `dontEscape` parameter is deprecated and is always `false`.| +|||The constructor has been deprecated. Please . The `dontEscape` parameter is deprecated and is always `false`.| +|||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| +|||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| +|||Callers should not use the interface and should instead use the methods directly on the class. Those inheriting from must still implement this interface, and should exclude this warning or also obsolete this method.| +|||CAS policy is obsolete and will be removed in a future release of the .NET Framework. Please see [Security Changes in the .NET Framework 4](http://go2.microsoft.com/fwlink/?LinkId=131738) for more information.| +|||CAS policy is obsolete and will be removed in a future release of the .NET Framework. Please see [Security Changes in the .NET Framework 4](http://go2.microsoft.com/fwlink/?LinkId=131738) for more information.| +|||Please use instead.| +|||Please use instead.| +|||Please use instead.| +|||Please use instead.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||This method has been deprecated. Use instead.| +|||This property has been deprecated. Use a type description provider to supply type information for COM types instead.| +|||This constructor is obsolete. Use instead.| +|||This value has been deprecated. Use instead.| +|||This value has been deprecated. It is no longer supported.| +|||This value has been deprecated. It is no longer supported.| +|||This value has been deprecated. Use instead.| +|||This value has been deprecated. Use class methods to determine valid values, or use a type converter.| +|||This value has been deprecated. Use instead.| +|||This value has been deprecated. Use instead.| +|||This class is obsolete. To create a new exception, create a .| +|||This class is obsolete. To create a new exception, create a .| +|||This class is obsolete. To create a new exception, create a .| +|||This class is obsolete. To create a new exception, create a .| +|||This class is obsolete. To create a new exception, create a .| +|||This class is obsolete. To create a new exception, create a .| +|||This class is obsolete. To create a new exception, create a .| +|||This class is obsolete. Use instead.| +|||This class is obsolete. Use instead| +|||This method is obsolete. It has been replaced by .| +|||This method is obsolete. It has been replaced by .| +|||This method has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This member has been deprecated. Please use instead.| +|||This member has been deprecated. Please use instead.| +|||This member has been deprecated. Please use instead.| +|||This constructor has been deprecated. Please use to get an instance of this collection instead.| +|||This constructor has been deprecated. Please use to get an instance of this collection instead.| +|||This field has been deprecated and is not used. Use machine.config or an application configuration file to set the size of the file mapping.| +|||This method has been deprecated. Please use instead.| +|||This method has been deprecated. Please use instead.| +|||This class has been deprecated. Use the performance counters through the class instead.| +|||This class has been deprecated. Use the performance counters through the class instead.| +|||This class has been deprecated. Use the performance counters through the class instead.| +|||This member has been deprecated. Use instead.| +|||This member has been deprecated. Use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||This property has been deprecated. Please use instead.| +|||Serialization is obsoleted for this type.| +||| is obsoleted for this type, please use instead.| +||| is obsoleted for this type, please use instead.| +||| is obsoleted for this type, please use instead.| +||| is obsoleted for this type, please use instead.| +||| is obsoleted for this type, please use instead.| +||| is obsoleted for this type, please use instead.| +||| is obsoleted for this type, please use instead.| +||| is obsoleted for this type, please use instead.| +|||Serialization is obsoleted for this type.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||Serialization is obsoleted for this type.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||Serialization is obsoleted for this type.| +|||This property has been deprecated. It is address family dependent. Please use the method to perform comparisons instead.| +||| is obsoleted for this type. Please use instead.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||This method has been deprecated. Please use the proxy selected for you by default.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||| is obsoleted for this type. Please use instead, which can accept multiple addresses.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||| is obsoleted for this type. Please use instead.| +||| is obsoleted for this type. Please use instead.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||This method has been deprecated. Please use instead.| +|||First deprecated in the .NET Framework 4.5.

This member is for internal use only and will be removed in a future version of the .NET Framework. Do not call it.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

Use to add claims to a .| ### Assembly: System.Drawing.dll |Type|Member|Message| |----------|------------|-------------| -|||Do not use the method; use the property instead.| -|||First deprecated in the .NET Framework 4.5.

This constructor has been deprecated. Use .| +|||Do not use the method; use the property instead.| +|||First deprecated in the .NET Framework 4.5.

This constructor has been deprecated. Use .| ### Assembly: System.Messaging.dll |Type|Member|Message| |----------|------------|-------------| -|||This method returns a that implements the family of methods incorrectly. Please use instead.| -|||This method returns a that implements the family of methods incorrectly. Please use instead.| +|||This method returns a that implements the family of methods incorrectly. Please use instead.| +|||This method returns a that implements the family of methods incorrectly. Please use instead.| ### Assembly: System.ServiceModel.dll |Type|Member|Message| |----------|------------|-------------| -|||First deprecated in the .NET Framework 4.5.

This property is obsolete. To enable Http , use the `System.ServiceModel.BasicHttpBinding.AllowCookies` property instead.| -|||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| -|||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||This property is deprecated and is maintained for backward compatibility only. The local machine policy will be used to determine if NTLM should be used.| +|||First deprecated in the .NET Framework 4.5.

This property is obsolete. To enable Http , use the `System.ServiceModel.BasicHttpBinding.AllowCookies` property instead.| +|||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +|||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||This property is deprecated and is maintained for backward compatibility only. The local machine policy will be used to determine if NTLM should be used.| ### Assembly: System.ServiceModel.Discovery.dll |Type|Member|Message| |----------|------------|-------------| -|||First deprecated in the .NET Framework 4.5.

The property is obsolete. Consider using for setting the transport properties.| -|||First deprecated in the .NET Framework 4.5.

The property is obsolete. Consider using for setting the transport properties.| +|||First deprecated in the .NET Framework 4.5.

The property is obsolete. Consider using for setting the transport properties.| +|||First deprecated in the .NET Framework 4.5.

The property is obsolete. Consider using for setting the transport properties.| ### Assembly: System.Web.DataVisualization.dll |Type|Member|Message| |----------|------------|-------------| -||| has been deprecated. Please investigate instead.| +||| has been deprecated. Please investigate instead.| ### Assembly: System.Web.dll |Type|Member|Message| |----------|------------|-------------| -|||The recommended alternative is in System.Web.dll.| -|||The recommended alternative is in System.Web.dll.| -|||First deprecated in the .NET Framework 4.5.

This method produces non\-standards\-compliant output and has interoperability issues. The preferred alternative is .| -|||First deprecated in the .NET Framework 4.5.

This method produces non\-standards\-compliant output and has interoperability issues. The preferred alternative is .| -|||This field is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413).| -|||This property is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413).| -|||The recommended alternative is the property. A version value greater than or equal to 1 implies JavaScript support.| -|||System.Web.Mobile.dll is obsolete.| -|||This method is obsolete. Override the method to use the event.| -|||First deprecated in the .NET Framework 4.5.

The recommended alternative is to use the APIs, such as .| -|||First deprecated in the .NET Framework 4.5.

The recommended alternative is to use the APIs, such as .| -|||First deprecated in the .NET Framework 4.5.

This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the and methods instead.| -|||First deprecated in the .NET Framework 4.5.

This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the and methods instead.| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is .| -|||The recommended alternative is and .| -|||Use of this property is not recommended because it is no longer useful.| -|||First deprecated in the .NET Framework 4.5.

This method is kept for backward compatibility. This API is no longer used.| -|||The recommended alternative is the property. Create a and call to create an .| +|||The recommended alternative is in System.Web.dll.| +|||The recommended alternative is in System.Web.dll.| +|||First deprecated in the .NET Framework 4.5.

This method produces non\-standards\-compliant output and has interoperability issues. The preferred alternative is .| +|||First deprecated in the .NET Framework 4.5.

This method produces non\-standards\-compliant output and has interoperability issues. The preferred alternative is .| +|||This field is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413).| +|||This property is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413).| +|||The recommended alternative is the property. A version value greater than or equal to 1 implies JavaScript support.| +|||System.Web.Mobile.dll is obsolete.| +|||This method is obsolete. Override the method to use the event.| +|||First deprecated in the .NET Framework 4.5.

The recommended alternative is to use the APIs, such as .| +|||First deprecated in the .NET Framework 4.5.

The recommended alternative is to use the APIs, such as .| +|||First deprecated in the .NET Framework 4.5.

This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the and methods instead.| +|||First deprecated in the .NET Framework 4.5.

This method is obsolete and is only provided for compatibility with existing code. It is recommended that new code use the and methods instead.| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is .| +|||The recommended alternative is and .| +|||Use of this property is not recommended because it is no longer useful.| +|||First deprecated in the .NET Framework 4.5.

This method is kept for backward compatibility. This API is no longer used.| +|||The recommended alternative is the property. Create a and call to create an .| ### Assembly: System.Web.DynamicData.dll |Type|Member|Message| |----------|------------|-------------| -|||Use the `EnablePersistedSelection` property on a databound control such as or .| +|||Use the `EnablePersistedSelection` property on a databound control such as or .| ### Assembly: System.Web.Extensions.dll |Type|Member|Message| |----------|------------|-------------| -|||Use .| -|||This property is obsolete. Set the [`System.Web.UI.ScriptReference.Path`](xref:System.Web.UI.ScriptReferenceBase.Path%2A) property on each individual instead.| -|||This property is obsolete. Instead of using , set the [`System.Web.UI.ScriptReference.Path`](xref:System.Web.UI.ScriptReferenceBase.Path%2A) property on each individual .| -|||Use .| -|||Use .| -||| is no longer required in script references.| -|||This property is obsolete. Use instead.| -|||This property is obsolete. Use instead.| +|||Use .| +|||This property is obsolete. Set the [`System.Web.UI.ScriptReference.Path`](xref:System.Web.UI.ScriptReferenceBase.Path%2A) property on each individual instead.| +|||This property is obsolete. Instead of using , set the [`System.Web.UI.ScriptReference.Path`](xref:System.Web.UI.ScriptReferenceBase.Path%2A) property on each individual .| +|||Use .| +|||Use .| +||| is no longer required in script references.| +|||This property is obsolete. Use instead.| +|||This property is obsolete. Use instead.| ### Assembly: System.Web.Services.dll |Type|Member|Message| |----------|------------|-------------| -|||This method will be removed from a future version. The method call is no longer required for resource discovery.| -|||This property will be removed from a future version. The presence of a particular header in a SOAP message is no longer enforced.| +|||This method will be removed from a future version. The method call is no longer required for resource discovery.| +|||This property will be removed from a future version. The presence of a particular header in a SOAP message is no longer enforced.| ### Assembly: System.Windows.Forms.dll |Type|Member|Message| |----------|------------|-------------| -|||This enumeration value has been deprecated. There is no replacement.| -|||This method has been deprecated. There is no replacement.| -|||This property has been deprecated. Please use instead.| -|||This method has been deprecated. Use the method instead.| -|||This method has been deprecated. Use the method instead.| -|||This method has been deprecated. Use the method instead.| -|||This property has been deprecated. Use the property instead.| -|||This method has been deprecated. Use the property instead.| -|||This property has been deprecated. Use instead.| -|||This method has been deprecated. There is no replacement.| -|||This property has been deprecated. Use the property instead.| +|||This enumeration value has been deprecated. There is no replacement.| +|||This method has been deprecated. There is no replacement.| +|||This property has been deprecated. Please use instead.| +|||This method has been deprecated. Use the method instead.| +|||This method has been deprecated. Use the method instead.| +|||This method has been deprecated. Use the method instead.| +|||This property has been deprecated. Use the property instead.| +|||This method has been deprecated. Use the property instead.| +|||This property has been deprecated. Use instead.| +|||This method has been deprecated. There is no replacement.| +|||This property has been deprecated. Use the property instead.| ### Assembly: System.Xaml.dll |Type|Member|Message| |----------|------------|-------------| -|||This is not used by the XAML parser. Please look at .| -|||The `expressionType` argument is not used by the XAML parser. To specify the expected return type, use . To specify custom handling for expression types, use .| +|||This is not used by the XAML parser. Please look at .| +|||The `expressionType` argument is not used by the XAML parser. To specify the expected return type, use . To specify custom handling for expression types, use .| ### Assembly: System.Xml.dll |Type|Member|Message| |----------|------------|-------------| -|||Validation type should be specified as or .| -|||XDR validation through is obsoleted.| -|||Use .| -|||Use .| -|||Use the property instead.| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -|||Use the property instead.| -|||Use for schema compilation and validation.| -|||Use for schema compilation and validation.| -|||This property has been deprecated. Please use property, which returns a strongly typed attribute type.| -|||This property has been deprecated. Please use the property, which returns a strongly typed element type.| -|||This property has been deprecated. Please use the property, which returns a strongly typed base schema type.| -|||This class should never get constructed as it contains only static methods.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an constructor overload that does not take an parameter.| -|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||Validation type should be specified as or .| +|||XDR validation through is obsoleted.| +|||Use .| +|||Use .| +|||Use the property instead.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +|||Use the property instead.| +|||Use for schema compilation and validation.| +|||Use for schema compilation and validation.| +|||This property has been deprecated. Please use property, which returns a strongly typed attribute type.| +|||This property has been deprecated. Please use the property, which returns a strongly typed element type.| +|||This property has been deprecated. Please use the property, which returns a strongly typed base schema type.| +|||This class should never get constructed as it contains only static methods.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an constructor overload that does not take an parameter.| +|||This method is obsolete and will be removed in a future release of the .NET Framework. Please use an overload of that does not take an parameter.| ## Obsolete Members in Microsoft Assemblies @@ -742,64 +742,64 @@ The tables in this article list the type members that are obsolete in the |Type|Member|Message| |----------|------------|-------------| -|||The recommended alternative is . takes the importer interface pointer as an instead of an , and thus works on both 32-bit and 64-bit architectures.| +|||The recommended alternative is . takes the importer interface pointer as an instead of an , and thus works on both 32-bit and 64-bit architectures.| ### Assembly: Microsoft.Build.Conversion.v4.0.dll |Type|Member|Message| |----------|------------|-------------| -|||Use parameterless overload instead.| -|||Use parameterless overload instead.| -|||Use parameterless method instead.| -|||Use parameterless method instead.| +|||Use parameterless overload instead.| +|||Use parameterless overload instead.| +|||Use parameterless method instead.| +|||Use parameterless method instead.| ### Assembly: Microsoft.Build.Engine.dll |Type|Member|Message| |----------|------------|-------------| -|||Avoid setting . If you were simply passing in the .NET Framework location as the , no other action is necessary. Otherwise, define Toolsets instead in the registry or config file, or by adding elements to the Engine's , in order to use a custom .| -|||If you were simply passing in the .NET Framework location as the , just change to the parameterless constructor. Otherwise, you can define custom toolsets in the registry or configuration file, or add elements to the Engine's . Then use either the or constructor instead.| +|||Avoid setting . If you were simply passing in the .NET Framework location as the , no other action is necessary. Otherwise, define Toolsets instead in the registry or config file, or by adding elements to the Engine's , in order to use a custom .| +|||If you were simply passing in the .NET Framework location as the , just change to the parameterless constructor. Otherwise, you can define custom toolsets in the registry or configuration file, or add elements to the Engine's . Then use either the or constructor instead.| ### Assembly: Microsoft.Build.Framework.dll |Type|Member|Message| |----------|------------|-------------| -|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

Use the property instead.| +|||First deprecated in the .NET Framework 4.5.

Use of this member generates a compiler error.

Use the property instead.| ### Assembly: Microsoft.Build.Utilities.v4.0.dll |Type|Member|Message| |----------|------------|-------------| -|||Use the property.| +|||Use the property.| ### Assembly: Microsoft.Data.Entity.Build.Tasks.dll |Type|Member|Message| |----------|------------|-------------| -| `Microsoft.Data.Entity.Build.Tasks.EntityDeploy`| `Microsoft.Data.Entity.Build.Tasks.EntityDeploy.EntityDataModelEmbeddedResources`|First deprecated in the .NET Framework 4.5.

Used only for version 3.5 backward compatibility.| +| `Microsoft.Data.Entity.Build.Tasks.EntityDeploy`| `Microsoft.Data.Entity.Build.Tasks.EntityDeploy.EntityDataModelEmbeddedResources`|First deprecated in the .NET Framework 4.5.

Used only for version 3.5 backward compatibility.| ### Assembly: Microsoft.VisualBasic.dll |Type|Member|Message| |----------|------------|-------------| -|||This member has been deprecated. Please use to write types, or coerce `FileNumber` and `RecordNumber` to for writing non-object types.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||Use of this member generates a compiler error.

Do not use this method.| -|||The `DynData` registry key works only on Win9x, which is not supported by this version of the .NET Framework. Use the `PerformanceData` registry key instead. This property will be removed from a future version of the Framework.| +|||This member has been deprecated. Please use to write types, or coerce `FileNumber` and `RecordNumber` to for writing non-object types.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||Use of this member generates a compiler error.

Do not use this method.| +|||The `DynData` registry key works only on Win9x, which is not supported by this version of the .NET Framework. Use the `PerformanceData` registry key instead. This property will be removed from a future version of the Framework.| ## See Also [What's Obsolete in the Class Library](../../../docs/framework/whats-new/whats-obsolete.md) diff --git a/docs/framework/whats-new/obsolete-types.md b/docs/framework/whats-new/obsolete-types.md index 0f4619a38c36a..fe1aa30a345a3 100644 --- a/docs/framework/whats-new/obsolete-types.md +++ b/docs/framework/whats-new/obsolete-types.md @@ -83,63 +83,63 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||This type previously indicated an unspecified fatal error in the runtime. The runtime no longer raises this exception so this type is obsolete.| -||Please use instead.| -||Please use instead.| -||The class has been deprecated.| -||First deprecated in the .NET Framework 4.5. Use the class in the System.Runtime.CompilerServices namespace instead.| -||An alternate API is available: Emit the custom attribute instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||This attribute is deprecated and will be removed in a future version.| -||The is deprecated.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||This attribute has been deprecated. Application Domains no longer respect Activation Context boundaries in IDispatch calls.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -||Use instead.| -|| is only used for .NET 2.0 transparency compatibility.| -|| is only used for .NET 2.0 transparency compatibility. Please use the instead.| -||This type is obsolete and will be removed in a future release of the .NET Framework.| -||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| -||This type is obsolete and will be removed in a future release of the .NET Framework.| +||This type previously indicated an unspecified fatal error in the runtime. The runtime no longer raises this exception so this type is obsolete.| +||Please use instead.| +||Please use instead.| +||The class has been deprecated.| +||First deprecated in the .NET Framework 4.5. Use the class in the System.Runtime.CompilerServices namespace instead.| +||An alternate API is available: Emit the custom attribute instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||This attribute is deprecated and will be removed in a future version.| +||The is deprecated.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||This attribute has been deprecated. Application Domains no longer respect Activation Context boundaries in IDispatch calls.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +||Use instead.| +|| is only used for .NET 2.0 transparency compatibility.| +|| is only used for .NET 2.0 transparency compatibility. Please use the instead.| +||This type is obsolete and will be removed in a future release of the .NET Framework.| +||Assembly level declarative security is obsolete and is no longer enforced by the CLR by default.| +||This type is obsolete and will be removed in a future release of the .NET Framework.| [Back to top](#introduction) @@ -148,7 +148,7 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||Use of this type generates a compiler error.

Do not use this type.| +||Use of this type generates a compiler error.

Do not use this type.| [Back to top](#introduction) @@ -157,10 +157,10 @@ manager: "wpickett" |Type|Message| |----------|-------------| -|| has been deprecated.| -|| has been deprecated.| -||The class will be removed in a future release. Please use in System.Design.dll.| -||The class will be removed in a future release.| +|| has been deprecated.| +|| has been deprecated.| +||The class will be removed in a future release. Please use in System.Design.dll.| +||The class will be removed in a future release.| [Back to top](#introduction) @@ -169,14 +169,14 @@ manager: "wpickett" |Type|Message| |----------|-------------| -|| has been deprecated.| -|| has been deprecated.| -|| has been deprecated.| -|| has been deprecated.| -|| has been deprecated.| -|| has been deprecated.| -|| has been deprecated.| -|| has been deprecated.| +|| has been deprecated.| +|| has been deprecated.| +|| has been deprecated.| +|| has been deprecated.| +|| has been deprecated.| +|| has been deprecated.| +|| has been deprecated.| +|| has been deprecated.| [Back to top](#introduction) @@ -185,20 +185,20 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||This class has been deprecated. Use instead.| -||Use of this type is not recommended because DataBindings editing is launched via a instead of the property grid.| -||Use of this type is not recommended because DataBindings editing is launched via a instead of the property grid.| -||The recommended alternative is and .| -||The recommended alternative is and .| -||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| -||The recommended alternative is . The contains additional functionality and allows for more extensibility. To get the , use the `RootDesigner.ReferenceManager` property from your .| -||The recommended alternative is . The contains additional functionality and allows for more extensibility. To get the , use the property from your .| -||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| -||The recommended alternative is because it uses an for editing the content. Designer regions allow for better control of the content being edited.| -||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| -||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| -||Use of this type is not recommended because the AutoFormat dialog is launched by the designer host. The list of available AutoFormats is exposed on the in the property.| -||The recommended alternative is because it uses an for editing the content. Designer regions allow for better control of the content being edited.| +||This class has been deprecated. Use instead.| +||Use of this type is not recommended because DataBindings editing is launched via a instead of the property grid.| +||Use of this type is not recommended because DataBindings editing is launched via a instead of the property grid.| +||The recommended alternative is and .| +||The recommended alternative is and .| +||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| +||The recommended alternative is . The contains additional functionality and allows for more extensibility. To get the , use the `RootDesigner.ReferenceManager` property from your .| +||The recommended alternative is . The contains additional functionality and allows for more extensibility. To get the , use the property from your .| +||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| +||The recommended alternative is because it uses an for editing the content. Designer regions allow for better control of the content being edited.| +||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| +||Use of this type is not recommended because template editing is handled in . To support template editing, expose template data in the property and call .| +||Use of this type is not recommended because the AutoFormat dialog is launched by the designer host. The list of available AutoFormats is exposed on the in the property.| +||The recommended alternative is because it uses an for editing the content. Designer regions allow for better control of the content being edited.| [Back to top](#introduction) @@ -207,13 +207,13 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||This interface has been deprecated. Add a to handle type instead.| -||Use instead to work with the new settings model.| -||This attribute has been deprecated. Use instead. For example, to specify a root designer for CodeDom, use `DesignerSerializerAttribute\(...,typeof\(TypeCodeDomSerializer\)\)`.| -||This class has been deprecated.| -||This class has been deprecated. Use the performance counters through the class instead.| -||This class has been deprecated. Please use instead to access and set the global default proxy. Use 'null' instead of .| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||This interface has been deprecated. Add a to handle type instead.| +||Use instead to work with the new settings model.| +||This attribute has been deprecated. Use instead. For example, to specify a root designer for CodeDom, use `DesignerSerializerAttribute\(...,typeof\(TypeCodeDomSerializer\)\)`.| +||This class has been deprecated.| +||This class has been deprecated. Use the performance counters through the class instead.| +||This class has been deprecated. Please use instead to access and set the global default proxy. Use 'null' instead of .| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| [Back to top](#introduction) @@ -222,7 +222,7 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||The class has been deprecated.| +||The class has been deprecated.| [Back to top](#introduction) @@ -231,15 +231,15 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| [Back to top](#introduction) @@ -248,14 +248,14 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| -||First deprecated in the .NET Framework 4.5.

This type is obsolete. To enable Http , use the `AllowCookies` property on the Http binding or on the .| -||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| -||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| -||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| -||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| -||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| -||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +||First deprecated in the .NET Framework 4.5.

This type is obsolete. To enable Http , use the `AllowCookies` property on the Http binding or on the .| +||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| +||First deprecated in the .NET Framework 4.5.

The peer channel feature is obsolete and will be removed in the future.| [Back to top](#introduction) @@ -264,19 +264,19 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| -||The recommended alternative is .| -||The recommended alternative is .| -||The recommended alternative is .| -||The recommended alternative is .| -||The recommended alternative is .| -||The recommended alternative is .| -||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| -||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| -||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| -||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| -||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| -||The recommended alternative is and .| +||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| +||The recommended alternative is .| +||The recommended alternative is .| +||The recommended alternative is .| +||The recommended alternative is .| +||The recommended alternative is .| +||The recommended alternative is .| +||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| +||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| +||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| +||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| +||This type is obsolete. The Passport authentication product is no longer supported and has been superseded by [Microsoft Account](http://go.microsoft.com/fwlink/?LinkId=733413)| +||The recommended alternative is and .| [Back to top](#introduction) @@ -285,198 +285,198 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| -||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| +||The System.Web.Mobile.dll assembly has been deprecated and should no longer be used. For information about how to develop ASP.NET mobile applications, see [ASP.NET for Mobiles](http://go.microsoft.com/fwlink/?LinkId=157231).| [Back to top](#introduction) @@ -485,11 +485,11 @@ manager: "wpickett" |Type|Message| |----------|-------------| -|All types in the namespace|First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +|All types in the namespace|First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| [Back to top](#introduction) @@ -498,16 +498,16 @@ manager: "wpickett" |Type|Message| |----------|-------------| -|All types in the namespace except and |First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -|All types in the namespace except and |First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +|All types in the namespace except and |First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +|All types in the namespace except and |First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| |All types in the namespace except |First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| -||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| +||First deprecated in the .NET Framework 4.5.

The System.Workflow.\* types are deprecated. Instead, please use the new types from .\*.| [Back to top](#introduction) @@ -531,27 +531,27 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -|All types in the namespace|First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| -||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +|All types in the namespace|First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| +||First deprecated in the .NET Framework 4.5.

The WF 3 types are deprecated. Instead, please use the new WF 4 types from .\*.| [Back to top](#introduction) @@ -560,7 +560,7 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||This is not used by the XAML parser. Please look at .| +||This is not used by the XAML parser. Please look at .| [Back to top](#introduction) @@ -569,11 +569,11 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||Use for schema compilation and validation.| -||Use an created by the method using the appropriate instead.| -||Use of this type generates a compiler error. This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| -||This class has been deprecated. Please use instead.| +||First deprecated in the .NET Framework 4.5.

Use of this type generates a compiler error.

This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||Use for schema compilation and validation.| +||Use an created by the method using the appropriate instead.| +||Use of this type generates a compiler error. This API supports the .NET Framework infrastructure and is not intended to be used directly from your code.| +||This class has been deprecated. Please use instead.| [Back to top](#introduction) @@ -582,7 +582,7 @@ manager: "wpickett" |Type|Message| |----------|-------------| -|| has been deprecated. This interface is no longer in use.| +|| has been deprecated. This interface is no longer in use.| [Back to top](#introduction) @@ -601,8 +601,8 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||This class has been deprecated. Please use from the *Microsoft.Build* assembly instead.| -||This class has been deprecated. Please use from the *Microsoft.Build* assembly instead.| +||This class has been deprecated. Please use from the *Microsoft.Build* assembly instead.| +||This class has been deprecated. Please use from the *Microsoft.Build* assembly instead.| [Back to top](#introduction) @@ -611,24 +611,24 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| -||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| +||Use of this type is not recommended because it is being deprecated in Visual Studio 2005; there will be no replacement for this feature. Please see the documentation for additional help.| [Back to top](#introduction) @@ -637,73 +637,73 @@ manager: "wpickett" For information about migrating from Visual Basic 6, see [Visual Basic 6.0 Resource Center](https://msdn.microsoft.com/library/windows/desktop/ms788229). |Type|Message| |----------|-------------| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| [Back to top](#introduction) @@ -712,55 +712,55 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| -||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| +||This member is obsolete.| [Back to top](#introduction) @@ -769,16 +769,16 @@ manager: "wpickett" |Type|Message| |----------|-------------| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| -||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| +||Microsoft.VisualC.dll is an obsolete assembly and exists only for backwards compatibility.| ## See Also [What's Obsolete in the Class Library](../../../docs/framework/whats-new/whats-obsolete.md) diff --git a/docs/framework/windows-services/service-application-programming-architecture.md b/docs/framework/windows-services/service-application-programming-architecture.md index 0e4995279f3be..38981879a1270 100644 --- a/docs/framework/windows-services/service-application-programming-architecture.md +++ b/docs/framework/windows-services/service-application-programming-architecture.md @@ -25,13 +25,13 @@ ms.author: "ghogen" manager: "douge" --- # Service Application Programming Architecture -Windows Service applications are based on a class that inherits from the class. You override methods from this class and define functionality for them to determine how your service behaves. +Windows Service applications are based on a class that inherits from the class. You override methods from this class and define functionality for them to determine how your service behaves. The main classes involved in service creation are: -- — You override methods from the class when creating a service and define the code to determine how your service functions in this inherited class. +- — You override methods from the class when creating a service and define the code to determine how your service functions in this inherited class. -- and —You use these classes to install and uninstall your service. +- and —You use these classes to install and uninstall your service. In addition, a class named can be used to manipulate the service itself. This class is not involved in the creation of a service, but can be used to start and stop the service, pass commands to it, and return a series of enumerations. diff --git a/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md b/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md index ce0056a5a0b77..a74ae9d6ffb9c 100644 --- a/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md +++ b/docs/framework/windows-services/walkthrough-creating-a-windows-service-application-in-the-component-designer.md @@ -17,11 +17,11 @@ manager: "douge" # Walkthrough: Creating a Windows Service Application in the Component Designer This article demonstrates how to create a simple Windows Service application in Visual Studio that writes messages to an event log. Here are the basic steps that you perform to create and use your service: -1. [Creating a Service](#BK_CreateProject) by using the **Windows Service** project template, and configure it. This template creates a class for you that inherits from and writes much of the basic service code, such as the code to start the service. +1. [Creating a Service](#BK_CreateProject) by using the **Windows Service** project template, and configure it. This template creates a class for you that inherits from and writes much of the basic service code, such as the code to start the service. 2. [Adding Features to the Service](#BK_WriteCode) for the and procedures, and override any other methods that you want to redefine. -3. [Setting Service Status](#BK_SetStatus). By default, services created with implement only a subset of the available status flags. If your service takes a long time to start up, pause, or stop, you can implement status values such as Start Pending or Stop Pending to indicate that it's working on an operation. +3. [Setting Service Status](#BK_SetStatus). By default, services created with implement only a subset of the available status flags. If your service takes a long time to start up, pause, or stop, you can implement status values such as Start Pending or Stop Pending to indicate that it's working on an operation. 4. [Adding Installers to the Service](#BK_AddInstallers) for your service application. @@ -52,7 +52,7 @@ This article demonstrates how to create a simple Windows Service application in 2. In the list of Visual Basic or Visual C# project templates, choose **Windows Service**, and name the project **MyNewService**. Choose **OK**. - The project template automatically adds a component class named `Service1` that inherits from . + The project template automatically adds a component class named `Service1` that inherits from . 3. On the **Edit** menu, choose **Find and Replace**, **Find in Files** (Keyboard: Ctrl+Shift+F). Change all occurrences of `Service1` to `MyNewService`. You’ll find instances in Service1.cs, Program.cs, and Service1.Designer.cs (or their .vb equivalents). @@ -89,7 +89,7 @@ This article demonstrates how to create a simple Windows Service application in [!code-csharp[VbRadconService#3](../../../samples/snippets/csharp/VS_Snippets_VBCSharp/VbRadconService/CS/MyNewService.cs#3)] [!code-vb[VbRadconService#3](../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRadconService/VB/MyNewService.vb#3)] - A service application is designed to be long-running, so it usually polls or monitors something in the system. The monitoring is set up in the method. However, doesn’t actually do the monitoring. The method must return to the operating system after the service's operation has begun. It must not loop forever or block. To set up a simple polling mechanism, you can use the component as follows: In the method, set parameters on the component, and then set the property to `true`. The timer raises events in your code periodically, at which time your service could do its monitoring. You can use the following code to do this: + A service application is designed to be long-running, so it usually polls or monitors something in the system. The monitoring is set up in the method. However, doesn’t actually do the monitoring. The method must return to the operating system after the service's operation has begun. It must not loop forever or block. To set up a simple polling mechanism, you can use the component as follows: In the method, set parameters on the component, and then set the property to `true`. The timer raises events in your code periodically, at which time your service could do its monitoring. You can use the following code to do this: ```csharp // Set up a timer to trigger every minute. @@ -125,7 +125,7 @@ This article demonstrates how to create a simple Windows Service application in End Sub ``` - You might want to perform tasks by using background worker threads instead of running all your work on the main thread. For an example of this, see the reference page. + You might want to perform tasks by using background worker threads instead of running all your work on the main thread. For an example of this, see the reference page. #### To define what occurs when the service is stopped @@ -153,7 +153,7 @@ This article demonstrates how to create a simple Windows Service application in #### To implement service pending status -1. Add a `using` statement or `Imports` declaration to the namespace in the MyNewService.cs or MyNewService.vb file: +1. Add a `using` statement or `Imports` declaration to the namespace in the MyNewService.cs or MyNewService.vb file: ```csharp using System.Runtime.InteropServices; diff --git a/docs/framework/windows-workflow-foundation/compensation.md b/docs/framework/windows-workflow-foundation/compensation.md index 0142e8b632b05..7fc2d7b2480c6 100644 --- a/docs/framework/windows-workflow-foundation/compensation.md +++ b/docs/framework/windows-workflow-foundation/compensation.md @@ -20,7 +20,7 @@ Compensation in [!INCLUDE[wf](../../../includes/wf-md.md)] is the mechanism by w A transaction allows you to combine multiple operations into a single unit of work. Using a transaction gives your application the ability to abort (roll back) all changes executed from within the transaction if any errors occur during any part of the transaction process. However, using transactions may not be appropriate if the work is long running. For example, a travel planning application is implemented as a workflow. The steps of the workflow may consist of booking a flight, waiting for manager approval, and then paying for the flight. This process could take many days and it is not practical for the steps of booking and paying for the flight to participate in the same transaction. In a scenario such as this, compensation could be used to undo the booking step of the workflow if there is a failure later in the processing. > [!NOTE] -> This topic covers compensation in workflows. [!INCLUDE[crabout](../../../includes/crabout-md.md)] transactions in workflows, see [Transactions](../../../docs/framework/windows-workflow-foundation/workflow-transactions.md) and . [!INCLUDE[crabout](../../../includes/crabout-md.md)] transactions, see and . +> This topic covers compensation in workflows. [!INCLUDE[crabout](../../../includes/crabout-md.md)] transactions in workflows, see [Transactions](../../../docs/framework/windows-workflow-foundation/workflow-transactions.md) and . [!INCLUDE[crabout](../../../includes/crabout-md.md)] transactions, see and . ## Using CompensableActivity is the core compensation activity in [!INCLUDE[wf1](../../../includes/wf1-md.md)]. Any activities that perform work that may need to be compensated are placed into the of a . In this example, the reservation step of purchasing a flight is placed into the of a and the cancellation of the reservation is placed into the . Immediately following the in the workflow are two activities that wait for manager approval and then complete the purchasing step of the flight. If an error condition causes the workflow to be canceled after the has successfully completed, then the activities in the handler are scheduled and the flight is canceled. diff --git a/docs/framework/windows-workflow-foundation/contract-first-workflow-service-development.md b/docs/framework/windows-workflow-foundation/contract-first-workflow-service-development.md index 3a96e2ee87876..236c7d3946ed7 100644 --- a/docs/framework/windows-workflow-foundation/contract-first-workflow-service-development.md +++ b/docs/framework/windows-workflow-foundation/contract-first-workflow-service-development.md @@ -126,9 +126,9 @@ Starting with [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], [!INCLUDE[wf ### Generation of configured messaging activities Two public static methods are added to the and activities to support the generation of pre-configured message activities when using contract-first workflow services. -- +- -- +- The activity generated by these methods should pass contract validation, and therefore these methods are used internally as part of the validation logic for and . The , , , , , and are all pre-configured to match the imported contract. In the content properties page for the activities in the workflow designer, the **Message** or **Parameters** sections are also pre-configured to match the contract. diff --git a/docs/framework/windows-workflow-foundation/creating-asynchronous-activities-in-wf.md b/docs/framework/windows-workflow-foundation/creating-asynchronous-activities-in-wf.md index 2a6e9361ca394..be8c672a24a26 100644 --- a/docs/framework/windows-workflow-foundation/creating-asynchronous-activities-in-wf.md +++ b/docs/framework/windows-workflow-foundation/creating-asynchronous-activities-in-wf.md @@ -17,7 +17,7 @@ manager: "erikre" provides activity authors a base class to use that enables derived activities to implement asynchronous execution logic. This is useful for custom activities that must perform asynchronous work without holding the workflow scheduler thread and blocking any activities that may be able to run in parallel. This topic provides an overview of how to create custom asynchronous activities using . ## Using AsyncCodeActivity - provides custom activity authors with different base classes for different activity authoring requirements. Each one carries a particular semantic and provides a workflow author (and the activity runtime) a corresponding contract. An based activity is an activity that performs work asynchronously relative to the scheduler thread and whose execution logic is expressed in managed code. As a result of going asynchronous, an may induce an idle point during execution. Due to the volatile nature of asynchronous work, an always creates a no persist block for the duration of the activity’s execution. This prevents the workflow runtime from persisting the workflow instance in the middle of the asynchronous work, and also prevents the workflow instance from unloading while the asynchronous code is executing. + provides custom activity authors with different base classes for different activity authoring requirements. Each one carries a particular semantic and provides a workflow author (and the activity runtime) a corresponding contract. An based activity is an activity that performs work asynchronously relative to the scheduler thread and whose execution logic is expressed in managed code. As a result of going asynchronous, an may induce an idle point during execution. Due to the volatile nature of asynchronous work, an always creates a no persist block for the duration of the activity’s execution. This prevents the workflow runtime from persisting the workflow instance in the middle of the asynchronous work, and also prevents the workflow instance from unloading while the asynchronous code is executing. ### AsyncCodeActivity Methods Activities that derive from can create asynchronous execution logic by overriding the and methods with custom code. When called by the runtime, these methods are passed an . allows the activity author to provide shared state across / in the context’s property. In the following example, a `GenerateRandom` activity generates a random number asynchronously. @@ -40,7 +40,7 @@ manager: "erikre" [!code-csharp[CFX_ActivityExample#12](../../../samples/snippets/csharp/VS_Snippets_CFX/CFX_ActivityExample/cs/Program.cs#12)] ### Sharing State Between the BeginExecute and EndExecute Methods - In the previous example, the object that was created in was accessed in the . This is possible because the `file` variable was passed in the property in . This is the correct method for sharing state between and . It is incorrect to use a member variable in the derived class (`FileWriter` in this case) to share state between and because the activity object may be referenced by multiple activity instances. Attempting to use a member variable to share state can result in values from one overwriting or consuming values from another . + In the previous example, the object that was created in was accessed in the . This is possible because the `file` variable was passed in the property in . This is the correct method for sharing state between and . It is incorrect to use a member variable in the derived class (`FileWriter` in this case) to share state between and because the activity object may be referenced by multiple activity instances. Attempting to use a member variable to share state can result in values from one overwriting or consuming values from another . ### Accessing Argument Values The environment of an consists of the arguments defined on the activity. These arguments can be accessed from the / overrides using the parameter. The arguments cannot be accessed in the delegate, but the argument values or any other desired data can be passed in to the delegate using its parameters. In the following example, a random number-generating activity is defined that obtains the inclusive upper bound from its `Max` argument. The value of the argument is passed in to the asynchronous code when the delegate is invoked. diff --git a/docs/framework/windows-workflow-foundation/csharp-expressions.md b/docs/framework/windows-workflow-foundation/csharp-expressions.md index 5a030cb765e91..fd1540ba26900 100644 --- a/docs/framework/windows-workflow-foundation/csharp-expressions.md +++ b/docs/framework/windows-workflow-foundation/csharp-expressions.md @@ -44,7 +44,7 @@ Starting with [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], C# expressio Visual Basic expressions in existing [!INCLUDE[netfx40_short](../../../includes/netfx40-short-md.md)] C# workflow projects that have been migrated to [!INCLUDE[netfx_current_short](../../../includes/netfx-current-short-md.md)] are supported. When the Visual Basic expressions are viewed in the workflow designer, the text of the existing Visual Basic expression is replaced with **Value was set in XAML**, unless the Visual Basic expression is valid C# syntax. If the Visual Basic expression is valid C# syntax, then the expression is displayed. To update the Visual Basic expressions to C#, you can edit them in the workflow designer and specify the equivalent C# expression. It is not required to update the Visual Basic expressions to C#, but once the expressions are updated in the workflow designer they are converted to C# and may not be reverted to Visual Basic. ### Using C# expressions in code workflows - C# expressions are supported in [!INCLUDE[netfx_current_short](../../../includes/netfx-current-short-md.md)] code based workflows, but before the workflow can be invoked the C# expressions must be compiled using . Workflow authors can use `CSharpValue` to represent the r-value of an expression, and `CSharpReference` to represent the l-value of an expression. In the following example, a workflow is created with an `Assign` activity and a `WriteLine` activity contained in a `Sequence` activity. A `CSharpReference` is specified for the `To` argument of the `Assign`, and represents the l-value of the expression. A `CSharpValue` is specified for the `Value` argument of the `Assign`, and for the `Text` argument of the `WriteLine`, and represents the r-value for those two expressions. + C# expressions are supported in [!INCLUDE[netfx_current_short](../../../includes/netfx-current-short-md.md)] code based workflows, but before the workflow can be invoked the C# expressions must be compiled using . Workflow authors can use `CSharpValue` to represent the r-value of an expression, and `CSharpReference` to represent the l-value of an expression. In the following example, a workflow is created with an `Assign` activity and a `WriteLine` activity contained in a `Sequence` activity. A `CSharpReference` is specified for the `To` argument of the `Assign`, and represents the l-value of the expression. A `CSharpValue` is specified for the `Value` argument of the `Assign`, and for the `Text` argument of the `WriteLine`, and represents the r-value for those two expressions. ```csharp Variable n = new Variable @@ -201,7 +201,7 @@ static void CompileExpressions(DynamicActivity dynamicActivity) C# expressions are supported in compiled XAML workflows that are compiled to a type as part of a C# workflow project that targets [!INCLUDE[netfx_current_short](../../../includes/netfx-current-short-md.md)]. Compiled XAML is the default type of workflow authoring in [!INCLUDE[vs_current_short](../../../includes/vs-current-short-md.md)], and C# workflow projects created in [!INCLUDE[vs_current_short](../../../includes/vs-current-short-md.md)] that target [!INCLUDE[netfx_current_short](../../../includes/netfx-current-short-md.md)] use C# expressions. #### Loose Xaml - C# expressions are supported in loose XAML workflows. The workflow host program that loads and invokes the loose XAML workflow must target [!INCLUDE[netfx_current_short](../../../includes/netfx-current-short-md.md)], and must be set to `true` (the default is `false`). To set to `true`, create an instance with its property set to `true`, and pass it as a parameter to . If `CompileExpressions` Is not set to `true`, a will be thrown with a message similar to the following: `Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.` + C# expressions are supported in loose XAML workflows. The workflow host program that loads and invokes the loose XAML workflow must target [!INCLUDE[netfx_current_short](../../../includes/netfx-current-short-md.md)], and must be set to `true` (the default is `false`). To set to `true`, create an instance with its property set to `true`, and pass it as a parameter to . If `CompileExpressions` Is not set to `true`, a will be thrown with a message similar to the following: `Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.` ```csharp ActivityXamlServicesSettings settings = new ActivityXamlServicesSettings diff --git a/docs/framework/windows-workflow-foundation/dynamic-update.md b/docs/framework/windows-workflow-foundation/dynamic-update.md index 7cc4c1e3ef54a..fd3b18601d530 100644 --- a/docs/framework/windows-workflow-foundation/dynamic-update.md +++ b/docs/framework/windows-workflow-foundation/dynamic-update.md @@ -33,9 +33,9 @@ Dynamic update provides a mechanism for workflow application developers to updat This topic provides an overview of the dynamic update process of adding a new activity to a persisted instance of a compiled Xaml workflow. ### Prepare the workflow definition for dynamic update - The first step in the dynamic update process is to prepare the desired workflow definition for update. This is done by calling the method and passing in the workflow definition to modify. This method validates and then walks the workflow tree to identify all of the objects such as public activities and variables that need to be tagged so they can be compared later with the modified workflow definition. When this is complete, the workflow tree is cloned and attached to the original workflow definition. When the update map is created, the updated version of the workflow definition is compared with the original workflow definition and the update map is generated based on the differences. + The first step in the dynamic update process is to prepare the desired workflow definition for update. This is done by calling the method and passing in the workflow definition to modify. This method validates and then walks the workflow tree to identify all of the objects such as public activities and variables that need to be tagged so they can be compared later with the modified workflow definition. When this is complete, the workflow tree is cloned and attached to the original workflow definition. When the update map is created, the updated version of the workflow definition is compared with the original workflow definition and the update map is generated based on the differences. - To prepare a Xaml workflow for dynamic update it may be loaded into an , and then the is passed into . + To prepare a Xaml workflow for dynamic update it may be loaded into an , and then the is passed into . > [!NOTE] > For more information about working with serialized workflows and , see [Serializing Workflows and Activities to and from XAML](../../../docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md). @@ -82,7 +82,7 @@ s.Activities.Insert(2, va); ``` ### Create the update map - Once the workflow definition that was prepared for update has been modified, the update map can be created. To create a dynamic update map, the method is invoked. This returns a that contains the information the runtime needs to modify a persisted workflow instance so that it may be loaded and resumed with the new workflow definition. In the following example, a dynamic map is created for the modified `MortgageWorkflow` definition from the previous example. + Once the workflow definition that was prepared for update has been modified, the update map can be created. To create a dynamic update map, the method is invoked. This returns a that contains the information the runtime needs to modify a persisted workflow instance so that it may be loaded and resumed with the new workflow definition. In the following example, a dynamic map is created for the modified `MortgageWorkflow` definition from the previous example. ```csharp // Create the update map. @@ -100,7 +100,7 @@ using (FileStream fs = System.IO.File.Open(@"C:\WorkflowDefitinions\MortgageWork } ``` - When returns, the cloned workflow definition and other dynamic update information that was added in the call to is removed, and the modified workflow definition is ready to be saved so that it can be used later when resuming updated workflow instances. In the following example, the modified workflow definition is saved to `MortgageWorkflow_v2.xaml`. + When returns, the cloned workflow definition and other dynamic update information that was added in the call to is removed, and the modified workflow definition is ready to be saved so that it can be used later when resuming updated workflow instances. In the following example, the modified workflow definition is saved to `MortgageWorkflow_v2.xaml`. ```csharp // Save the modified workflow definition. @@ -111,7 +111,7 @@ sw.Close(); ``` ### Apply the update map to the desired persisted workflow instances - Applying the update map can be done at any time after creating it. It can be done right away using the instance that was returned by , or it can be done later using a saved copy of the update map. To update a workflow instance, load it into a using . Next, create a using the updated workflow definition, and the desired . This may be different than the one that was used to persist the original workflow, and typically is in order to reflect that the persisted instance has been modified. Once the is created, it is loaded using the overload of that takes a , and then unloaded with a call to . This applies the dynamic update and persists the updated workflow instance. + Applying the update map can be done at any time after creating it. It can be done right away using the instance that was returned by , or it can be done later using a saved copy of the update map. To update a workflow instance, load it into a using . Next, create a using the updated workflow definition, and the desired . This may be different than the one that was used to persist the original workflow, and typically is in order to reflect that the persisted instance has been modified. Once the is created, it is loaded using the overload of that takes a , and then unloaded with a call to . This applies the dynamic update and persists the updated workflow instance. ```csharp // Load the serialized update map. diff --git a/docs/framework/windows-workflow-foundation/net-framework-3-0-wf-in-net-framework-4-interop.md b/docs/framework/windows-workflow-foundation/net-framework-3-0-wf-in-net-framework-4-interop.md index a3b913ef35c3f..2f12372c74b24 100644 --- a/docs/framework/windows-workflow-foundation/net-framework-3-0-wf-in-net-framework-4-interop.md +++ b/docs/framework/windows-workflow-foundation/net-framework-3-0-wf-in-net-framework-4-interop.md @@ -22,7 +22,7 @@ The activity is a [!INCLUDE[netfx_cu ## Criteria for Using a WF 3 Activity with an Interop Activity For a WF 3 activity to successfully execute within an activity, the following criteria must be met: -- The WF 3 activity must derive from . +- The WF 3 activity must derive from . - The WF 3 activity must be declared as `public` and cannot be `abstract`. diff --git a/docs/framework/windows-workflow-foundation/samples/custom-composite-designers-workflow-items-presenter.md b/docs/framework/windows-workflow-foundation/samples/custom-composite-designers-workflow-items-presenter.md index b95232b2e165a..f550e52b21498 100644 --- a/docs/framework/windows-workflow-foundation/samples/custom-composite-designers-workflow-items-presenter.md +++ b/docs/framework/windows-workflow-foundation/samples/custom-composite-designers-workflow-items-presenter.md @@ -14,11 +14,11 @@ ms.author: "erikre" manager: "erikre" --- # Custom Composite Designers - Workflow Items Presenter -The is a key type in the WF designer programming model that allows for the editing of a collection of contained elements. This sample shows how to build an activity designer that surfaces such an editable collection. +The is a key type in the WF designer programming model that allows for the editing of a collection of contained elements. This sample shows how to build an activity designer that surfaces such an editable collection. This sample demonstrates: -- Creating a custom activity designer with a . +- Creating a custom activity designer with a . - Creating an activity designer with a "collapsed" and "expanded" view. @@ -35,13 +35,13 @@ The . A few things to point out: +- The creation of a custom activity designer with a . A few things to point out: - Note the use of WPF data binding to bind to `ModelItem.Branches`. `ModelItem` is the property on `WorkflowElementDesigner` that refers to the underlying object the designer is being used for, in this case, our `Parallel`. - - The can be used to put a visual to display between the individual items in the collection. + - The can be used to put a visual to display between the individual items in the collection. - - is a template that can be provided to determine the layout of the items in the collection. In this case, a horizontal stack panel is used. + - is a template that can be provided to determine the layout of the items in the collection. In this case, a horizontal stack panel is used. This following example code shows this. diff --git a/docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md b/docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md index d89b55f9340d6..240ded8e65de2 100644 --- a/docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md +++ b/docs/framework/windows-workflow-foundation/serializing-workflows-and-activities-to-and-from-xaml.md @@ -79,7 +79,7 @@ sw.Close(); > [!NOTE] > [!INCLUDE[crabout](../../../includes/crabout-md.md)] invoking workflows with input and output arguments, see [Using WorkflowInvoker and WorkflowApplication](../../../docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md) and . - If the serialized workflow contains C# expressions, then an instance with its property set to `true` must be passed as a parameter to , otherwise a will be thrown with a message similar to the following: `Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.` + If the serialized workflow contains C# expressions, then an instance with its property set to `true` must be passed as a parameter to , otherwise a will be thrown with a message similar to the following: `Expression Activity type 'CSharpValue`1' requires compilation in order to run. Please ensure that the workflow has been compiled.` ```csharp ActivityXamlServicesSettings settings = new ActivityXamlServicesSettings diff --git a/docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md b/docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md index afd6cd6d572e4..1af042027ca11 100644 --- a/docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md +++ b/docs/framework/windows-workflow-foundation/using-workflowinvoker-and-workflowapplication.md @@ -64,7 +64,7 @@ manager: "erikre" [!code-csharp[CFX_WorkflowApplicationExample#30](../../../samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#30)] ### Retrieving Output Arguments of a Workflow - When a workflow completes, any output arguments can be retrieved in the handler by accessing the dictionary. The following example hosts a workflow using . A instance is constructed using using a workflow definition consisting of a single `DiceRoll` activity. The `DiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes, the outputs are retrieved in the handler. + When a workflow completes, any output arguments can be retrieved in the handler by accessing the dictionary. The following example hosts a workflow using . A instance is constructed using using a workflow definition consisting of a single `DiceRoll` activity. The `DiceRoll` activity has two output arguments that represent the results of the dice roll operation. When the workflow completes, the outputs are retrieved in the handler. [!code-csharp[CFX_WorkflowApplicationExample#130](../../../samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#130)] diff --git a/docs/framework/windows-workflow-foundation/workflow-transactions.md b/docs/framework/windows-workflow-foundation/workflow-transactions.md index acdeb9432867c..38c87292b2e57 100644 --- a/docs/framework/windows-workflow-foundation/workflow-transactions.md +++ b/docs/framework/windows-workflow-foundation/workflow-transactions.md @@ -14,7 +14,7 @@ ms.author: "erikre" manager: "erikre" --- # Workflow Transactions -[!INCLUDE[wf1](../../../includes/wf1-md.md)] provides support for participating in transactions by using the activity to scope a transacted unit of work. While the must be explicitly completed the activity implicitly calls complete on the transaction upon successful completion. Any activities that are contained in the of the activity participate in the transaction. WF can to flow transactions into a workflow through the use of the activity. Like the activity, any activity contained in the participates in the transaction. WF ensures that activities dependent on works with both and . If the system-provided activities do not address all requirements, custom activities can be built using the to enable advanced flow and transaction control scenarios. +[!INCLUDE[wf1](../../../includes/wf1-md.md)] provides support for participating in transactions by using the activity to scope a transacted unit of work. While the must be explicitly completed the activity implicitly calls complete on the transaction upon successful completion. Any activities that are contained in the of the activity participate in the transaction. WF can to flow transactions into a workflow through the use of the activity. Like the activity, any activity contained in the participates in the transaction. WF ensures that activities dependent on works with both and . If the system-provided activities do not address all requirements, custom activities can be built using the to enable advanced flow and transaction control scenarios. In the following example, taken from the [Basic TransactionScope](../../../docs/framework/windows-workflow-foundation/samples/basic-transactionscope.md) sample, a workflow is constructed consisting of a activity that contains child activities including a activity. The activities of the execute under the transaction initialized by the activity. @@ -55,4 +55,4 @@ static Activity ScenarioOne() ## See Also - + diff --git a/docs/framework/winforms/advanced/about-gdi-managed-code.md b/docs/framework/winforms/advanced/about-gdi-managed-code.md index cf5b55dc04863..5072eb61b1798 100644 --- a/docs/framework/winforms/advanced/about-gdi-managed-code.md +++ b/docs/framework/winforms/advanced/about-gdi-managed-code.md @@ -39,31 +39,31 @@ manager: "wpickett" Discusses how to transform graphics with [!INCLUDE[ndptecgdiplus](../../../../includes/ndptecgdiplus-md.md)]. ## Reference - + Describes this class and has links to all its members. - + Describes this class and has links to all its members. - , + , Describes this class and has links to all its members. - , + , Describes this class and has links to all its members. - , + , Describes this class and has links to all its members. - , + , Describes this class and has links to all its members. - , + , Describes this class and has links to all its members. - + Describes this class and has links to all its members. - + Describes this class and has links to all its members. ## Related Sections diff --git a/docs/framework/winforms/advanced/antialiasing-with-lines-and-curves.md b/docs/framework/winforms/advanced/antialiasing-with-lines-and-curves.md index 2a2f2d8ca98ca..c2f1a9865d5b8 100644 --- a/docs/framework/winforms/advanced/antialiasing-with-lines-and-curves.md +++ b/docs/framework/winforms/advanced/antialiasing-with-lines-and-curves.md @@ -50,6 +50,6 @@ When you use [!INCLUDE[ndptecgdiplus](../../../../includes/ndptecgdiplus-md.md)] [!code-vb[LinesCurvesAndShapes#81](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/LinesCurvesAndShapes/VB/Class1.vb#81)] ## See Also - + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [How to: Use Antialiasing with Text](../../../../docs/framework/winforms/advanced/how-to-use-antialiasing-with-text.md) diff --git a/docs/framework/winforms/advanced/application-settings-architecture.md b/docs/framework/winforms/advanced/application-settings-architecture.md index 04a5fb75e560a..4cfc1fb0df437 100644 --- a/docs/framework/winforms/advanced/application-settings-architecture.md +++ b/docs/framework/winforms/advanced/application-settings-architecture.md @@ -114,7 +114,7 @@ This topic describes how the Application Settings architecture works, and explor If you implement your own settings class, you can use the to mark a setting for either binary or custom serialization using the enumeration. For more information on creating your own settings class in code, see [How to: Create Application Settings](../../../../docs/framework/winforms/advanced/how-to-create-application-settings.md). ### Settings File Locations - The location of the `app`.exe.config and *user*.config files will differ based on how the application is installed. For a Windows Forms-based application copied onto the local computer, `app`.exe.config will reside in the same directory as the base directory of the application's main executable file, and *user*.config will reside in the location specified by the property. For an application installed by means of [!INCLUDE[ndptecclick](../../../../includes/ndptecclick-md.md)], both of these files will reside in the [!INCLUDE[ndptecclick](../../../../includes/ndptecclick-md.md)] Data Directory underneath %InstallRoot%\Documents and Settings\\*username*\Local Settings. + The location of the `app`.exe.config and *user*.config files will differ based on how the application is installed. For a Windows Forms-based application copied onto the local computer, `app`.exe.config will reside in the same directory as the base directory of the application's main executable file, and *user*.config will reside in the location specified by the property. For an application installed by means of [!INCLUDE[ndptecclick](../../../../includes/ndptecclick-md.md)], both of these files will reside in the [!INCLUDE[ndptecclick](../../../../includes/ndptecclick-md.md)] Data Directory underneath %InstallRoot%\Documents and Settings\\*username*\Local Settings. The storage location of these files is slightly different if a user has enabled roaming profiles, which enables a user to define different Windows and application settings when he or she is using other computers within a domain. In that case, both [!INCLUDE[ndptecclick](../../../../includes/ndptecclick-md.md)] applications and non-[!INCLUDE[ndptecclick](../../../../includes/ndptecclick-md.md)] applications will have their `app`.exe.config and *user*.config files stored under %InstallRoot%\Documents and Settings\\*username*\Application Data. @@ -128,7 +128,7 @@ This topic describes how the Application Settings architecture works, and explor ## Custom Settings Providers In the Application Settings architecture, there is a loose coupling between the applications settings wrapper class, derived from , and the associated settings provider or providers, derived from . This association is defined only by the applied to the wrapper class or its individual properties. If a settings provider is not explicitly specified, the default provider, , is used. As a result, this architecture supports creating and using custom settings providers. - For example, suppose that you want to develop and use `SqlSettingsProvider`, a provider that will store all settings data in a Microsoft SQL Server database. Your -derived class would receive this information in its `Initialize` method as a parameter of type . You would then implement the method to retrieve your settings from the data store, and to save them. Your provider can use the supplied to to determine the property's name, type, and scope, as well as any other settings attributes defined for that property. + For example, suppose that you want to develop and use `SqlSettingsProvider`, a provider that will store all settings data in a Microsoft SQL Server database. Your -derived class would receive this information in its `Initialize` method as a parameter of type . You would then implement the method to retrieve your settings from the data store, and to save them. Your provider can use the supplied to to determine the property's name, type, and scope, as well as any other settings attributes defined for that property. Your provider will need to implement one property and one method whose implementations may not be obvious. The property is an abstract property of ; you should program it to return the following: @@ -149,7 +149,7 @@ This topic describes how the Application Settings architecture works, and explor > [!IMPORTANT] > You should ensure that your provider is thread-safe, and only allows one thread at a time to write to the configuration files. - Your provider does not need to support all of the settings attributes defined in the namespace, though it must at a minimum support and , and should also support . For those attributes that it does not support, your provider should just fail without notification; it should not throw an exception. If the settings class uses an invalid combination of attributes, however — such as applying and to the same setting — your provider should throw an exception and cease operation. + Your provider does not need to support all of the settings attributes defined in the namespace, though it must at a minimum support and , and should also support . For those attributes that it does not support, your provider should just fail without notification; it should not throw an exception. If the settings class uses an invalid combination of attributes, however — such as applying and to the same setting — your provider should throw an exception and cease operation. ## See Also diff --git a/docs/framework/winforms/advanced/bezier-splines-in-gdi.md b/docs/framework/winforms/advanced/bezier-splines-in-gdi.md index c761f62a499ed..89d40a9007311 100644 --- a/docs/framework/winforms/advanced/bezier-splines-in-gdi.md +++ b/docs/framework/winforms/advanced/bezier-splines-in-gdi.md @@ -43,8 +43,8 @@ A Bézier spline is a curve specified by four points: two end points (p1 and p2) ![Paths](../../../../docs/framework/winforms/advanced/media/aboutgdip02-art13.gif "Aboutgdip02_art13") ## See Also - - + + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [Constructing and Drawing Curves](../../../../docs/framework/winforms/advanced/constructing-and-drawing-curves.md) [How to: Create Graphics Objects for Drawing](../../../../docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md) diff --git a/docs/framework/winforms/advanced/brushes-and-filled-shapes-in-gdi.md b/docs/framework/winforms/advanced/brushes-and-filled-shapes-in-gdi.md index b17adc0c337b9..1347383d512b0 100644 --- a/docs/framework/winforms/advanced/brushes-and-filled-shapes-in-gdi.md +++ b/docs/framework/winforms/advanced/brushes-and-filled-shapes-in-gdi.md @@ -82,10 +82,10 @@ A closed shape, such as a rectangle or an ellipse, consists of an outline and an ![Filled Shape](../../../../docs/framework/winforms/advanced/media/aboutgdip02-art23.gif "AboutGdip02_Art23") ## See Also - - - - + + + + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [How to: Draw a Filled Rectangle on a Windows Form](../../../../docs/framework/winforms/advanced/how-to-draw-a-filled-rectangle-on-a-windows-form.md) [How to: Draw a Filled Ellipse on a Windows Form](../../../../docs/framework/winforms/advanced/how-to-draw-a-filled-ellipse-on-a-windows-form.md) diff --git a/docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md b/docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md index e3a6e1abad708..832156ea83b20 100644 --- a/docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md +++ b/docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md @@ -25,26 +25,26 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Support COM Interop by Displaying a Windows Form with the ShowDialog Method -You can resolve Component Object Model (COM) interoperability problems by displaying your Windows Form on a [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop, which is created by using the method. +You can resolve Component Object Model (COM) interoperability problems by displaying your Windows Form on a [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop, which is created by using the method. To make a form work correctly from a COM client application, you must run it on a Windows Forms message loop. To do this, use one of the following approaches: -- Use the method to display the Windows Form; +- Use the method to display the Windows Form; - Display each Windows Form on a separate thread. For more information, see [How to: Support COM Interop by Displaying Each Windows Form on Its Own Thread](../../../../docs/framework/winforms/advanced/how-to-support-com-interop-by-displaying-each-windows-form-on-its-own-thread.md). ## Procedure - Using the method can be the easiest way to display a form on a [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop because, of all the approaches, it requires the least code to implement. + Using the method can be the easiest way to display a form on a [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop because, of all the approaches, it requires the least code to implement. - The method suspends the unmanaged application's message loop and displays the form as a dialog box. Because the host application's message loop has been suspended, the method creates a new [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop to process the form's messages. + The method suspends the unmanaged application's message loop and displays the form as a dialog box. Because the host application's message loop has been suspended, the method creates a new [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop to process the form's messages. - The disadvantage of using the method is that the form will be opened as a modal dialog box. This behavior blocks any user interface (UI) in the calling application while the Windows Form is open. When the user exits the form, the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop closes and the earlier application's message loop starts running again. + The disadvantage of using the method is that the form will be opened as a modal dialog box. This behavior blocks any user interface (UI) in the calling application while the Windows Form is open. When the user exits the form, the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop closes and the earlier application's message loop starts running again. - You can create a class library in Windows Forms which has a method to show the form, and then build the class library for COM interop. You can use this DLL file from Visual Basic 6.0 or Microsoft Foundation Classes (MFC), and from either of these environments you can call the method to display the form. + You can create a class library in Windows Forms which has a method to show the form, and then build the class library for COM interop. You can use this DLL file from Visual Basic 6.0 or Microsoft Foundation Classes (MFC), and from either of these environments you can call the method to display the form. #### To support COM interop by displaying a windows form with the ShowDialog method -- Replace all calls to the method with calls to the method in your [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] component. +- Replace all calls to the method with calls to the method in your [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] component. ## See Also [Exposing .NET Framework Components to COM](../../../../docs/framework/interop/exposing-dotnet-components-to-com.md) diff --git a/docs/framework/winforms/advanced/double-buffered-graphics.md b/docs/framework/winforms/advanced/double-buffered-graphics.md index 6b16970141480..8054c487ceb8c 100644 --- a/docs/framework/winforms/advanced/double-buffered-graphics.md +++ b/docs/framework/winforms/advanced/double-buffered-graphics.md @@ -34,9 +34,9 @@ Flicker is a common problem when programming graphics. Graphics operations that For more advanced double buffering scenarios, such as animation or advanced memory management, you can use the .NET Framework classes to implement your own double-buffering logic. The class responsible for allocating and managing individual graphics buffers is the class. Every application domain has its own default instance that manages all of the default double buffering for that application. In most cases there will be only one application domain per application, so there is generally one default per application. Default instances are managed by the class. You can retrieve a reference to the default instance by calling the . You can also create a dedicated instance, which can improve performance for graphically intensive applications. For information on how to create a instance, see [How to: Manually Manage Buffered Graphics](../../../../docs/framework/winforms/advanced/how-to-manually-manage-buffered-graphics.md). ## Manually Displaying Buffered Graphics - You can use an instance of the class to create graphics buffers by calling the , which returns an instance of the class. A object manages a memory buffer that is associated with a rendering surface, such as a form or control. + You can use an instance of the class to create graphics buffers by calling the , which returns an instance of the class. A object manages a memory buffer that is associated with a rendering surface, such as a form or control. - After it is instantiated, the class manages rendering to an in-memory graphics buffer. You can render graphics to the memory buffer through the , which exposes a object that directly represents the memory buffer. You can paint to this object just as you would to a object that represents a drawing surface. After all the graphics have been drawn to the buffer, you can use the to copy the contents of the buffer to the drawing surface on the screen. + After it is instantiated, the class manages rendering to an in-memory graphics buffer. You can render graphics to the memory buffer through the , which exposes a object that directly represents the memory buffer. You can paint to this object just as you would to a object that represents a drawing surface. After all the graphics have been drawn to the buffer, you can use the to copy the contents of the buffer to the drawing surface on the screen. For more information on using the class, see [Manually Rendering Buffered Graphics](../../../../docs/framework/winforms/advanced/how-to-manually-render-buffered-graphics.md). For more information on rendering graphics, see [Graphics and Drawing in Windows Forms](../../../../docs/framework/winforms/advanced/graphics-and-drawing-in-windows-forms.md) diff --git a/docs/framework/winforms/advanced/ellipses-and-arcs-in-gdi.md b/docs/framework/winforms/advanced/ellipses-and-arcs-in-gdi.md index 5b6e57455eba1..2e3f08ec9eff7 100644 --- a/docs/framework/winforms/advanced/ellipses-and-arcs-in-gdi.md +++ b/docs/framework/winforms/advanced/ellipses-and-arcs-in-gdi.md @@ -53,8 +53,8 @@ You can easily draw ellipses and arcs using the - + + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [How to: Create Graphics Objects for Drawing](../../../../docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md) [How to: Create a Pen](../../../../docs/framework/winforms/advanced/how-to-create-a-pen.md) diff --git a/docs/framework/winforms/advanced/graphics-paths-in-gdi.md b/docs/framework/winforms/advanced/graphics-paths-in-gdi.md index a0859ef1027b8..be65b935c5a0b 100644 --- a/docs/framework/winforms/advanced/graphics-paths-in-gdi.md +++ b/docs/framework/winforms/advanced/graphics-paths-in-gdi.md @@ -72,8 +72,8 @@ Paths are formed by combining lines, rectangles, and simple curves. Recall from ![Paths](../../../../docs/framework/winforms/advanced/media/aboutgdip02-art16.gif "Aboutgdip02_Art16") ## See Also - - + + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [How to: Create Graphics Objects for Drawing](../../../../docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md) [Constructing and Drawing Paths](../../../../docs/framework/winforms/advanced/constructing-and-drawing-paths.md) diff --git a/docs/framework/winforms/advanced/how-to-arrange-mdi-child-forms.md b/docs/framework/winforms/advanced/how-to-arrange-mdi-child-forms.md index 442db3afc830e..2b192d860efac 100644 --- a/docs/framework/winforms/advanced/how-to-arrange-mdi-child-forms.md +++ b/docs/framework/winforms/advanced/how-to-arrange-mdi-child-forms.md @@ -29,7 +29,7 @@ Often, applications will have menu commands for actions such as Tile, Cascade, a ### To arrange child forms -1. In a method, use the method to set the enumeration for the MDI parent form. The following example uses the enumeration value for the child windows of the MDI parent form (`Form1`). The enumeration is used in code during the event handler for the event of the **Cascade Windows** menu item. +1. In a method, use the method to set the enumeration for the MDI parent form. The following example uses the enumeration value for the child windows of the MDI parent form (`Form1`). The enumeration is used in code during the event handler for the event of the **Cascade Windows** menu item. ```vb Protected Sub CascadeWindows_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) diff --git a/docs/framework/winforms/advanced/how-to-copy-pixels-for-reducing-flicker-in-windows-forms.md b/docs/framework/winforms/advanced/how-to-copy-pixels-for-reducing-flicker-in-windows-forms.md index 98d2637aca12f..ab7ed3b3c2f48 100644 --- a/docs/framework/winforms/advanced/how-to-copy-pixels-for-reducing-flicker-in-windows-forms.md +++ b/docs/framework/winforms/advanced/how-to-copy-pixels-for-reducing-flicker-in-windows-forms.md @@ -69,7 +69,7 @@ private void Form1_Paint(System.Object sender, ## See Also - - + + [Graphics and Drawing in Windows Forms](../../../../docs/framework/winforms/advanced/graphics-and-drawing-in-windows-forms.md) [Using a Pen to Draw Lines and Shapes](../../../../docs/framework/winforms/advanced/using-a-pen-to-draw-lines-and-shapes.md) diff --git a/docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md b/docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md index dabe248154207..446307bb9ed65 100644 --- a/docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md +++ b/docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md @@ -127,7 +127,7 @@ Before you can draw lines and shapes, render text, or display and manipulate ima #### To create a Graphics object from an Image -- Call the method, supplying the name of the Image variable from which you want to create a object. +- Call the method, supplying the name of the Image variable from which you want to create a object. The following example shows how to use a object: diff --git a/docs/framework/winforms/advanced/how-to-create-mdi-parent-forms.md b/docs/framework/winforms/advanced/how-to-create-mdi-parent-forms.md index 393379cd3d4e4..6abbad8a5d9c8 100644 --- a/docs/framework/winforms/advanced/how-to-create-mdi-parent-forms.md +++ b/docs/framework/winforms/advanced/how-to-create-mdi-parent-forms.md @@ -35,7 +35,7 @@ manager: "wpickett" This designates the form as an MDI container for child windows. > [!NOTE] - > While setting properties in the **Properties** window, you can also set the `WindowState` property to **Maximized**, if you like, as it is easiest to manipulate MDI child windows when the parent form is maximized. Additionally, be aware that the edge of the MDI parent form will pick up the system color (set in the Windows System Control Panel), rather than the back color you set using the property. + > While setting properties in the **Properties** window, you can also set the `WindowState` property to **Maximized**, if you like, as it is easiest to manipulate MDI child windows when the parent form is maximized. Additionally, be aware that the edge of the MDI parent form will pick up the system color (set in the Windows System Control Panel), rather than the back color you set using the property. 3. From the **Toolbox**, drag a **MenuStrip** control to the form. Create a top-level menu item with the **Text** property set to **&File** with submenu items called **&New** and **&Close**. Also create a top-level menu item called **&Window**. diff --git a/docs/framework/winforms/advanced/how-to-draw-a-line-with-line-caps.md b/docs/framework/winforms/advanced/how-to-draw-a-line-with-line-caps.md index 4b5e2ca67e96d..f295d573ddae6 100644 --- a/docs/framework/winforms/advanced/how-to-draw-a-line-with-line-caps.md +++ b/docs/framework/winforms/advanced/how-to-draw-a-line-with-line-caps.md @@ -40,7 +40,7 @@ You can draw the start or end of a line in one of several shapes called line cap - Create a Windows Form and handle the form's event. Paste the example code into the event handler passing `e` as . ## See Also - - + + [Graphics and Drawing in Windows Forms](../../../../docs/framework/winforms/advanced/graphics-and-drawing-in-windows-forms.md) [Using a Pen to Draw Lines and Shapes](../../../../docs/framework/winforms/advanced/using-a-pen-to-draw-lines-and-shapes.md) diff --git a/docs/framework/winforms/advanced/how-to-flatten-a-curved-path-into-a-line.md b/docs/framework/winforms/advanced/how-to-flatten-a-curved-path-into-a-line.md index 7b069451498c7..bdff24a4f5e82 100644 --- a/docs/framework/winforms/advanced/how-to-flatten-a-curved-path-into-a-line.md +++ b/docs/framework/winforms/advanced/how-to-flatten-a-curved-path-into-a-line.md @@ -34,6 +34,6 @@ A object stores a sequence of lines - call the method of a object. The method receives a flatness argument that specifies the maximum distance between the flattened path and the original path. ## See Also - + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [Constructing and Drawing Paths](../../../../docs/framework/winforms/advanced/constructing-and-drawing-paths.md) diff --git a/docs/framework/winforms/advanced/how-to-set-tab-stops-in-drawn-text.md b/docs/framework/winforms/advanced/how-to-set-tab-stops-in-drawn-text.md index b4f97ce443074..e6f87ea17ec6b 100644 --- a/docs/framework/winforms/advanced/how-to-set-tab-stops-in-drawn-text.md +++ b/docs/framework/winforms/advanced/how-to-set-tab-stops-in-drawn-text.md @@ -24,7 +24,7 @@ manager: "wpickett" You can set tab stops for text by calling the method of a object and then passing that object to the method of the class. > [!NOTE] -> The does not support adding tab stops to drawn text, although you can expand existing tab stops using the flag. +> The does not support adding tab stops to drawn text, although you can expand existing tab stops using the flag. ## Example The following example sets tab stops at 150, 250, and 350. Then, the code displays a tabbed list of names and test scores. diff --git a/docs/framework/winforms/advanced/how-to-support-com-interop-by-displaying-each-windows-form-on-its-own-thread.md b/docs/framework/winforms/advanced/how-to-support-com-interop-by-displaying-each-windows-form-on-its-own-thread.md index 43c9d8b0752a8..1a93fda1c6b68 100644 --- a/docs/framework/winforms/advanced/how-to-support-com-interop-by-displaying-each-windows-form-on-its-own-thread.md +++ b/docs/framework/winforms/advanced/how-to-support-com-interop-by-displaying-each-windows-form-on-its-own-thread.md @@ -24,11 +24,11 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Support COM Interop by Displaying Each Windows Form on Its Own Thread -You can resolve COM interoperability problems by displaying your form on a [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop, which you can create by using the method. +You can resolve COM interoperability problems by displaying your form on a [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop, which you can create by using the method. To make a Windows Form work correctly from a COM client application, you must run the form on a Windows Forms message loop. To do this, use one of the following approaches: -- Use the method to display the Windows Form. For more information, see [How to: Support COM Interop by Displaying a Windows Form with the ShowDialog Method](../../../../docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md). +- Use the method to display the Windows Form. For more information, see [How to: Support COM Interop by Displaying a Windows Form with the ShowDialog Method](../../../../docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md). - Display each Windows Form on a separate thread. @@ -37,7 +37,7 @@ You can resolve COM interoperability problems by displaying your form on a [!INC Also see [Walkthrough: Supporting COM Interop by Displaying Each Windows Form on Its Own Thread](http://msdn.microsoft.com/library/ms233639\(v=vs.110\)). ## Example - The following code example demonstrates how to display the form on a separate thread and call the method to start a Windows Forms message pump on that thread. To use this approach, you must marshal any calls to the form from the unmanaged application by using the method. + The following code example demonstrates how to display the form on a separate thread and call the method to start a Windows Forms message pump on that thread. To use this approach, you must marshal any calls to the form from the unmanaged application by using the method. This approach requires that each instance of a form runs on its own thread by using its own message loop. You cannot have more than one message loop running per thread. Therefore, you cannot change the client application's message loop. However, you can modify the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] component to start a new thread that uses its own message loop. diff --git a/docs/framework/winforms/advanced/how-to-use-compositing-mode-to-control-alpha-blending.md b/docs/framework/winforms/advanced/how-to-use-compositing-mode-to-control-alpha-blending.md index df931a642c756..1bec78b715988 100644 --- a/docs/framework/winforms/advanced/how-to-use-compositing-mode-to-control-alpha-blending.md +++ b/docs/framework/winforms/advanced/how-to-use-compositing-mode-to-control-alpha-blending.md @@ -30,7 +30,7 @@ There may be times when you want to create an off-screen bitmap that has the fol - When you display the finished bitmap, colors in the bitmap are alpha blended with the background colors on the display device. - To create such a bitmap, construct a blank object, and then construct a object based on that bitmap. Set the compositing mode of the object to . + To create such a bitmap, construct a blank object, and then construct a object based on that bitmap. Set the compositing mode of the object to . ## Example The following example creates a object based on a object. The code uses the object along with two semitransparent brushes (alpha = 160) to paint on the bitmap. The code fills a red ellipse and a green ellipse using the semitransparent brushes. The green ellipse overlaps the red ellipse, but the green is not blended with the red because the compositing mode of the object is set to . diff --git a/docs/framework/winforms/advanced/open-and-closed-curves-in-gdi.md b/docs/framework/winforms/advanced/open-and-closed-curves-in-gdi.md index 872f8e5b95646..371b9cb3a3cdf 100644 --- a/docs/framework/winforms/advanced/open-and-closed-curves-in-gdi.md +++ b/docs/framework/winforms/advanced/open-and-closed-curves-in-gdi.md @@ -54,9 +54,9 @@ The following illustration shows two curves: one open and one closed. ![String in a path](../../../../docs/framework/winforms/advanced/media/aboutgdip02-art26.gif "Aboutgdip02_art26") ## See Also - - - + + + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [How to: Create Graphics Objects for Drawing](../../../../docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md) [Constructing and Drawing Paths](../../../../docs/framework/winforms/advanced/constructing-and-drawing-paths.md) diff --git a/docs/framework/winforms/advanced/pens-lines-and-rectangles-in-gdi.md b/docs/framework/winforms/advanced/pens-lines-and-rectangles-in-gdi.md index dbd5c064d1082..d74b030364288 100644 --- a/docs/framework/winforms/advanced/pens-lines-and-rectangles-in-gdi.md +++ b/docs/framework/winforms/advanced/pens-lines-and-rectangles-in-gdi.md @@ -73,9 +73,9 @@ To draw lines with [!INCLUDE[ndptecgdiplus](../../../../includes/ndptecgdiplus-m A object has methods and properties for manipulating and gathering information about the rectangle. For example, the and methods change the size and position of the rectangle. The method tells you whether the rectangle intersects another given rectangle, and the method tells you whether a given point is inside the rectangle. ## See Also - - - + + + [How to: Create a Pen](../../../../docs/framework/winforms/advanced/how-to-create-a-pen.md) [How to: Draw a Line on a Windows Form](../../../../docs/framework/winforms/advanced/how-to-draw-a-line-on-a-windows-form.md) [How to: Draw an Outlined Shape](../../../../docs/framework/winforms/advanced/how-to-draw-an-outlined-shape.md) diff --git a/docs/framework/winforms/advanced/polygons-in-gdi.md b/docs/framework/winforms/advanced/polygons-in-gdi.md index 9308a4f3112c1..750d0c517b973 100644 --- a/docs/framework/winforms/advanced/polygons-in-gdi.md +++ b/docs/framework/winforms/advanced/polygons-in-gdi.md @@ -37,7 +37,7 @@ A polygon is a closed shape with three or more straight sides. For example, a tr ![Polygon](../../../../docs/framework/winforms/advanced/media/aboutgdip02-art08.gif "Aboutgdip02_art08") ## See Also - - + + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [How to: Create a Pen](../../../../docs/framework/winforms/advanced/how-to-create-a-pen.md) diff --git a/docs/framework/winforms/advanced/regions-in-gdi.md b/docs/framework/winforms/advanced/regions-in-gdi.md index 4de82cd55c436..cfa84fbc5e026 100644 --- a/docs/framework/winforms/advanced/regions-in-gdi.md +++ b/docs/framework/winforms/advanced/regions-in-gdi.md @@ -45,6 +45,6 @@ A region is a portion of the display area of an output device. Regions can be si [!code-vb[LinesCurvesAndShapes#61](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/LinesCurvesAndShapes/VB/Class1.vb#61)] ## See Also - + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [Using Regions](../../../../docs/framework/winforms/advanced/using-regions.md) diff --git a/docs/framework/winforms/advanced/restricting-the-drawing-surface-in-gdi.md b/docs/framework/winforms/advanced/restricting-the-drawing-surface-in-gdi.md index 96f35e9e2eaac..e613667a528e7 100644 --- a/docs/framework/winforms/advanced/restricting-the-drawing-surface-in-gdi.md +++ b/docs/framework/winforms/advanced/restricting-the-drawing-surface-in-gdi.md @@ -37,7 +37,7 @@ Clipping involves restricting drawing to a certain rectangle or region. The foll [!code-vb[LinesCurvesAndShapes#91](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/LinesCurvesAndShapes/VB/Class1.vb#91)] ## See Also - - + + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [Using Regions](../../../../docs/framework/winforms/advanced/using-regions.md) diff --git a/docs/framework/winforms/advanced/types-of-bitmaps.md b/docs/framework/winforms/advanced/types-of-bitmaps.md index 5f98e0c4b25fc..fd0ec37810270 100644 --- a/docs/framework/winforms/advanced/types-of-bitmaps.md +++ b/docs/framework/winforms/advanced/types-of-bitmaps.md @@ -94,8 +94,8 @@ A bitmap is an array of bits that specify the color of each pixel in a rectangul TIFF is a flexible and extendable format that is supported by a wide variety of platforms and image-processing applications. TIFF files can store images with an arbitrary number of bits per pixel and can employ a variety of compression algorithms. Several images can be stored in a single, multiple-page TIFF file. Information related to the image (scanner make, host computer, type of compression, orientation, samples per pixel, and so on) can be stored in the file and arranged through the use of tags. The TIFF format can be extended as needed by the approval and addition of new tags. ## See Also - - - + + + [Images, Bitmaps, and Metafiles](../../../../docs/framework/winforms/advanced/images-bitmaps-and-metafiles.md) [Working with Images, Bitmaps, Icons, and Metafiles](../../../../docs/framework/winforms/advanced/working-with-images-bitmaps-icons-and-metafiles.md) diff --git a/docs/framework/winforms/advanced/using-a-brush-to-fill-shapes.md b/docs/framework/winforms/advanced/using-a-brush-to-fill-shapes.md index 503ed6b7a854b..6a7402d3dd11a 100644 --- a/docs/framework/winforms/advanced/using-a-brush-to-fill-shapes.md +++ b/docs/framework/winforms/advanced/using-a-brush-to-fill-shapes.md @@ -38,19 +38,19 @@ A [!INCLUDE[ndptecgdiplus](../../../../includes/ndptecgdiplus-md.md)] + Describes this class and contains links to all of its members - + Describes this class and contains links to all of its members - + Describes this class and contains links to all of its members. - + Describes this class and contains links to all of its members. - + Describes this class and contains links to all of its members. ## Related Sections diff --git a/docs/framework/winforms/advanced/using-a-gradient-brush-to-fill-shapes.md b/docs/framework/winforms/advanced/using-a-gradient-brush-to-fill-shapes.md index ca47eaa06287d..be2830660491f 100644 --- a/docs/framework/winforms/advanced/using-a-gradient-brush-to-fill-shapes.md +++ b/docs/framework/winforms/advanced/using-a-gradient-brush-to-fill-shapes.md @@ -41,8 +41,8 @@ You can use a gradient brush to fill a shape with a gradually changing color. Fo Explains how to use gamma correction with a gradient brush. ## Reference - + Contains a description of this class and has links to all of its members. - + Contains a description of this class and has links to all of its members. diff --git a/docs/framework/winforms/advanced/vector-graphics-overview.md b/docs/framework/winforms/advanced/vector-graphics-overview.md index 09c856527d601..a120f9fd5fc39 100644 --- a/docs/framework/winforms/advanced/vector-graphics-overview.md +++ b/docs/framework/winforms/advanced/vector-graphics-overview.md @@ -62,7 +62,7 @@ manager: "wpickett" [!code-vb[LinesCurvesAndShapes#11](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/LinesCurvesAndShapes/VB/Class1.vb#11)] ## See Also - - + + [Lines, Curves, and Shapes](../../../../docs/framework/winforms/advanced/lines-curves-and-shapes.md) [How to: Create Graphics Objects for Drawing](../../../../docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md) diff --git a/docs/framework/winforms/advanced/walkthrough-assigning-wpf-content-on-windows-forms-at-design-time.md b/docs/framework/winforms/advanced/walkthrough-assigning-wpf-content-on-windows-forms-at-design-time.md index 372ca70cb761b..3ca26d8aff320 100644 --- a/docs/framework/winforms/advanced/walkthrough-assigning-wpf-content-on-windows-forms-at-design-time.md +++ b/docs/framework/winforms/advanced/walkthrough-assigning-wpf-content-on-windows-forms-at-design-time.md @@ -63,15 +63,15 @@ This walkthrough show you how to select the Windows Presentation Foundation (WPF 3. In the **Properties** window, set the value of the and properties to `200`. -4. Add a control to the and set the value of the property to **Hosted Content**. +4. Add a control to the and set the value of the property to **Hosted Content**. 5. Add a second WPF to the project. Use the default name for the control type, `UserControl2.xaml`. 6. In the **Properties** window, set the value of the and properties to `200`. -7. Add a control to the and set the value of the property to **Hosted Content 2**. +7. Add a control to the and set the value of the property to **Hosted Content 2**. - **Note** In general, you should host more sophisticated WPF content. The control is used here for illustrative purposes only. + **Note** In general, you should host more sophisticated WPF content. The control is used here for illustrative purposes only. 1. Build the project. diff --git a/docs/framework/winforms/advanced/walkthrough-creating-new-wpf-content-on-windows-forms-at-design-time.md b/docs/framework/winforms/advanced/walkthrough-creating-new-wpf-content-on-windows-forms-at-design-time.md index e0d6ad3a3be03..2861c35b449d4 100644 --- a/docs/framework/winforms/advanced/walkthrough-creating-new-wpf-content-on-windows-forms-at-design-time.md +++ b/docs/framework/winforms/advanced/walkthrough-creating-new-wpf-content-on-windows-forms-at-design-time.md @@ -56,7 +56,7 @@ This topic shows you how to create a Windows Presentation Foundation (WPF) contr Creating a new WPF control and adding it to your project is as easy as adding any other item to your project. The Windows Forms Designer works with a particular kind of control named *composite control*, or *user control*. For more information about WPF user controls, see . > [!NOTE] -> The type for WPF is distinct from the user control type provided by Windows Forms, which is also named . +> The type for WPF is distinct from the user control type provided by Windows Forms, which is also named . #### To create a new WPF control @@ -76,12 +76,12 @@ This topic shows you how to create a Windows Presentation Foundation (WPF) contr 3. In the **Properties** window, set the value of the and properties to `200`. -4. From the **Toolbox**, drag a control onto the design surface. +4. From the **Toolbox**, drag a control onto the design surface. 5. In the **Properties** window, set the value of the property to **Hosted Content**. > [!NOTE] - > In general, you should host more sophisticated WPF content. The control is used here for illustrative purposes only. + > In general, you should host more sophisticated WPF content. The control is used here for illustrative purposes only. 6. Build the project. diff --git a/docs/framework/winforms/advanced/walkthrough-styling-wpf-content.md b/docs/framework/winforms/advanced/walkthrough-styling-wpf-content.md index 27ab873d47379..7b0b055ad8dbd 100644 --- a/docs/framework/winforms/advanced/walkthrough-styling-wpf-content.md +++ b/docs/framework/winforms/advanced/walkthrough-styling-wpf-content.md @@ -61,9 +61,9 @@ This walkthrough show you how to apply styling to a Windows Presentation Foundat 3. In the **Properties** window, set the value of the and properties to `200`. -4. Add a control to the and set the value of the property to **Cancel**. +4. Add a control to the and set the value of the property to **Cancel**. -5. Add a second control to the and set the value of the property to **OK**. +5. Add a second control to the and set the value of the property to **OK**. 6. Build the project. diff --git a/docs/framework/winforms/advanced/windows-forms-and-unmanaged-applications-overview.md b/docs/framework/winforms/advanced/windows-forms-and-unmanaged-applications-overview.md index 8ba254f1cbc62..fc5da7e251a73 100644 --- a/docs/framework/winforms/advanced/windows-forms-and-unmanaged-applications-overview.md +++ b/docs/framework/winforms/advanced/windows-forms-and-unmanaged-applications-overview.md @@ -55,11 +55,11 @@ Windows Forms applications and controls can interoperate with unmanaged applicat An application's message loop is an internal program loop that retrieves messages from a thread's message queue, translates them, and then sends them to the application to be handled. The message loop for a Windows Form does not have the same architecture as message loops that earlier applications, such as Visual Basic 6.0 applications and MFC applications, provide. The window messages that are posted to the message loop may be handled differently than the Windows Form expects. Therefore, unexpected behavior may occur. Some keystroke combinations may not work, some mouse activity may not work, or some events may not be raised as expected. ## Resolving Interoperability Issues - You can resolve these problems by displaying the form on a [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop, which is created by using the method. + You can resolve these problems by displaying the form on a [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] message loop, which is created by using the method. To make a Windows Form work correctly from a COM client application, you must run it on a Windows Forms message loop. To do this, use one of the following approaches: -- Use the method to display the Windows Form. For more information, see [How to: Support COM Interop by Displaying a Windows Form with the ShowDialog Method](../../../../docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md). +- Use the method to display the Windows Form. For more information, see [How to: Support COM Interop by Displaying a Windows Form with the ShowDialog Method](../../../../docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md). - Display each Windows Form on a new thread. For more information, see [How to: Support COM Interop by Displaying Each Windows Form on Its Own Thread](../../../../docs/framework/winforms/advanced/how-to-support-com-interop-by-displaying-each-windows-form-on-its-own-thread.md). diff --git a/docs/framework/winforms/advanced/windows-forms-and-unmanaged-applications.md b/docs/framework/winforms/advanced/windows-forms-and-unmanaged-applications.md index fd2c275b5893a..ad89377831c02 100644 --- a/docs/framework/winforms/advanced/windows-forms-and-unmanaged-applications.md +++ b/docs/framework/winforms/advanced/windows-forms-and-unmanaged-applications.md @@ -31,7 +31,7 @@ Windows Forms applications and controls can interoperate with unmanaged applicat Offers general information about how to use and implement Windows Forms controls that work with unmanaged applications. [How to: Support COM Interop by Displaying a Windows Form with the ShowDialog Method](../../../../docs/framework/winforms/advanced/com-interop-by-displaying-a-windows-form-shadow.md) - Provides a code example that shows how to use the method to run a Windows Form in an unmanaged application. + Provides a code example that shows how to use the method to run a Windows Form in an unmanaged application. [How to: Support COM Interop by Displaying Each Windows Form on Its Own Thread](../../../../docs/framework/winforms/advanced/how-to-support-com-interop-by-displaying-each-windows-form-on-its-own-thread.md) Provides a code example that shows how to run a Windows Form on its own thread. @@ -39,10 +39,10 @@ Windows Forms applications and controls can interoperate with unmanaged applicat Also see [Walkthrough: Supporting COM Interop by Displaying Each Windows Form on Its Own Thread](http://msdn.microsoft.com/library/ms233639\(v=vs.110\)). ## Reference - + Used to create a separate thread for a Windows Form. - + Starts a message loop for a thread. diff --git a/docs/framework/winforms/controls/access-objects-in-a-wf-datagridviewcomboboxcell-drop-down-list.md b/docs/framework/winforms/controls/access-objects-in-a-wf-datagridviewcomboboxcell-drop-down-list.md index 6d498d0ca54e8..8f55e67a8d736 100644 --- a/docs/framework/winforms/controls/access-objects-in-a-wf-datagridviewcomboboxcell-drop-down-list.md +++ b/docs/framework/winforms/controls/access-objects-in-a-wf-datagridviewcomboboxcell-drop-down-list.md @@ -24,7 +24,7 @@ manager: "wpickett" # How to: Access Objects in a Windows Forms DataGridViewComboBoxCell Drop-Down List Like the control, the and types enable you to add arbitrary objects to their drop-down lists. With this feature, you can represent complex states in a drop-down list without having to store corresponding objects in a separate collection. - Unlike the control, the types do not have a property for retrieving the currently selected object. Instead, you must set the or property to the name of a property on your business object. When the user makes a selection, the indicated property of the business object sets the cell property. + Unlike the control, the types do not have a property for retrieving the currently selected object. Instead, you must set the or property to the name of a property on your business object. When the user makes a selection, the indicated property of the business object sets the cell property. To retrieve the business object through the cell value, the `ValueMember` property must indicate a property that returns a reference to the business object itself. Therefore, if the type of the business object is not under your control, you must add such a property by extending the type through inheritance. @@ -76,13 +76,13 @@ Like the control, the - - - + + + - - - - + + + + [Displaying Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/add-tooltips-to-individual-cells-in-a-wf-datagridview-control.md b/docs/framework/winforms/controls/add-tooltips-to-individual-cells-in-a-wf-datagridview-control.md index b0dc53c193891..2d591abc3bc80 100644 --- a/docs/framework/winforms/controls/add-tooltips-to-individual-cells-in-a-wf-datagridview-control.md +++ b/docs/framework/winforms/controls/add-tooltips-to-individual-cells-in-a-wf-datagridview-control.md @@ -24,11 +24,11 @@ manager: "wpickett" # How to: Add ToolTips to Individual Cells in a Windows Forms DataGridView Control By default, ToolTips are used to display the values of cells that are too small to show their entire contents. You can override this behavior, however, to set ToolTip-text values for individual cells. This is useful to display to users additional information about a cell or to provide to users an alternate description of the cell contents. For example, if you have a row that displays status icons, you may want to provide text explanations using ToolTips. - You can also disable the display of cell-level ToolTips by setting the property to `false`. + You can also disable the display of cell-level ToolTips by setting the property to `false`. ### To add a ToolTip to a cell -- Set the property. +- Set the property. [!code-cpp[System.Windows.Forms.DataGridViewCell.ToolTipText#1](../../../../samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewCell.ToolTipText/cpp/datagridviewcell.tooltiptext.cpp#1)] [!code-csharp[System.Windows.Forms.DataGridViewCell.ToolTipText#1](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewCell.ToolTipText/CS/datagridviewcell.tooltiptext.cs#1)] @@ -40,15 +40,15 @@ By default, ToolTips are used to display the values of control named `dataGridView1` that contains a column named `Rating` for displaying string values of one through four asterisk ("*") symbols. The event of the control must be associated with the event handler method shown in the example. -- References to the and assemblies. +- References to the and assemblies. ## Robust Programming - When you bind the control to an external data source or provide your own data source by implementing virtual mode, you might encounter performance issues. To avoid a performance penalty when working with large amounts of data, handle the event rather than setting the property of multiple cells. When you handle this event, getting the value of a cell property raises the event and returns the value of the property as specified in the event handler. + When you bind the control to an external data source or provide your own data source by implementing virtual mode, you might encounter performance issues. To avoid a performance penalty when working with large amounts of data, handle the event rather than setting the property of multiple cells. When you handle this event, getting the value of a cell property raises the event and returns the value of the property as specified in the event handler. ## See Also - - + + - + [Programming with Cells, Rows, and Columns in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/programming-with-cells-rows-and-columns-in-the-datagrid.md) diff --git a/docs/framework/winforms/controls/autogenerate-columns-in-a-data-bound-wf-datagridview-control.md b/docs/framework/winforms/controls/autogenerate-columns-in-a-data-bound-wf-datagridview-control.md index 7b3fac7ae539e..a8ad497d860eb 100644 --- a/docs/framework/winforms/controls/autogenerate-columns-in-a-data-bound-wf-datagridview-control.md +++ b/docs/framework/winforms/controls/autogenerate-columns-in-a-data-bound-wf-datagridview-control.md @@ -37,10 +37,10 @@ The following code example demonstrates how to display columns from a bound data - A object named `customersDataSet` that has a table named `Customers`. -- References to the , , , and assemblies. +- References to the , , , and assemblies. ## See Also - + [Displaying Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md) [How to: Remove Autogenerated Columns from a Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/remove-autogenerated-columns-from-a-wf-datagridview-control.md) diff --git a/docs/framework/winforms/controls/automatically-resize-cells-when-content-changes-in-the-datagrid.md b/docs/framework/winforms/controls/automatically-resize-cells-when-content-changes-in-the-datagrid.md index 7f8360c763040..a7c24e2594a9d 100644 --- a/docs/framework/winforms/controls/automatically-resize-cells-when-content-changes-in-the-datagrid.md +++ b/docs/framework/winforms/controls/automatically-resize-cells-when-content-changes-in-the-datagrid.md @@ -44,12 +44,12 @@ You can configure the control to resize ## See Also - - - - - - + + + + + + diff --git a/docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md index d6c747467f80e..6567d823374c7 100644 --- a/docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md @@ -44,11 +44,11 @@ The control is designed to provide maxi ## Using Cell Styles Efficiently Each cell, row, and column can have its own style information. Style information is stored in objects. Creating cell style objects for many individual elements can be inefficient, especially when working with large amounts of data. To avoid a performance impact, use the following guidelines: -- Avoid setting cell style properties for individual or objects. This includes the row object specified by the property. Each new row that is cloned from the row template will receive its own copy of the template's cell style object. For maximum scalability, set cell style properties at the level. For example, set the property rather than the property. +- Avoid setting cell style properties for individual or objects. This includes the row object specified by the property. Each new row that is cloned from the row template will receive its own copy of the template's cell style object. For maximum scalability, set cell style properties at the level. For example, set the property rather than the property. - If some cells require formatting other than default formatting, use the same instance across groups of cells, rows, or columns. Avoid directly setting properties of type on individual cells, rows, and columns. For an example of cell style sharing, see [How to: Set Default Cell Styles for the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-set-default-cell-styles-for-the-windows-forms-datagridview-control.md). You can also avoid a performance penalty when setting cell styles individually by handling the event handler. For an example, see [How to: Customize Data Formatting in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-customize-data-formatting-in-the-windows-forms-datagridview-control.md). -- When determining a cell's style, use the property rather than the property. Accessing the property creates a new instance of the class if the property has not already been used. Additionally, this object might not contain the complete style information for the cell if some styles are inherited from the row, column, or control. For more information about cell style inheritance, see [Cell Styles in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md). +- When determining a cell's style, use the property rather than the property. Accessing the property creates a new instance of the class if the property has not already been used. Additionally, this object might not contain the complete style information for the cell if some styles are inherited from the row, column, or control. For more information about cell style inheritance, see [Cell Styles in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md). ## Using Shortcut Menus Efficiently Each cell, row, and column can have its own shortcut menu. Shortcut menus in the control are represented by controls. Just as with cell style objects, creating shortcut menus for many individual elements will negatively impact performance. To avoid this penalty, use the following guidelines: @@ -75,9 +75,9 @@ The control is designed to provide maxi - To determine whether all the cells in the have been selected before you access the contents of the collection, check the return value of the method. Note, however, that this method can cause rows to become unshared. For more information, see the next section. -- Avoid using the property of the to determine the number of selected cells. Instead, use the method and pass in the value. Similarly, use the and methods to determine the number of selected elements, rather than accessing the selected row and column collections. +- Avoid using the property of the to determine the number of selected cells. Instead, use the method and pass in the value. Similarly, use the and methods to determine the number of selected elements, rather than accessing the selected row and column collections. -- Avoid cell-based selection modes. Instead, set the property to or . +- Avoid cell-based selection modes. Instead, set the property to or . ## Using Shared Rows Efficient memory use is achieved in the control through shared rows. Rows will share as much information about their appearance and behavior as possible by sharing instances of the class. @@ -100,21 +100,21 @@ The control is designed to provide maxi The control will automatically attempt to use shared rows whenever rows are added to the . Use the following guidelines to ensure that rows are shared: -- Avoid calling the `Add(Object[])` overload of the method and the `Insert(Object[])` overload of the method of the collection. These overloads automatically create unshared rows. +- Avoid calling the `Add(Object[])` overload of the method and the `Insert(Object[])` overload of the method of the collection. These overloads automatically create unshared rows. -- Be sure that the row specified in the property can be shared in the following cases: +- Be sure that the row specified in the property can be shared in the following cases: - - When calling the `Add()` or `Add(Int32)` overloads of the method or the `Insert(Int32,Int32)` overload of the method of the collection. + - When calling the `Add()` or `Add(Int32)` overloads of the method or the `Insert(Int32,Int32)` overload of the method of the collection. - - When increasing the value of the property. + - When increasing the value of the property. - - When setting the property. + - When setting the property. -- Be sure that the row indicated by the `indexSource` parameter can be shared when calling the , , , and methods of the collection. +- Be sure that the row indicated by the `indexSource` parameter can be shared when calling the , , , and methods of the collection. -- Be sure that the specified row or rows can be shared when calling the `Add(DataGridViewRow)` overload of the method, the method, the `Insert(Int32,DataGridViewRow)` overload of the method, and the method of the collection. +- Be sure that the specified row or rows can be shared when calling the `Add(DataGridViewRow)` overload of the method, the method, the `Insert(Int32,DataGridViewRow)` overload of the method, and the method of the collection. - To determine whether a row is shared, use the method to retrieve the row object, and then check the object's property. Shared rows always have an property value of –1. + To determine whether a row is shared, use the method to retrieve the row object, and then check the object's property. Shared rows always have an property value of –1. ## Preventing Rows from Becoming Unshared Shared rows can become unshared as a result of code or user action. To avoid a performance impact, you should avoid causing rows to become unshared. During application development, you can handle the event to determine when rows become unshared. This is useful when debugging row-sharing problems. @@ -123,23 +123,23 @@ The control is designed to provide maxi - Avoid indexing the collection or iterating through it with a `foreach` loop. You will not typically need to access rows directly. methods that operate on rows take row index arguments rather than row instances. Additionally, handlers for row-related events receive event argument objects with row properties that you can use to manipulate rows without causing them to become unshared. -- If you need to access a row object, use the method and pass in the row's actual index. Note, however, that modifying a shared row object retrieved through this method will modify all the rows that share this object. The row for new records is not shared with other rows, however, so it will not be affected when you modify any other row. Note also that different rows represented by a shared row may have different shortcut menus. To retrieve the correct shortcut menu from a shared row instance, use the method and pass in the row's actual index. If you access the shared row's property instead, it will use the shared row index of -1 and will not retrieve the correct shortcut menu. +- If you need to access a row object, use the method and pass in the row's actual index. Note, however, that modifying a shared row object retrieved through this method will modify all the rows that share this object. The row for new records is not shared with other rows, however, so it will not be affected when you modify any other row. Note also that different rows represented by a shared row may have different shortcut menus. To retrieve the correct shortcut menu from a shared row instance, use the method and pass in the row's actual index. If you access the shared row's property instead, it will use the shared row index of -1 and will not retrieve the correct shortcut menu. -- Avoid indexing the collection. Accessing a cell directly will cause its parent row to become unshared, instantiating a new . Handlers for cell-related events receive event argument objects with cell properties that you can use to manipulate cells without causing rows to become unshared. You can also use the property to retrieve the row and column indexes of the current cell without accessing the cell directly. +- Avoid indexing the collection. Accessing a cell directly will cause its parent row to become unshared, instantiating a new . Handlers for cell-related events receive event argument objects with cell properties that you can use to manipulate cells without causing rows to become unshared. You can also use the property to retrieve the row and column indexes of the current cell without accessing the cell directly. -- Avoid cell-based selection modes. These modes cause rows to become unshared. Instead, set the property to or . +- Avoid cell-based selection modes. These modes cause rows to become unshared. Instead, set the property to or . -- Do not handle the or events. These events cause rows to become unshared. Also, do not call the or methods, which raise these events. +- Do not handle the or events. These events cause rows to become unshared. Also, do not call the or methods, which raise these events. -- Do not access the collection when the property value is , , , or . This causes all selected rows to become unshared. +- Do not access the collection when the property value is , , , or . This causes all selected rows to become unshared. -- Do not call the method. This method can cause rows to become unshared. +- Do not call the method. This method can cause rows to become unshared. -- Do not call the method when the property value is . This causes all rows to become unshared. +- Do not call the method when the property value is . This causes all rows to become unshared. - Do not set the or property of a cell to `false` when the corresponding property in its column is set to `true`. This causes all rows to become unshared. -- Do not access the property. This causes all rows to become unshared. +- Do not access the property. This causes all rows to become unshared. - Do not call the `Sort(IComparer)` overload of the method. Sorting with a custom comparer causes all rows to become unshared. diff --git a/docs/framework/winforms/controls/bind-data-to-the-datagrid-using-the-designer.md b/docs/framework/winforms/controls/bind-data-to-the-datagrid-using-the-designer.md index b28406e72b51c..ef81e26dc2f36 100644 --- a/docs/framework/winforms/controls/bind-data-to-the-datagrid-using-the-designer.md +++ b/docs/framework/winforms/controls/bind-data-to-the-datagrid-using-the-designer.md @@ -45,7 +45,7 @@ You can use the designer to connect a c 4. Expand the **Other Data Sources** and **Project Data Sources** nodes if they are not already expanded, and then select the data source to bind the control to. -5. If your data source contains more than one member, such as if you have created a that contains multiple tables, expand the data source, and then select the specific member to bind to. +5. If your data source contains more than one member, such as if you have created a that contains multiple tables, expand the data source, and then select the specific member to bind to. 6. To create a master/detail relationship, in the **Choose Data Source** drop-down window for a second control, expand the created for the parent table, and then select the related child table from the list shown. @@ -55,8 +55,8 @@ You can use the designer to connect a c ## See Also - - + + [How to: Connect to Data in a Database](http://msdn.microsoft.com/library/6c56e54e-8834-4297-85aa-cc1a443ba556) [How to: Add and Remove Columns in the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/add-and-remove-columns-in-the-datagrid-using-the-designer.md) [How to: Change the Order of Columns in the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/change-the-order-of-columns-in-the-datagrid-using-the-designer.md) diff --git a/docs/framework/winforms/controls/bindingsource-component-architecture.md b/docs/framework/winforms/controls/bindingsource-component-architecture.md index ac377fa39a2ea..a087679121a78 100644 --- a/docs/framework/winforms/controls/bindingsource-component-architecture.md +++ b/docs/framework/winforms/controls/bindingsource-component-architecture.md @@ -33,7 +33,7 @@ With the component, you can universall - Simplifies creating a list that supports the interface by providing list change notification for data sources that do not natively support list change notification. -- Provides an extensibility point for the method. +- Provides an extensibility point for the method. - Provides a level of indirection between the data source and the control. This indirection is important when the data source may change at run time. @@ -143,7 +143,7 @@ With the component, you can universall - The method will roll back the pending addition if the method has not already been committed. ### IEnumerable Support - The component enables binding controls to data sources. With this component, you can bind to a data source such as a . + The component enables binding controls to data sources. With this component, you can bind to a data source such as a . When an data source is assigned to the component, the creates an and adds the contents of the data source to the list. @@ -153,7 +153,7 @@ With the component, you can universall To support this scenario, the component supports binding to a . When you assign a to the property, the component creates an empty of items. Any controls you subsequently bind to the component will be alerted to the presence of the properties or schema of your type at design time, or at run time. For more information, see [How to: Bind a Windows Forms Control to a Type](../../../../docs/framework/winforms/controls/how-to-bind-a-windows-forms-control-to-a-type.md). ### Static ListBindingHelper Methods - The , , and types all share common logic to generate a list from a `DataSource`/`DataMember` pair. Additionally, this common logic is publicly exposed for use by control authors and other third parties in the following `static` methods: + The , , and types all share common logic to generate a list from a `DataSource`/`DataMember` pair. Additionally, this common logic is publicly exposed for use by control authors and other third parties in the following `static` methods: - diff --git a/docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md index a1405c5cc6e9c..ee138150daaa4 100644 --- a/docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md @@ -73,25 +73,25 @@ Each cell within the control can have i ## Style Inheritance Each gets its appearance from its property. The object returned by this property inherits its values from a hierarchy of properties of type . These properties are listed below in the order in which the for non-header cells obtains its values. -1. +1. -2. +2. -3. (only for cells in rows with odd index numbers) +3. (only for cells in rows with odd index numbers) -4. +4. -5. +5. -6. +6. For row and column header cells, the property is populated by values from the following list of source properties in the given order. -1. +1. -2. or +2. or -3. +3. The following diagram illustrates this process. @@ -99,19 +99,19 @@ Each cell within the control can have i You can also access the styles inherited by specific rows and columns. The column property inherits its values from the following properties. -1. +1. -2. +2. The row property inherits its values from the following properties. -1. +1. -2. (only for cells in rows with odd index numbers) +2. (only for cells in rows with odd index numbers) -3. +3. -4. +4. For each property in a object returned by an `InheritedStyle` property, the property value is obtained from the first cell style in the appropriate list that has the corresponding property set to a value other than the class defaults. @@ -119,14 +119,14 @@ Each cell within the control can have i |Property of type `DataGridViewCellStyle`|Example `ForeColor` value for retrieved object| |----------------------------------------------|----------------------------------------------------| -||| -||| -||| -||| -||| -||| +||| +||| +||| +||| +||| +||| - In this case, the value from the cell's row is the first real value on the list. This becomes the property value of the cell's . + In this case, the value from the cell's row is the first real value on the list. This becomes the property value of the cell's . The following diagram illustrates how different properties can inherit their values from different places. @@ -142,12 +142,12 @@ Each cell within the control can have i The , , and types also initialize some values of the object returned by the column property. For more information, see the reference documentation for these types. ## Setting Styles Dynamically - To customize the styles of cells with particular values, implement a handler for the event. Handlers for this event receive an argument of the type. This object contains properties that let you determine the value of the cell being formatted along with its location in the control. This object also contains a property that is initialized to the value of the property of the cell being formatted. You can modify the cell style properties to specify style information appropriate to the cell value and location. + To customize the styles of cells with particular values, implement a handler for the event. Handlers for this event receive an argument of the type. This object contains properties that let you determine the value of the cell being formatted along with its location in the control. This object also contains a property that is initialized to the value of the property of the cell being formatted. You can modify the cell style properties to specify style information appropriate to the cell value and location. > [!NOTE] > The and events also receive a object in the event data, but in their case, it is a copy of the row property for read-only purposes, and changes to it do not affect the control. - You can also dynamically modify the styles of individual cells in response to events such as the and events. For example, in a handler for the event, you could store the current value of the cell background color (retrieved through the cell's property), then set it to a new color that will highlight the cell when the mouse hovers over it. In a handler for the event, you can then restore the background color to the original value. + You can also dynamically modify the styles of individual cells in response to events such as the and events. For example, in a handler for the event, you could store the current value of the cell background color (retrieved through the cell's property), then set it to a new color that will highlight the cell when the mouse hovers over it. In a handler for the event, you can then restore the background color to the original value. > [!NOTE] > Caching the values stored in the cell's property is important regardless of whether a particular style value is set. If you temporarily replace a style setting, restoring it to its original "not set" state ensures that the cell will go back to inheriting the style setting from a higher level. If you need to determine the actual style in effect for a cell regardless of whether the style is inherited, use the cell's property. @@ -155,21 +155,21 @@ Each cell within the control can have i ## See Also - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + [Basic Formatting and Styling in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-formatting-and-styling-in-the-windows-forms-datagridview-control.md) [How to: Set Default Cell Styles for the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-set-default-cell-styles-for-the-windows-forms-datagridview-control.md) [Data Formatting in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/data-formatting-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/change-the-border-and-gridline-styles-in-the-datagrid.md b/docs/framework/winforms/controls/change-the-border-and-gridline-styles-in-the-datagrid.md index 4cc351d5b19fa..9b50761880ada 100644 --- a/docs/framework/winforms/controls/change-the-border-and-gridline-styles-in-the-datagrid.md +++ b/docs/framework/winforms/controls/change-the-border-and-gridline-styles-in-the-datagrid.md @@ -27,7 +27,7 @@ manager: "wpickett" With the control, you can customize the appearance of the control's border and gridlines to improve the user experience. You can modify the gridline color and the control border style in addition to the border styles for the cells within the control. You can also apply different cell border styles for ordinary cells, row header cells, and column header cells. > [!NOTE] -> The gridline color is used only with the , , and values of the enumeration and the value of the enumeration. The other values of these enumerations use colors specified by the operating system. Additionally, when visual styles are enabled on Windows XP and the Windows Server 2003 family through the method, the property value is not used. +> The gridline color is used only with the , , and values of the enumeration and the value of the enumeration. The other values of these enumerations use colors specified by the operating system. Additionally, when visual styles are enabled on Windows XP and the Windows Server 2003 family through the method, the property value is not used. ### To change the gridline color programmatically @@ -59,15 +59,15 @@ With the control, you can customize the - A control named `dataGridView1`. -- References to the , , and assemblies. +- References to the , , and assemblies. ## See Also - - - - - + + + + + [Basic Formatting and Styling in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-formatting-and-styling-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/checkedlistbox-control-overview-windows-forms.md b/docs/framework/winforms/controls/checkedlistbox-control-overview-windows-forms.md index 9e7a7a8aadc69..b58dc30d81eb9 100644 --- a/docs/framework/winforms/controls/checkedlistbox-control-overview-windows-forms.md +++ b/docs/framework/winforms/controls/checkedlistbox-control-overview-windows-forms.md @@ -24,14 +24,14 @@ ms.author: dotnetcontent manager: "wpickett" --- # CheckedListBox Control Overview (Windows Forms) -The Windows Forms control extends the control. It does almost everything that a list box does and also can display a check mark next to items in the list. Other differences between the two controls are that checked list boxes only support ; and that checked list boxes can only have one item or none selected. Note that a selected item appears highlighted on the form and is not the same as a checked item. +The Windows Forms control extends the control. It does almost everything that a list box does and also can display a check mark next to items in the list. Other differences between the two controls are that checked list boxes only support ; and that checked list boxes can only have one item or none selected. Note that a selected item appears highlighted on the form and is not the same as a checked item. Checked list boxes can have items added at design time using the **String Collection Editor** or their items can added dynamically from a collection at run time, using the property. For more information, see [How to: Add and Remove Items from a Windows Forms ComboBox, ListBox, or CheckedListBox Control](../../../../docs/framework/winforms/controls/add-and-remove-items-from-a-wf-combobox.md). ## See Also - - + + [ListBox Control Overview](../../../../docs/framework/winforms/controls/listbox-control-overview-windows-forms.md) [Windows Forms Controls Used to List Options](../../../../docs/framework/winforms/controls/windows-forms-controls-used-to-list-options.md) [How to: Determine Checked Items in the Windows Forms CheckedListBox Control](../../../../docs/framework/winforms/controls/how-to-determine-checked-items-in-the-windows-forms-checkedlistbox-control.md) diff --git a/docs/framework/winforms/controls/column-fill-mode-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/column-fill-mode-in-the-windows-forms-datagridview-control.md index 2b7b3f1d51e7d..f823b10047a44 100644 --- a/docs/framework/winforms/controls/column-fill-mode-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/column-fill-mode-in-the-windows-forms-datagridview-control.md @@ -69,16 +69,16 @@ In column fill mode, the control resize ## See Also - - + + - - + + - - - - - + + + + + [Resizing Columns and Rows in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/resizing-columns-and-rows-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/column-sort-modes-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/column-sort-modes-in-the-windows-forms-datagridview-control.md index db8e6197c03ea..ce8b16fd8bc41 100644 --- a/docs/framework/winforms/controls/column-sort-modes-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/column-sort-modes-in-the-windows-forms-datagridview-control.md @@ -29,11 +29,11 @@ manager: "wpickett" ||Default for non–text box columns. You can sort this column programmatically; however, it is not intended for sorting, so no space is reserved for the sorting glyph.| ||You can sort this column programmatically, and space is reserved for the sorting glyph.| - You might want to change the sort mode for a column that defaults to if it contains values that can be meaningfully ordered. For example, if you have a database column containing numbers that represent item states, you can display these numbers as corresponding icons by binding an image column to the database column. You can then change the numerical cell values into image display values in a handler for the event. In this case, setting the property to will enable your users to sort the column. Automatic sorting will enable your users to group items that have the same state even if the states corresponding to the numbers do not have a natural sequence. Check box columns are another example where automatic sorting is useful for grouping items in the same state. + You might want to change the sort mode for a column that defaults to if it contains values that can be meaningfully ordered. For example, if you have a database column containing numbers that represent item states, you can display these numbers as corresponding icons by binding an image column to the database column. You can then change the numerical cell values into image display values in a handler for the event. In this case, setting the property to will enable your users to sort the column. Automatic sorting will enable your users to group items that have the same state even if the states corresponding to the numbers do not have a natural sequence. Check box columns are another example where automatic sorting is useful for grouping items in the same state. You can sort a programmatically by the values in any column or in multiple columns, regardless of the settings. Programmatic sorting is useful when you want to provide your own user interface (UI) for sorting or when you want to implement custom sorting. Providing your own sorting UI is useful, for example, when you set the selection mode to enable column header selection. In this case, although the column headers cannot be used for sorting, you still want the headers to display the appropriate sorting glyph, so you would set the property to . - Columns set to programmatic sort mode do not automatically display a sorting glyph. For these columns, you must display the glyph yourself by setting the property. This is necessary if you want flexibility in custom sorting. For example, if you sort the by multiple columns, you might want to display multiple sorting glyphs or no sorting glyph. + Columns set to programmatic sort mode do not automatically display a sorting glyph. For these columns, you must display the glyph yourself by setting the property. This is necessary if you want flexibility in custom sorting. For example, if you sort the by multiple columns, you might want to display multiple sorting glyphs or no sorting glyph. Although you can programmatically sort a by any column, some columns, such as button columns, might not contain values that can be meaningfully ordered. For these columns, a property setting of indicates that it will never be used for sorting, so there is no need to reserve space in the header for the sorting glyph. @@ -44,7 +44,7 @@ manager: "wpickett" ## Programmatic Sorting You can sort a programmatically by calling its method. - The `Sort(DataGridViewColumn,ListSortDirection)` overload of the method takes a and a enumeration value as parameters. This overload is useful when sorting by columns with values that can be meaningfully ordered, but which you do not want to configure for automatic sorting. When you call this overload and pass in a column with a property value of , the and properties are set automatically and the appropriate sorting glyph appears in the column header. + The `Sort(DataGridViewColumn,ListSortDirection)` overload of the method takes a and a enumeration value as parameters. This overload is useful when sorting by columns with values that can be meaningfully ordered, but which you do not want to configure for automatic sorting. When you call this overload and pass in a column with a property value of , the and properties are set automatically and the appropriate sorting glyph appears in the column header. > [!NOTE] > When the control is bound to an external data source by setting the property, the `Sort(DataGridViewColumn,ListSortDirection)` method overload does not work for unbound columns. Additionally, when the property is `true`, you can call this overload only for bound columns. To determine whether a column is data-bound, check the property value. Sorting unbound columns in bound mode is not supported. @@ -57,9 +57,9 @@ manager: "wpickett" > [!NOTE] > The `Sort(IComparer)` method overload works only when the control is not bound to an external data source and the property value is `false`. To customize sorting for columns bound to an external data source, you must use the sorting operations provided by the data source. In virtual mode, you must provide your own sorting operations for unbound columns. - To use the `Sort(IComparer)` method overload, you must create your own class that implements the interface. This interface requires your class to implement the method, to which the passes objects as input when the `Sort(IComparer)` method overload is called. With this, you can calculate the correct row ordering based on the values in any column. + To use the `Sort(IComparer)` method overload, you must create your own class that implements the interface. This interface requires your class to implement the method, to which the passes objects as input when the `Sort(IComparer)` method overload is called. With this, you can calculate the correct row ordering based on the values in any column. - The `Sort(IComparer)` method overload does not set the and properties, so you must always set the property to display the sorting glyph. + The `Sort(IComparer)` method overload does not set the and properties, so you must always set the property to display the sorting glyph. As an alternative to the `Sort(IComparer)` method overload, you can provide custom sorting by implementing a handler for the event. This event occurs when users click the headers of columns configured for automatic sorting or when you call the `Sort(DataGridViewColumn,ListSortDirection)` overload of the method. The event occurs for each pair of rows in the control, enabling you to calculate their correct order. @@ -68,11 +68,11 @@ manager: "wpickett" ## See Also - - - - - + + + + + [Sorting Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/sorting-data-in-the-windows-forms-datagridview-control.md) [How to: Set the Sort Modes for Columns in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/set-the-sort-modes-for-columns-wf-datagridview-control.md) [How to: Customize Sorting in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-customize-sorting-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/column-types-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/column-types-in-the-windows-forms-datagridview-control.md index 67da8f39b50c0..8468a7e208881 100644 --- a/docs/framework/winforms/controls/column-types-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/column-types-in-the-windows-forms-datagridview-control.md @@ -59,23 +59,23 @@ The control uses several column types t The automatic population of an image column from a data source works with byte arrays in a variety of image formats, including all formats supported by the class and the OLE Picture format used by Microsoft® Access and the Northwind sample database. - Populating an image column manually is useful when you want to provide the functionality of a , but with a customized appearance. You can handle the event to respond to clicks within an image cell. + Populating an image column manually is useful when you want to provide the functionality of a , but with a customized appearance. You can handle the event to respond to clicks within an image cell. Populating the cells of an image column in a handler for the event is useful when you want to provide images for calculated values or values in non-image formats. For example, you may have a "Risk" column with string values such as `"high"`, `"middle"`, and `"low"` that you want to display as icons. Alternately, you may have an "Image" column that contains the locations of images that must be loaded rather than the binary content of the images. ## DataGridViewButtonColumn With the , you can display a column of cells that contain buttons. This is useful when you want to provide an easy way for your users to perform actions on particular records, such as placing an order or displaying child records in a separate window. - Button columns are not generated automatically when data-binding a control. To use button columns, you must create them manually and add them to the collection returned by the property. + Button columns are not generated automatically when data-binding a control. To use button columns, you must create them manually and add them to the collection returned by the property. - You can respond to user clicks in button cells by handling the event. + You can respond to user clicks in button cells by handling the event. ## DataGridViewComboBoxColumn With the , you can display a column of cells that contain drop-down list boxes. This is useful for data entry in fields that can only contain particular values, such as the Category column of the Products table in the Northwind sample database. You can populate the drop-down list used for all cells the same way you would populate a drop-down list, either manually through the collection returned by the property, or by binding it to a data source through the , , and properties. For more information, see [ComboBox Control](../../../../docs/framework/winforms/controls/combobox-control-windows-forms.md). - You can bind the actual cell values to the data source used by the control by setting the property of the . + You can bind the actual cell values to the data source used by the control by setting the property of the . Combo box columns are not generated automatically when data-binding a control. To use combo box columns, you must create them manually and add them to the collection returned by the property. diff --git a/docs/framework/winforms/controls/considerations-when-hosting-an-activex-control-on-a-windows-form.md b/docs/framework/winforms/controls/considerations-when-hosting-an-activex-control-on-a-windows-form.md index 9d4f020c7bd65..b9abbdd2c9a81 100644 --- a/docs/framework/winforms/controls/considerations-when-hosting-an-activex-control-on-a-windows-form.md +++ b/docs/framework/winforms/controls/considerations-when-hosting-an-activex-control-on-a-windows-form.md @@ -26,7 +26,7 @@ manager: "wpickett" # Considerations When Hosting an ActiveX Control on a Windows Form Although Windows Forms have been optimized to host Windows Forms controls, you can still use ActiveX controls. Keep the following considerations in mind when planning an application that uses ActiveX controls: -- **Security** The common language runtime has been enhanced with regard to code access security. Applications featuring Windows Forms can run in a fully trusted environment without issue and in a semi-trusted environment with most of the functionality accessible. Windows Forms controls can be hosted in a browser with no complications. However, ActiveX controls on Windows Forms cannot take advantage of these security enhancements. Running an ActiveX control requires unmanaged code permission, which is set with the property. For more information about security and unmanaged code permission, see . +- **Security** The common language runtime has been enhanced with regard to code access security. Applications featuring Windows Forms can run in a fully trusted environment without issue and in a semi-trusted environment with most of the functionality accessible. Windows Forms controls can be hosted in a browser with no complications. However, ActiveX controls on Windows Forms cannot take advantage of these security enhancements. Running an ActiveX control requires unmanaged code permission, which is set with the property. For more information about security and unmanaged code permission, see . - **Total Cost of Ownership** ActiveX controls added to a Windows Form are deployed with that Windows Form in their entirety, which can add significantly to the size of the file(s) created. Additionally, using ActiveX controls on Windows Forms requires writing to the registry. This is more invasive to a user's computer than Windows Forms controls, which do not require this. diff --git a/docs/framework/winforms/controls/controls-with-built-in-owner-drawing-support.md b/docs/framework/winforms/controls/controls-with-built-in-owner-drawing-support.md index 2b92ae861e802..c1e83a885dea5 100644 --- a/docs/framework/winforms/controls/controls-with-built-in-owner-drawing-support.md +++ b/docs/framework/winforms/controls/controls-with-built-in-owner-drawing-support.md @@ -82,17 +82,17 @@ Owner drawing in Windows Forms, which is also known as custom drawing, is a tech For more information, including code examples, see the following topics: -- +- -- +- -- +- -- +- -- +- -- +- - [How to: Create Variable Sized Text in a ComboBox Control](../../../../docs/framework/winforms/controls/how-to-create-variable-sized-text-in-a-combobox-control.md) @@ -103,11 +103,11 @@ Owner drawing in Windows Forms, which is also known as custom drawing, is a tech For more information, including code examples, see the following reference topics: -- +- -- +- -- +- ### TabControl Control The control enables you to draw individual tabs in the control. Owner drawing affects only the tabs; the contents are not affected. @@ -116,9 +116,9 @@ Owner drawing in Windows Forms, which is also known as custom drawing, is a tech For more information, including code examples, see the following reference topics: -- +- -- +- ### ToolTip Component The component enables you to draw the entire ToolTip when it is displayed. @@ -127,11 +127,11 @@ Owner drawing in Windows Forms, which is also known as custom drawing, is a tech For more information, including code examples, see the following reference topics: -- +- -- +- -- +- ### ListView Control The control enables you to draw individual items, subitems, and column headers in the control. @@ -144,13 +144,13 @@ Owner drawing in Windows Forms, which is also known as custom drawing, is a tech For more information, including code examples, see the following reference topics: -- +- -- +- -- +- -- +- ### TreeView Control The control enables you to draw individual nodes in the control. @@ -161,9 +161,9 @@ Owner drawing in Windows Forms, which is also known as custom drawing, is a tech For more information, including code examples, see the following reference topics: -- +- -- +- ### DataGridView Control The control enables you to draw individual cells and rows in the control. diff --git a/docs/framework/winforms/controls/create-and-set-a-custom-renderer-for-the-toolstrip-control-in-wf.md b/docs/framework/winforms/controls/create-and-set-a-custom-renderer-for-the-toolstrip-control-in-wf.md index 120071314e0b1..9f8d2d445ceff 100644 --- a/docs/framework/winforms/controls/create-and-set-a-custom-renderer-for-the-toolstrip-control-in-wf.md +++ b/docs/framework/winforms/controls/create-and-set-a-custom-renderer-for-the-toolstrip-control-in-wf.md @@ -23,12 +23,12 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Create and Set a Custom Renderer for the ToolStrip Control in Windows Forms - controls give easy support to themes and styles. You can achieve completely custom appearance and behavior (look and feel) by setting either the property or the property to a custom renderer. + controls give easy support to themes and styles. You can achieve completely custom appearance and behavior (look and feel) by setting either the property or the property to a custom renderer. - You can assign renderers to each individual , , , or control, or you can use the property to affect all objects by setting the property to . + You can assign renderers to each individual , , , or control, or you can use the property to affect all objects by setting the property to . > [!NOTE] -> returns only if the value of is not `null`. +> returns only if the value of is not `null`. ### To create a custom renderer @@ -64,7 +64,7 @@ manager: "wpickett" ### To set the custom renderer to be the current renderer -1. To set the custom renderer for one , set the property to the custom renderer. +1. To set the custom renderer for one , set the property to the custom renderer. ```vb toolStrip1.Renderer = New RedTextRenderer() @@ -74,7 +74,7 @@ manager: "wpickett" toolStrip1.Renderer = new RedTextRenderer(); ``` -2. Or to set the custom renderer for all classes contained in your application: Set the property to the custom renderer and set the property to . +2. Or to set the custom renderer for all classes contained in your application: Set the property to the custom renderer and set the property to . ```vb toolStrip1.RenderMode = ToolStripRenderMode.ManagerRenderMode diff --git a/docs/framework/winforms/controls/creating-a-wf-control-design-time-features.md b/docs/framework/winforms/controls/creating-a-wf-control-design-time-features.md index c93f575a46b07..4374fe8561527 100644 --- a/docs/framework/winforms/controls/creating-a-wf-control-design-time-features.md +++ b/docs/framework/winforms/controls/creating-a-wf-control-design-time-features.md @@ -232,7 +232,7 @@ using MarqueeControlLibrary; Common features of the two controls are factored into an interface called `IMarqueeWidget`. This allows the `MarqueeControl` to discover any Marquee-related child controls and give them special treatment. - To implement the periodic animation feature, you will use objects from the namespace. You could use objects, but when many `IMarqueeWidget` objects are present, the single UI thread may be unable to keep up with the animation. + To implement the periodic animation feature, you will use objects from the namespace. You could use objects, but when many `IMarqueeWidget` objects are present, the single UI thread may be unable to keep up with the animation. #### To create a child control for your custom control @@ -519,7 +519,7 @@ using MarqueeControlLibrary; 2. Drag two controls from the **Toolbox** onto the `LightShapeSelectionControl`. Name them `squarePanel` and `circlePanel`. Arrange them side by side. Set the property of both controls to (60, 60). Set the property of the `squarePanel` control to (8, 10). Set the property of the `circlePanel` control to (80, 10). Finally, set the property of the `LightShapeSelectionControl` to (150, 80). -3. Open the `LightShapeSelectionControl` source file in the **Code Editor**. At the top of the file, import the namespace: +3. Open the `LightShapeSelectionControl` source file in the **Code Editor**. At the top of the file, import the namespace: ```vb Imports System.Windows.Forms.Design diff --git a/docs/framework/winforms/controls/customize-the-appearance-of-rows-in-the-datagrid.md b/docs/framework/winforms/controls/customize-the-appearance-of-rows-in-the-datagrid.md index e2cccae033761..6dde7ce2707dd 100644 --- a/docs/framework/winforms/controls/customize-the-appearance-of-rows-in-the-datagrid.md +++ b/docs/framework/winforms/controls/customize-the-appearance-of-rows-in-the-datagrid.md @@ -22,7 +22,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Customize the Appearance of Rows in the Windows Forms DataGridView Control -You can control the appearance of rows by handling one or both of the and events. These events are designed so that you can paint only what you want to while letting the control paint the rest. For example, if you want to paint a custom background, you can handle the event and let the individual cells paint their own foreground content. Alternately, you can let the cells paint themselves and add custom foreground content in a handler for the event. You can also disable cell painting and paint everything yourself in a event handler. +You can control the appearance of rows by handling one or both of the and events. These events are designed so that you can paint only what you want to while letting the control paint the rest. For example, if you want to paint a custom background, you can handle the event and let the individual cells paint their own foreground content. Alternately, you can let the cells paint themselves and add custom foreground content in a handler for the event. You can also disable cell painting and paint everything yourself in a event handler. The following code example implements handlers for both events in order to provide a gradient selection background and some custom foreground content that spans multiple columns. @@ -39,7 +39,7 @@ You can control the appearance of rows ## See Also - - + + [Customizing the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/customizing-the-windows-forms-datagridview-control.md) [DataGridView Control Architecture](../../../../docs/framework/winforms/controls/datagridview-control-architecture-windows-forms.md) diff --git a/docs/framework/winforms/controls/data-display-modes-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/data-display-modes-in-the-windows-forms-datagridview-control.md index a1320a39ca4b7..6d756557d9906 100644 --- a/docs/framework/winforms/controls/data-display-modes-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/data-display-modes-in-the-windows-forms-datagridview-control.md @@ -25,7 +25,7 @@ manager: "wpickett" The control can display data in three distinct modes: bound, unbound, and virtual. Choose the most suitable mode based on your requirements. ## Unbound - Unbound mode is suitable for displaying relatively small amounts of data that you manage programmatically. You do not attach the control directly to a data source as in bound mode. Instead, you must populate the control yourself, typically by using the method. + Unbound mode is suitable for displaying relatively small amounts of data that you manage programmatically. You do not attach the control directly to a data source as in bound mode. Instead, you must populate the control yourself, typically by using the method. Unbound mode can be particularly useful for static, read-only data, or when you want to provide your own code that interacts with an external data store. When you want your users to interact with an external data source, however, you will typically use bound mode. @@ -36,7 +36,7 @@ The control can display data in three d For an example that uses a bound control, see [Walkthrough: Validating Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/walkthrough-validating-data-in-the-windows-forms-datagridview-control.md). - You can also add unbound columns to a control in bound mode. This is useful when you want to display a column of buttons or links that enable users to perform actions on specific rows. It is also useful to display columns with values calculated from bound columns. You can populate the cell values for calculated columns in a handler for the event. If you are using a or as the data source, however, you might want to use the property to create a calculated column instead. In this case, the control will treat calculated column just like any other column in the data source. + You can also add unbound columns to a control in bound mode. This is useful when you want to display a column of buttons or links that enable users to perform actions on specific rows. It is also useful to display columns with values calculated from bound columns. You can populate the cell values for calculated columns in a handler for the event. If you are using a or as the data source, however, you might want to use the property to create a calculated column instead. In this case, the control will treat calculated column just like any other column in the data source. Sorting by unbound columns in bound mode is not supported. If you create an unbound column in bound mode that contains user-editable values, you must implement virtual mode to maintain these values when the control is sorted by a bound column. @@ -51,10 +51,10 @@ The control can display data in three d ## See Also - - + + - + [Displaying Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md) [Column Types in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/column-types-in-the-windows-forms-datagridview-control.md) [Walkthrough: Creating an Unbound Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/walkthrough-creating-an-unbound-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/data-entry-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/data-entry-in-the-windows-forms-datagridview-control.md index aa3b677eeae4d..d2e16ed7249c0 100644 --- a/docs/framework/winforms/controls/data-entry-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/data-entry-in-the-windows-forms-datagridview-control.md @@ -44,16 +44,16 @@ The `DataGridView` control provides several features that let you change how use Provides reference documentation for the control. - + Provides reference documentation for the property. - + Provides reference documentation for the event. - + Provides reference documentation for the event. - + Provides reference documentation for the event. ## Related Sections diff --git a/docs/framework/winforms/controls/data-formatting-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/data-formatting-in-the-windows-forms-datagridview-control.md index d58770da0d086..556cbf4e3a234 100644 --- a/docs/framework/winforms/controls/data-formatting-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/data-formatting-in-the-windows-forms-datagridview-control.md @@ -30,7 +30,7 @@ The control provides automatic conversi The class provides additional formatting properties for wordwrap, text alignment, and the custom display of null database values. For more information, see [How to: Format Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-format-data-in-the-windows-forms-datagridview-control.md). ## Formatting with the CellFormatting Event - If the basic formatting does not meet your needs, you can provide custom data formatting in a handler for the event. The passed to the handler has a property that initially contains the cell value. Normally, this value is automatically converted to the display type. To convert the value yourself, set the property to a value of the display type. + If the basic formatting does not meet your needs, you can provide custom data formatting in a handler for the event. The passed to the handler has a property that initially contains the cell value. Normally, this value is automatically converted to the display type. To convert the value yourself, set the property to a value of the display type. > [!NOTE] > If a format string is in effect for the cell, it overrides your change of the property value unless you set the property to `true`. diff --git a/docs/framework/winforms/controls/datagridview-control-architecture-windows-forms.md b/docs/framework/winforms/controls/datagridview-control-architecture-windows-forms.md index 2bf1d1c28ed59..17b941551e130 100644 --- a/docs/framework/winforms/controls/datagridview-control-architecture-windows-forms.md +++ b/docs/framework/winforms/controls/datagridview-control-architecture-windows-forms.md @@ -20,7 +20,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # DataGridView Control Architecture (Windows Forms) -The control and its related classes are designed to be a flexible, extensible system for displaying and editing tabular data. These classes are all contained in the namespace, and they are all named with the "DataGridView" prefix. +The control and its related classes are designed to be a flexible, extensible system for displaying and editing tabular data. These classes are all contained in the namespace, and they are all named with the "DataGridView" prefix. ## Architecture Elements The primary companion classes derive from . The following object model illustrates the inheritance hierarchy. diff --git a/docs/framework/winforms/controls/datagridview-control-technology-summary-windows-forms.md b/docs/framework/winforms/controls/datagridview-control-technology-summary-windows-forms.md index 6735128ce6994..3761b162fd26d 100644 --- a/docs/framework/winforms/controls/datagridview-control-technology-summary-windows-forms.md +++ b/docs/framework/winforms/controls/datagridview-control-technology-summary-windows-forms.md @@ -29,9 +29,9 @@ This topic summarizes information about the `DataGridView` control and the class DataGridView, BindingSource, table, cell, data binding, virtual mode ## Namespaces - + - + ## Related Technologies `BindingSource` diff --git a/docs/framework/winforms/controls/default-cell-styles-datagridview.md b/docs/framework/winforms/controls/default-cell-styles-datagridview.md index e09326b52c8ac..f01f6d41003e9 100644 --- a/docs/framework/winforms/controls/default-cell-styles-datagridview.md +++ b/docs/framework/winforms/controls/default-cell-styles-datagridview.md @@ -65,15 +65,15 @@ The control lets you specify default ce 3. Select a format type, then modify the details of the type (such as the number of decimal places to display), using the **Sample** box to confirm your choices. -4. If you are binding the control to a data source that is likely to contain null values, fill in the **Null Value** text box. This value is displayed when the cell value is equal to a null reference (`Nothing` in Visual Basic) or . +4. If you are binding the control to a data source that is likely to contain null values, fill in the **Null Value** text box. This value is displayed when the cell value is equal to a null reference (`Nothing` in Visual Basic) or . ## See Also - - - - + + + + [Cell Styles in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md) [How to: Set Alternating Row Styles for the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/set-alternating-row-styles-for-the-datagrid-using-the-designer.md) [How to: Create a Windows Application Project](http://msdn.microsoft.com/en-us/b2f93fed-c635-4705-8d0e-cf079a264efa) diff --git a/docs/framework/winforms/controls/default-keyboard-and-mouse-handling-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/default-keyboard-and-mouse-handling-in-the-windows-forms-datagridview-control.md index e94a7ed0b3014..6051e1965ca54 100644 --- a/docs/framework/winforms/controls/default-keyboard-and-mouse-handling-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/default-keyboard-and-mouse-handling-in-the-windows-forms-datagridview-control.md @@ -62,7 +62,7 @@ The following tables describe how users can interact with the value into the current cell if the cell can be edited. By default, the display value for a cell value is the value of the property of the in effect for the current cell.| +|CTRL+0|Enters a value into the current cell if the cell can be edited. By default, the display value for a cell value is the value of the property of the in effect for the current cell.| ### Selection Keys If the property is set to `false` and the property is set to , changing the current cell by using the navigation keys changes the selection to the new cell. The SHIFT, CTRL, and ALT keys do not affect this behavior. @@ -89,10 +89,10 @@ The following tables describe how users can interact with the event.| -|Left mouse button up|Raises the event| -|Left mouse button click|Raises the and events| -|Left mouse button down, and drag on a column header cell|If the property is `true`, moves the column so that it can be dropped into a new position.| +|Left mouse button down|Makes the clicked cell the current cell, and raises the event.| +|Left mouse button up|Raises the event| +|Left mouse button click|Raises the and events| +|Left mouse button down, and drag on a column header cell|If the property is `true`, moves the column so that it can be dropped into a new position.| ### Mouse Selection No selection behavior is associated with the middle mouse button or the mouse wheel. diff --git a/docs/framework/winforms/controls/developing-custom-windows-forms-controls.md b/docs/framework/winforms/controls/developing-custom-windows-forms-controls.md index 71b64aa555868..dc27b204f0921 100644 --- a/docs/framework/winforms/controls/developing-custom-windows-forms-controls.md +++ b/docs/framework/winforms/controls/developing-custom-windows-forms-controls.md @@ -29,7 +29,7 @@ Windows Forms controls are reusable components that encapsulate user interface f Highlights the essential elements of using controls in Windows Forms applications. [Varieties of Custom Controls](../../../../docs/framework/winforms/controls/varieties-of-custom-controls.md) - Describes the different kinds of custom controls you can author with the namespace. + Describes the different kinds of custom controls you can author with the namespace. [Windows Forms Control Development Basics](../../../../docs/framework/winforms/controls/windows-forms-control-development-basics.md) Discusses the first steps in developing a Windows Forms control. @@ -53,10 +53,10 @@ Windows Forms controls are reusable components that encapsulate user interface f Shows how to implement multithreaded controls. ## Reference - + Describes this class and has links to all of its members. - + Describes this class and has links to all of its members. ## Related Sections diff --git a/docs/framework/winforms/controls/developing-windows-forms-controls-at-design-time.md b/docs/framework/winforms/controls/developing-windows-forms-controls-at-design-time.md index 05ac660b63ee7..d54a5590b0450 100644 --- a/docs/framework/winforms/controls/developing-windows-forms-controls-at-design-time.md +++ b/docs/framework/winforms/controls/developing-windows-forms-controls-at-design-time.md @@ -49,7 +49,7 @@ For control authors, the .NET Framework provides a wealth of control authoring t Shows how to use the smart tag feature on Windows Forms controls. [Walkthrough: Serializing Collections of Standard Types with the DesignerSerializationVisibilityAttribute](../../../../docs/framework/winforms/controls/serializing-collections-designerserializationvisibilityattribute.md) - Shows how to use the attribute to serialize a collection. + Shows how to use the attribute to serialize a collection. [Walkthrough: Debugging Custom Windows Forms Controls at Design Time](../../../../docs/framework/winforms/controls/walkthrough-debugging-custom-windows-forms-controls-at-design-time.md) Shows how to debug the design-time behavior of a Windows Forms control. @@ -91,10 +91,10 @@ For control authors, the .NET Framework provides a wealth of control authoring t Shows how to diagnose and fix common issues that can occur when you author a custom component or control. ## Reference - + Describes this class and has links to all of its members. - + Describes this class and has links to all of its members. ## Related Sections diff --git a/docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md index c8fbceb299a36..595111328fa39 100644 --- a/docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md @@ -64,13 +64,13 @@ The `DataGridView` control is used to display data from a variety of external da Describes how to display data from two related database tables so that the values shown in one `DataGridView` control depend on the currently selected row in another control. [How to: Customize Data Formatting in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-customize-data-formatting-in-the-windows-forms-datagridview-control.md) - Describes how to handle the event to change the appearance of cells depending on their values. + Describes how to handle the event to change the appearance of cells depending on their values. ## Reference Provides reference documentation for the control. - + Provides reference documentation for the property. diff --git a/docs/framework/winforms/controls/enable-column-reordering-in-the-datagrid-using-the-designer.md b/docs/framework/winforms/controls/enable-column-reordering-in-the-datagrid-using-the-designer.md index d40a24ea143a9..d009582b25a64 100644 --- a/docs/framework/winforms/controls/enable-column-reordering-in-the-datagrid-using-the-designer.md +++ b/docs/framework/winforms/controls/enable-column-reordering-in-the-datagrid-using-the-designer.md @@ -36,7 +36,7 @@ When viewing data displayed in a Windows Forms - + [How to: Freeze Columns in the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/freeze-columns-in-the-datagrid-using-the-designer.md) [How to: Create a Windows Application Project](http://msdn.microsoft.com/en-us/b2f93fed-c635-4705-8d0e-cf079a264efa) [How to: Add Controls to Windows Forms](../../../../docs/framework/winforms/controls/how-to-add-controls-to-windows-forms.md) diff --git a/docs/framework/winforms/controls/enable-drag-and-drop-operations-with-wf-richtextbox-control.md b/docs/framework/winforms/controls/enable-drag-and-drop-operations-with-wf-richtextbox-control.md index 7897d2d3846a3..4c04e557e0d34 100644 --- a/docs/framework/winforms/controls/enable-drag-and-drop-operations-with-wf-richtextbox-control.md +++ b/docs/framework/winforms/controls/enable-drag-and-drop-operations-with-wf-richtextbox-control.md @@ -29,7 +29,7 @@ Drag-and-drop operations with the Windows Forms property of the control to `true`. -2. Write code in the event handler of the event. Use an `if` statement to ensure that the data being dragged is of an acceptable type (in this case, text). The property can be set to any value of the enumeration. +2. Write code in the event handler of the event. Use an `if` statement to ensure that the data being dragged is of an acceptable type (in this case, text). The property can be set to any value of the enumeration. ```vb Private Sub RichTextBox1_DragEnter(ByVal sender As Object, _ @@ -80,7 +80,7 @@ Drag-and-drop operations with the Windows Forms event. Use the method to retrieve the data being dragged. +3. Write code to handle the event. Use the method to retrieve the data being dragged. In the example below, the code sets the property of the control equal to the data being dragged. If there is already text in the control, the dragged text is inserted at the insertion point. diff --git a/docs/framework/winforms/controls/enable-tile-view-in-a-wf-listview-control-using-the-designer.md b/docs/framework/winforms/controls/enable-tile-view-in-a-wf-listview-control-using-the-designer.md index 14705216419f7..0d55b116dcf9c 100644 --- a/docs/framework/winforms/controls/enable-tile-view-in-a-wf-listview-control-using-the-designer.md +++ b/docs/framework/winforms/controls/enable-tile-view-in-a-wf-listview-control-using-the-designer.md @@ -33,7 +33,7 @@ The tile view feature of the control enable The following procedure requires a **Windows Application** project with a form containing a control. For information about setting up such a project, see [How to: Create a Windows Application Project](http://msdn.microsoft.com/en-us/b2f93fed-c635-4705-8d0e-cf079a264efa) and [How to: Add Controls to Windows Forms](../../../../docs/framework/winforms/controls/how-to-add-controls-to-windows-forms.md). > [!NOTE] -> The tile view is available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code related to the tile view has no effect, and the control displays in the large icon view. For more information, see . +> The tile view is available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code related to the tile view has no effect, and the control displays in the large icon view. For more information, see . > > The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose **Import and Export Settings** on the **Tools** menu. For more information, see [Customizing Development Settings in Visual Studio](http://msdn.microsoft.com/en-us/22c4debb-4e31-47a8-8f19-16f328d7dcd3). diff --git a/docs/framework/winforms/controls/enable-users-to-copy-multiple-cells-to-the-clipboard-datagridview.md b/docs/framework/winforms/controls/enable-users-to-copy-multiple-cells-to-the-clipboard-datagridview.md index facdbff57a4ec..fa822a90cce64 100644 --- a/docs/framework/winforms/controls/enable-users-to-copy-multiple-cells-to-the-clipboard-datagridview.md +++ b/docs/framework/winforms/controls/enable-users-to-copy-multiple-cells-to-the-clipboard-datagridview.md @@ -31,13 +31,13 @@ When you enable cell copying, you make the data in your property. +- Set the property. [!code-csharp[System.Windows.Forms.DataGridViewClipboardDemo#15](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewClipboardDemo/CS/datagridviewclipboarddemo.cs#15)] [!code-vb[System.Windows.Forms.DataGridViewClipboardDemo#15](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewClipboardDemo/VB/datagridviewclipboarddemo.vb#15)] ## Example - The following complete code example demonstrates how cells are copied to the Clipboard. This example includes a button that copies the selected cells to the Clipboard using the method and displays the Clipboard contents in a text box. + The following complete code example demonstrates how cells are copied to the Clipboard. This example includes a button that copies the selected cells to the Clipboard using the method and displays the Clipboard contents in a text box. [!code-csharp[System.Windows.Forms.DataGridViewClipboardDemo#00](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewClipboardDemo/CS/datagridviewclipboarddemo.cs#00)] [!code-vb[System.Windows.Forms.DataGridViewClipboardDemo#00](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewClipboardDemo/VB/datagridviewclipboarddemo.vb#00)] diff --git a/docs/framework/winforms/controls/events-in-windows-forms-controls.md b/docs/framework/winforms/controls/events-in-windows-forms-controls.md index 205cdac8d40f3..e558e205dd3be 100644 --- a/docs/framework/winforms/controls/events-in-windows-forms-controls.md +++ b/docs/framework/winforms/controls/events-in-windows-forms-controls.md @@ -21,7 +21,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # Events in Windows Forms Controls -A Windows Forms control inherits more than sixty events from . These include the event, which causes a control to be drawn, events related to displaying a window, such as the and events, and low-level mouse and keyboard events. Some low-level events are synthesized by into semantic events such as and . For details about inherited events, see . +A Windows Forms control inherits more than sixty events from . These include the event, which causes a control to be drawn, events related to displaying a window, such as the and events, and low-level mouse and keyboard events. Some low-level events are synthesized by into semantic events such as and . For details about inherited events, see . If your custom control needs to override inherited event functionality, override the inherited `On`*EventName* method instead of attaching a delegate. If you are not familiar with the event model in the .NET Framework, see [Raising Events from a Component](http://msdn.microsoft.com/library/9aebf605-a87d-470b-b7c8-f9abfc8360a0). diff --git a/docs/framework/winforms/controls/freeze-columns-in-the-datagrid-using-the-designer.md b/docs/framework/winforms/controls/freeze-columns-in-the-datagrid-using-the-designer.md index 30210b66018a8..e818a2008b4d1 100644 --- a/docs/framework/winforms/controls/freeze-columns-in-the-datagrid-using-the-designer.md +++ b/docs/framework/winforms/controls/freeze-columns-in-the-datagrid-using-the-designer.md @@ -45,7 +45,7 @@ When users view data displayed in a Windows Forms - + [How to: Add and Remove Columns in the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/add-and-remove-columns-in-the-datagrid-using-the-designer.md) [How to: Enable Column Reordering in the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/enable-column-reordering-in-the-datagrid-using-the-designer.md) [How to: Display Right-to-Left Text in Windows Forms for Globalization](http://msdn.microsoft.com/en-us/f0663385-2354-4c65-8676-706422283b14) diff --git a/docs/framework/winforms/controls/get-and-set-the-current-cell-wf-datagridview-control.md b/docs/framework/winforms/controls/get-and-set-the-current-cell-wf-datagridview-control.md index ebc032816e64b..d4f43924d51c6 100644 --- a/docs/framework/winforms/controls/get-and-set-the-current-cell-wf-datagridview-control.md +++ b/docs/framework/winforms/controls/get-and-set-the-current-cell-wf-datagridview-control.md @@ -50,10 +50,10 @@ Interaction with the often requires tha - A control named `dataGridView1`. -- References to the and assemblies. +- References to the and assemblies. ## See Also - + [Basic Column, Row, and Cell Features in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-column-row-and-cell-features-wf-datagridview-control.md) [Selection Modes in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/selection-modes-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/handling-user-input.md b/docs/framework/winforms/controls/handling-user-input.md index 1bbe6292a7c02..52c3d2cc24149 100644 --- a/docs/framework/winforms/controls/handling-user-input.md +++ b/docs/framework/winforms/controls/handling-user-input.md @@ -22,7 +22,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # Handling User Input -This topic describes the main keyboard and mouse events provided by . When handling an event, control authors should override the protected `On`*EventName* method rather than attaching a delegate to the event. For a review of events, see [Raising Events from a Component](http://msdn.microsoft.com/library/9aebf605-a87d-470b-b7c8-f9abfc8360a0). +This topic describes the main keyboard and mouse events provided by . When handling an event, control authors should override the protected `On`*EventName* method rather than attaching a delegate to the event. For a review of events, see [Raising Events from a Component](http://msdn.microsoft.com/library/9aebf605-a87d-470b-b7c8-f9abfc8360a0). > [!NOTE] > If there is no data associated with an event, an instance of the base class is passed as an argument to the `On`*EventName* method. diff --git a/docs/framework/winforms/controls/hide-columns-in-the-datagrid-using-the-designer.md b/docs/framework/winforms/controls/hide-columns-in-the-datagrid-using-the-designer.md index a83262c46c157..a05c5458f8aba 100644 --- a/docs/framework/winforms/controls/hide-columns-in-the-datagrid-using-the-designer.md +++ b/docs/framework/winforms/controls/hide-columns-in-the-datagrid-using-the-designer.md @@ -43,7 +43,7 @@ Sometimes you will want to display only some of the columns that are available i ## See Also - + [How to: Add and Remove Columns in the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/add-and-remove-columns-in-the-datagrid-using-the-designer.md) [How to: Create a Windows Application Project](http://msdn.microsoft.com/en-us/b2f93fed-c635-4705-8d0e-cf079a264efa) [How to: Add Controls to Windows Forms](../../../../docs/framework/winforms/controls/how-to-add-controls-to-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-access-objects-bound-to-windows-forms-datagridview-rows.md b/docs/framework/winforms/controls/how-to-access-objects-bound-to-windows-forms-datagridview-rows.md index 4f61869859286..e0c39df77a0a0 100644 --- a/docs/framework/winforms/controls/how-to-access-objects-bound-to-windows-forms-datagridview-rows.md +++ b/docs/framework/winforms/controls/how-to-access-objects-bound-to-windows-forms-datagridview-rows.md @@ -28,13 +28,13 @@ Sometimes it is useful to display a table of information stored in a collection ### To access row-bound objects -- Use the property. +- Use the property. [!code-csharp[System.Windows.Forms.DataGridViewObjectBinding#10](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewObjectBinding/CS/datagridviewobjectbinding.cs#10)] [!code-vb[System.Windows.Forms.DataGridViewObjectBinding#10](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewObjectBinding/VB/datagridviewobjectbinding.vb#10)] ## Example - The complete code example includes a simple `Customer` implementation and binds the to an containing a few `Customer` objects. The event handler of the must access the `Customer` objects through the rows, because the customer collection is not accessible outside the event handler. + The complete code example includes a simple `Customer` implementation and binds the to an containing a few `Customer` objects. The event handler of the must access the `Customer` objects through the rows, because the customer collection is not accessible outside the event handler. [!code-csharp[System.Windows.Forms.DataGridViewObjectBinding#00](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewObjectBinding/CS/datagridviewobjectbinding.cs#00)] [!code-vb[System.Windows.Forms.DataGridViewObjectBinding#00](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewObjectBinding/VB/datagridviewobjectbinding.vb#00)] @@ -49,6 +49,6 @@ Sometimes it is useful to display a table of information stored in a collection ## See Also - + [Displaying Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md) [How to: Bind Objects to Windows Forms DataGridView Controls](../../../../docs/framework/winforms/controls/how-to-bind-objects-to-windows-forms-datagridview-controls.md) diff --git a/docs/framework/winforms/controls/how-to-add-a-custom-place-to-a-file-dialog-box.md b/docs/framework/winforms/controls/how-to-add-a-custom-place-to-a-file-dialog-box.md index 4a6040447cfec..3627f1ef81e75 100644 --- a/docs/framework/winforms/controls/how-to-add-a-custom-place-to-a-file-dialog-box.md +++ b/docs/framework/winforms/controls/how-to-add-a-custom-place-to-a-file-dialog-box.md @@ -43,5 +43,5 @@ The default open and save dialog boxes on [!INCLUDE[wiprlhext](../../../../inclu ## See Also - + [Known Folder GUIDs for File Dialog Custom Places](../../../../docs/framework/winforms/controls/known-folder-guids-for-file-dialog-custom-places.md) diff --git a/docs/framework/winforms/controls/how-to-add-buttons-to-a-toolbar-control.md b/docs/framework/winforms/controls/how-to-add-buttons-to-a-toolbar-control.md index ff7a0bad6a41c..6cda0e8ea70fe 100644 --- a/docs/framework/winforms/controls/how-to-add-buttons-to-a-toolbar-control.md +++ b/docs/framework/winforms/controls/how-to-add-buttons-to-a-toolbar-control.md @@ -33,14 +33,14 @@ manager: "wpickett" ### To add buttons programmatically -1. In a procedure, create toolbar buttons by adding them to the collection. +1. In a procedure, create toolbar buttons by adding them to the collection. 2. Specify property settings for an individual button by passing the button's index via the property. The example below assumes a form with a control already added. > [!NOTE] - > The collection is a zero-based collection, so code should proceed accordingly. + > The collection is a zero-based collection, so code should proceed accordingly. ```vb Public Sub CreateToolBarButtons() diff --git a/docs/framework/winforms/controls/how-to-add-items-to-windows-forms-domainupdown-controls-programmatically.md b/docs/framework/winforms/controls/how-to-add-items-to-windows-forms-domainupdown-controls-programmatically.md index 37211193272e8..6f322b2e4fa5f 100644 --- a/docs/framework/winforms/controls/how-to-add-items-to-windows-forms-domainupdown-controls-programmatically.md +++ b/docs/framework/winforms/controls/how-to-add-items-to-windows-forms-domainupdown-controls-programmatically.md @@ -60,7 +60,7 @@ You can add items to the Windows Forms ## See Also - - + + [DomainUpDown Control](../../../../docs/framework/winforms/controls/domainupdown-control-windows-forms.md) [DomainUpDown Control Overview](../../../../docs/framework/winforms/controls/domainupdown-control-overview-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-add-toolstrip-items-dynamically.md b/docs/framework/winforms/controls/how-to-add-toolstrip-items-dynamically.md index 45a1a589e083d..4230e361f6b98 100644 --- a/docs/framework/winforms/controls/how-to-add-toolstrip-items-dynamically.md +++ b/docs/framework/winforms/controls/how-to-add-toolstrip-items-dynamically.md @@ -27,7 +27,7 @@ You can dynamically populate the menu item collection of a control. The example also shows how to reuse the same for three different controls on the form. - In the example, an event handler populates the menu item collection. The event handler examines the and properties and adds a describing the source control. + In the example, an event handler populates the menu item collection. The event handler examines the and properties and adds a describing the source control. [!code-csharp[System.Windows.Forms.ToolStrip.Misc#1](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/CS/Program.cs#1)] [!code-vb[System.Windows.Forms.ToolStrip.Misc#1](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/VB/Program.vb#1)] diff --git a/docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms-at-design-time.md b/docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms-at-design-time.md index 59a3d88e7f6d8..4a39eb13bdd6b 100644 --- a/docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms-at-design-time.md +++ b/docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms-at-design-time.md @@ -50,8 +50,8 @@ You can make your control align to the edge of your forms by setting the - + + [How to: Align a Control to the Edges of Forms](../../../../docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms.md) [Walkthrough: Arranging Controls on Windows Forms Using Snaplines](../../../../docs/framework/winforms/controls/walkthrough-arranging-controls-on-windows-forms-using-snaplines.md) [How to: Anchor Controls on Windows Forms](../../../../docs/framework/winforms/controls/how-to-anchor-controls-on-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms.md b/docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms.md index b3d200edf423f..4f345442f5d7d 100644 --- a/docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms.md +++ b/docs/framework/winforms/controls/how-to-align-a-control-to-the-edges-of-forms.md @@ -55,8 +55,8 @@ You can make your control align to the edge of your forms by setting the - + + [Developing Custom Windows Forms Controls with the .NET Framework](../../../../docs/framework/winforms/controls/developing-custom-windows-forms-controls.md) [How to: Anchor and Dock Child Controls in a FlowLayoutPanel Control](../../../../docs/framework/winforms/controls/how-to-anchor-and-dock-child-controls-in-a-flowlayoutpanel-control.md) [How to: Anchor and Dock Child Controls in a TableLayoutPanel Control](../../../../docs/framework/winforms/controls/how-to-anchor-and-dock-child-controls-in-a-tablelayoutpanel-control.md) diff --git a/docs/framework/winforms/controls/how-to-append-a-menustrip-to-an-mdi-parent-window-windows-forms.md b/docs/framework/winforms/controls/how-to-append-a-menustrip-to-an-mdi-parent-window-windows-forms.md index d8e57d8e3ae14..84bbdd06678f7 100644 --- a/docs/framework/winforms/controls/how-to-append-a-menustrip-to-an-mdi-parent-window-windows-forms.md +++ b/docs/framework/winforms/controls/how-to-append-a-menustrip-to-an-mdi-parent-window-windows-forms.md @@ -91,4 +91,4 @@ In some applications, the kind of a multiple-document interface (MDI) child wind - A control on `Form1` named `menuStrip1`, and a control on `Form2` named `menuStrip2`. -- References to the and assemblies. +- References to the and assemblies. diff --git a/docs/framework/winforms/controls/how-to-bind-data-to-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-bind-data-to-the-windows-forms-datagridview-control.md index ddf2bfa832b94..faa5b985084d6 100644 --- a/docs/framework/winforms/controls/how-to-bind-data-to-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-bind-data-to-the-windows-forms-datagridview-control.md @@ -61,7 +61,7 @@ The control supports the standard Windo ## See Also - + [Displaying Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md) [Protecting Connection Information](../../../../docs/framework/data/adonet/protecting-connection-information.md) diff --git a/docs/framework/winforms/controls/how-to-change-the-order-of-columns-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-change-the-order-of-columns-in-the-windows-forms-datagridview-control.md index 8bcdf61732de8..cdc16a6db6900 100644 --- a/docs/framework/winforms/controls/how-to-change-the-order-of-columns-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-change-the-order-of-columns-in-the-windows-forms-datagridview-control.md @@ -37,12 +37,12 @@ When you use a to display data from a d - A control named `customersDataGridView` that is bound to a table with the indicated column names, such as the `Customers` table in the Northwind sample database. -- References to the , , , and assemblies. +- References to the , , , and assemblies. ## See Also - - + + [Displaying Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md) [How to: Bind Data to the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-bind-data-to-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-create-a-windows-forms-control-that-shows-progress.md b/docs/framework/winforms/controls/how-to-create-a-windows-forms-control-that-shows-progress.md index 85877d27d4950..2654a17b9f891 100644 --- a/docs/framework/winforms/controls/how-to-create-a-windows-forms-control-that-shows-progress.md +++ b/docs/framework/winforms/controls/how-to-create-a-windows-forms-control-that-shows-progress.md @@ -62,7 +62,7 @@ The following code example shows a custom control called `FlashTrackBar` that ca > [!NOTE] > `FlashTrackBar` uses the class for event data and for the event delegate. - To handle the corresponding *EventName* events, `FlashTrackBar` overrides the following methods that it inherits from : + To handle the corresponding *EventName* events, `FlashTrackBar` overrides the following methods that it inherits from : - @@ -74,7 +74,7 @@ The following code example shows a custom control called `FlashTrackBar` that ca - - To handle the corresponding property-changed events, `FlashTrackBar` overrides the following methods that it inherits from : + To handle the corresponding property-changed events, `FlashTrackBar` overrides the following methods that it inherits from : - diff --git a/docs/framework/winforms/controls/how-to-create-an-mdi-form-with-menu-merging-and-toolstrip-controls.md b/docs/framework/winforms/controls/how-to-create-an-mdi-form-with-menu-merging-and-toolstrip-controls.md index e3b9e52ccaeaf..1417e989f21af 100644 --- a/docs/framework/winforms/controls/how-to-create-an-mdi-form-with-menu-merging-and-toolstrip-controls.md +++ b/docs/framework/winforms/controls/how-to-create-an-mdi-form-with-menu-merging-and-toolstrip-controls.md @@ -23,7 +23,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Create an MDI Form with Menu Merging and ToolStrip Controls -The namespace supports multiple document interface (MDI) applications, and the control supports menu merging. MDI forms can also controls. +The namespace supports multiple document interface (MDI) applications, and the control supports menu merging. MDI forms can also controls. There is extensive support for this feature in [!INCLUDE[vsprvs](../../../../includes/vsprvs-md.md)]. diff --git a/docs/framework/winforms/controls/how-to-create-an-mdi-window-list-with-menustrip-windows-forms.md b/docs/framework/winforms/controls/how-to-create-an-mdi-window-list-with-menustrip-windows-forms.md index fefbeb6e64335..5dcb5430fa5a8 100644 --- a/docs/framework/winforms/controls/how-to-create-an-mdi-window-list-with-menustrip-windows-forms.md +++ b/docs/framework/winforms/controls/how-to-create-an-mdi-window-list-with-menustrip-windows-forms.md @@ -84,7 +84,7 @@ Use the multiple-document interface (MDI) to create applications that can open s - A control on `Form1` named `menuStrip1`, and a control on `Form2` named `menuStrip2`. -- References to the and assemblies. +- References to the and assemblies. ## See Also [How to: Create MDI Parent Forms](../../../../docs/framework/winforms/advanced/how-to-create-mdi-parent-forms.md) diff --git a/docs/framework/winforms/controls/how-to-create-variable-sized-text-in-a-combobox-control.md b/docs/framework/winforms/controls/how-to-create-variable-sized-text-in-a-combobox-control.md index 47dee7b8b0ee7..00b3ff09e1107 100644 --- a/docs/framework/winforms/controls/how-to-create-variable-sized-text-in-a-combobox-control.md +++ b/docs/framework/winforms/controls/how-to-create-variable-sized-text-in-a-combobox-control.md @@ -71,7 +71,7 @@ End Sub > [!NOTE] > This technique is also applicable to the control — you can substitute a for the . -- References to the and namespaces. +- References to the and namespaces. ## See Also diff --git a/docs/framework/winforms/controls/how-to-custom-draw-a-toolstrip-control.md b/docs/framework/winforms/controls/how-to-custom-draw-a-toolstrip-control.md index 3da7de6f2b9c7..8776525b3c5b7 100644 --- a/docs/framework/winforms/controls/how-to-custom-draw-a-toolstrip-control.md +++ b/docs/framework/winforms/controls/how-to-custom-draw-a-toolstrip-control.md @@ -54,7 +54,7 @@ The controls have the following associated ### To change the Microsoft Office–style borders to straight -- Override , but do not call the base class. +- Override , but do not call the base class. > [!NOTE] > There is a version of this method for , , and . @@ -117,15 +117,15 @@ The controls have the following associated ### To change the rendering for all ToolStrip controls in your application -1. Use the property to choose one of the provided renderers. +1. Use the property to choose one of the provided renderers. -2. Use to assign a custom renderer. +2. Use to assign a custom renderer. -3. Ensure that is set to the default value of . +3. Ensure that is set to the default value of . ### To turn off the Microsoft Office colors for the entire application -- Set to `false`. +- Set to `false`. ### To turn off the Microsoft Office colors for one ToolStrip control diff --git a/docs/framework/winforms/controls/how-to-customize-data-formatting-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-customize-data-formatting-in-the-windows-forms-datagridview-control.md index eb0e24f8166de..d4a2c16d679ec 100644 --- a/docs/framework/winforms/controls/how-to-customize-data-formatting-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-customize-data-formatting-in-the-windows-forms-datagridview-control.md @@ -29,7 +29,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Customize Data Formatting in the Windows Forms DataGridView Control -The following code example demonstrates how to implement a handler for the event that changes how cells are displayed depending on their columns and values. +The following code example demonstrates how to implement a handler for the event that changes how cells are displayed depending on their columns and values. Cells in the `Balance` column that contain negative numbers are given a red background. You can also format these cells as currency to display parentheses around negative values. For more information, see [How to: Format Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-format-data-in-the-windows-forms-datagridview-control.md). @@ -49,8 +49,8 @@ The following code example demonstrates how to implement a handler for the - + + diff --git a/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md b/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md index 87afff084742e..02f892fde5a95 100644 --- a/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md +++ b/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md @@ -29,7 +29,7 @@ When you use a component to bind a Win > When an item is added by handling the event, the addition cannot be canceled. ## Example - The following example demonstrates how to bind a control to a class factory by using a component. When the user clicks the control's new row, the event is raised. The event handler creates a new `DemoCustomer` object, which is assigned to the property. This causes the new `DemoCustomer` object to be added to the component's list and to be displayed in the new row of the control. + The following example demonstrates how to bind a control to a class factory by using a component. When the user clicks the control's new row, the event is raised. The event handler creates a new `DemoCustomer` object, which is assigned to the property. This causes the new `DemoCustomer` object to be added to the component's list and to be displayed in the new row of the control. [!code-cpp[System.Windows.Forms.DataConnector.AddingNew#1](../../../../samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CPP/form1.cpp#1)] [!code-csharp[System.Windows.Forms.DataConnector.AddingNew#1](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CS/form1.cs#1)] diff --git a/docs/framework/winforms/controls/how-to-delete-or-hide-columns-in-the-windows-forms-datagrid-control.md b/docs/framework/winforms/controls/how-to-delete-or-hide-columns-in-the-windows-forms-datagrid-control.md index 42e795b4bd760..c89c6525dba5e 100644 --- a/docs/framework/winforms/controls/how-to-delete-or-hide-columns-in-the-windows-forms-datagrid-control.md +++ b/docs/framework/winforms/controls/how-to-delete-or-hide-columns-in-the-windows-forms-datagrid-control.md @@ -39,7 +39,7 @@ manager: "wpickett" 1. In the declarations area of your form, declare a new instance of the class. -2. Set the property to the table in your data source that you want to apply the style to. The following example uses the property, which it assumes is already set. +2. Set the property to the table in your data source that you want to apply the style to. The following example uses the property, which it assumes is already set. 3. Add the new object to the datagrid's table styles collection. @@ -86,7 +86,7 @@ manager: "wpickett" 1. In the declarations area of your form, declare a new instance of the class. -2. Set the property of the to the table in your data source that you want to apply the style to. The following code example uses the property, which it assumes is already set. +2. Set the property of the to the table in your data source that you want to apply the style to. The following code example uses the property, which it assumes is already set. 3. Add the new object to the datagrid's table styles collection. diff --git a/docs/framework/winforms/controls/how-to-determine-page-properties-using-the-pagesetupdialog-component.md b/docs/framework/winforms/controls/how-to-determine-page-properties-using-the-pagesetupdialog-component.md index 0642bd40e9c31..cb13e80675874 100644 --- a/docs/framework/winforms/controls/how-to-determine-page-properties-using-the-pagesetupdialog-component.md +++ b/docs/framework/winforms/controls/how-to-determine-page-properties-using-the-pagesetupdialog-component.md @@ -32,7 +32,7 @@ The [PageSetupDialog](../../../../docs/framework/winforms/controls/pagesetupdial 1. Use the method to display the dialog box, specifying the to use. - In the example below, the control's event handler opens an instance of the component. An existing document is specified in the property, and its property is set to `false`. + In the example below, the control's event handler opens an instance of the component. An existing document is specified in the property, and its property is set to `false`. The example assumes your form has a control, a component named `myDocument`, and a component. diff --git a/docs/framework/winforms/controls/how-to-develop-a-simple-windows-forms-control.md b/docs/framework/winforms/controls/how-to-develop-a-simple-windows-forms-control.md index 099d03a6a640b..c371a6b8762aa 100644 --- a/docs/framework/winforms/controls/how-to-develop-a-simple-windows-forms-control.md +++ b/docs/framework/winforms/controls/how-to-develop-a-simple-windows-forms-control.md @@ -26,7 +26,7 @@ This section walks you through the key steps for authoring a custom Windows Form ### To create a simple custom control -1. Define a class that derives from . +1. Define a class that derives from . ```vb Public Class FirstControl @@ -74,7 +74,7 @@ This section walks you through the key steps for authoring a custom Windows Form The `/t:library` compiler option tells the compiler that the assembly you are creating is a library (and not an executable). The `/out` option specifies the path and name of the assembly. The`/r` option provides the name of the assemblies that are referenced by your code. In this example, you create a private assembly that only your applications can use. Hence, you have to save it in your application's directory. For more information about packaging and deploying a control for distribution, see [Deployment](../../../../docs/framework/deployment/index.md). - The following sample shows the code for `FirstControl`. The control is enclosed in the namespace `CustomWinControls`. A namespace provides a logical grouping of related types. You can create your control in a new or existing namespace. In C#, the `using` declaration (in Visual Basic, `Imports`) allows types to be accessed from a namespace without using the fully qualified name of the type. In the following example, the `using` declaration allows code to access the class from as simply instead of having to use the fully qualified name . + The following sample shows the code for `FirstControl`. The control is enclosed in the namespace `CustomWinControls`. A namespace provides a logical grouping of related types. You can create your control in a new or existing namespace. In C#, the `using` declaration (in Visual Basic, `Imports`) allows types to be accessed from a namespace without using the fully qualified name of the type. In the following example, the `using` declaration allows code to access the class from as simply instead of having to use the fully qualified name . [!code-csharp[System.Windows.Forms.FirstControl#1](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.FirstControl/CS/FirstControl.cs#1)] [!code-vb[System.Windows.Forms.FirstControl#1](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.FirstControl/VB/FirstControl.vb#1)] diff --git a/docs/framework/winforms/controls/how-to-display-an-insertion-mark-in-a-windows-forms-listview-control.md b/docs/framework/winforms/controls/how-to-display-an-insertion-mark-in-a-windows-forms-listview-control.md index 5b01c420c841a..f2abe4d0d4639 100644 --- a/docs/framework/winforms/controls/how-to-display-an-insertion-mark-in-a-windows-forms-listview-control.md +++ b/docs/framework/winforms/controls/how-to-display-an-insertion-mark-in-a-windows-forms-listview-control.md @@ -26,7 +26,7 @@ manager: "wpickett" The insertion mark in the control shows users the point where dragged items will be inserted. When a user drags an item to a point between two other items, the insertion mark shows the item's expected new location. > [!NOTE] -> The insertion mark feature is available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code relating to the insertion mark has no effect and the insertion mark will not appear. For more information, see . +> The insertion mark feature is available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code relating to the insertion mark has no effect and the insertion mark will not appear. For more information, see . The following image shows an insertion mark: @@ -48,7 +48,7 @@ The insertion mark in the control shows use ## See Also - + [ListView Control](../../../../docs/framework/winforms/controls/listview-control-windows-forms.md) [ListView Control Overview](../../../../docs/framework/winforms/controls/listview-control-overview-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-display-images-in-cells-of-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-display-images-in-cells-of-the-windows-forms-datagridview-control.md index 930bf1c04a1f9..8090bbf7fd146 100644 --- a/docs/framework/winforms/controls/how-to-display-images-in-cells-of-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-display-images-in-cells-of-the-windows-forms-datagridview-control.md @@ -42,7 +42,7 @@ A picture or graphic is one of the values that you can display in a row of data. - An embedded icon resource named `tree.ico`. -- References to the , , and assemblies. +- References to the , , and assemblies. ## See Also diff --git a/docs/framework/winforms/controls/how-to-display-option-buttons-in-a-menustrip-windows-forms.md b/docs/framework/winforms/controls/how-to-display-option-buttons-in-a-menustrip-windows-forms.md index 851a5412953b7..2aa5cba85c3d4 100644 --- a/docs/framework/winforms/controls/how-to-display-option-buttons-in-a-menustrip-windows-forms.md +++ b/docs/framework/winforms/controls/how-to-display-option-buttons-in-a-menustrip-windows-forms.md @@ -88,11 +88,11 @@ Option buttons, also known as radio buttons, are similar to check boxes except t ## See Also - - - - - + + + + + [MenuStrip Control](../../../../docs/framework/winforms/controls/menustrip-control-windows-forms.md) [How to: Implement a Custom ToolStripRenderer](../../../../docs/framework/winforms/controls/how-to-implement-a-custom-toolstriprenderer.md) diff --git a/docs/framework/winforms/controls/how-to-display-web-style-links-with-the-windows-forms-richtextbox-control.md b/docs/framework/winforms/controls/how-to-display-web-style-links-with-the-windows-forms-richtextbox-control.md index 340c633eebd75..2a6997e6e4955 100644 --- a/docs/framework/winforms/controls/how-to-display-web-style-links-with-the-windows-forms-richtextbox-control.md +++ b/docs/framework/winforms/controls/how-to-display-web-style-links-with-the-windows-forms-richtextbox-control.md @@ -37,7 +37,7 @@ The Windows Forms control can display We In the example below, the event opens an instance of Internet Explorer to the URL specified in the property of the control. This example assumes a form with a control. > [!IMPORTANT] - > In calling the method, you will encounter a exception if you are running the code in a partial-trust context because of insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). + > In calling the method, you will encounter a exception if you are running the code in a partial-trust context because of insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). ```vb Public p As New System.Diagnostics.Process diff --git a/docs/framework/winforms/controls/how-to-download-a-file-in-the-background.md b/docs/framework/winforms/controls/how-to-download-a-file-in-the-background.md index 429a01b146520..f9e24acf380b5 100644 --- a/docs/framework/winforms/controls/how-to-download-a-file-in-the-background.md +++ b/docs/framework/winforms/controls/how-to-download-a-file-in-the-background.md @@ -48,14 +48,14 @@ Downloading a file is a common task, and it is often useful to run this potentia If you only want the application to respond to events and do not want to do any work in the main thread while you wait for the background thread to complete, just exit the handler. - If you want to continue doing work in the main thread, use the property to determine whether the thread is still running. In the example, a progress bar is updated while the download is processing. Be sure to call the method to keep the UI responsive. + If you want to continue doing work in the main thread, use the property to determine whether the thread is still running. In the example, a progress bar is updated while the download is processing. Be sure to call the method to keep the UI responsive. [!code-csharp[System.ComponentModel.BackgroundWorker.IsBusy#2](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker.IsBusy/CS/Form1.cs#2)] [!code-vb[System.ComponentModel.BackgroundWorker.IsBusy#2](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker.IsBusy/VB/Form1.vb#2)] **Displaying the result** - The `backgroundWorker1_RunWorkerCompleted` method handles the event and is called when the background operation is completed. This method first checks the property. If is `null`, then this method displays the contents of the file. It then enables the download button, which was disabled when the download began, and it resets the progress bar. + The `backgroundWorker1_RunWorkerCompleted` method handles the event and is called when the background operation is completed. This method first checks the property. If is `null`, then this method displays the contents of the file. It then enables the download button, which was disabled when the download began, and it resets the progress bar. [!code-csharp[System.ComponentModel.BackgroundWorker.IsBusy#4](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker.IsBusy/CS/Form1.cs#4)] [!code-vb[System.ComponentModel.BackgroundWorker.IsBusy#4](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker.IsBusy/VB/Form1.vb#4)] @@ -68,7 +68,7 @@ Downloading a file is a common task, and it is often useful to run this potentia For information about building this example from the command line for [!INCLUDE[vbprvb](../../../../includes/vbprvb-md.md)] or [!INCLUDE[csprcs](../../../../includes/csprcs-md.md)], see [Building from the Command Line](~/docs/visual-basic/reference/command-line-compiler/building-from-the-command-line.md) or [Command-line Building With csc.exe](~/docs/csharp/language-reference/compiler-options/command-line-building-with-csc-exe.md). You can also build this example in [!INCLUDE[vsprvs](../../../../includes/vsprvs-md.md)] by pasting the code into a new project. Also see [How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio](http://msdn.microsoft.com/library/Bb129228\(v=vs.110\)). ## Robust Programming - Always check the property in your event handler before attempting to access the property or any other object that may have been affected by the event handler. + Always check the property in your event handler before attempting to access the property or any other object that may have been affected by the event handler. ## See Also diff --git a/docs/framework/winforms/controls/how-to-enable-check-margins-and-image-margins-in-contextmenustrip-controls.md b/docs/framework/winforms/controls/how-to-enable-check-margins-and-image-margins-in-contextmenustrip-controls.md index 325284c37f3f8..f5f93c74c47b3 100644 --- a/docs/framework/winforms/controls/how-to-enable-check-margins-and-image-margins-in-contextmenustrip-controls.md +++ b/docs/framework/winforms/controls/how-to-enable-check-margins-and-image-margins-in-contextmenustrip-controls.md @@ -34,7 +34,7 @@ You can customize the objects in y [!code-csharp[System.Windows.Forms.ToolStrip.Misc#60](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/CS/Program.cs#60)] [!code-vb[System.Windows.Forms.ToolStrip.Misc#60](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/VB/Program.vb#60)] - Set the and properties to specify when check marks and custom images appear in your menu items. + Set the and properties to specify when check marks and custom images appear in your menu items. ## Compiling the Code This example requires: diff --git a/docs/framework/winforms/controls/how-to-enable-column-reordering-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-enable-column-reordering-in-the-windows-forms-datagridview-control.md index 6a2e69cf2d810..0f2daefa200f5 100644 --- a/docs/framework/winforms/controls/how-to-enable-column-reordering-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-enable-column-reordering-in-the-windows-forms-datagridview-control.md @@ -22,13 +22,13 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Enable Column Reordering in the Windows Forms DataGridView Control -When you enable column reordering in the control, users can move a column to a new position by dragging the column header with the mouse. In the control, the property value determines whether users can move columns to different positions. +When you enable column reordering in the control, users can move a column to a new position by dragging the column header with the mouse. In the control, the property value determines whether users can move columns to different positions. There is support for this task in Visual Studio. Also see [How to: Enable Column Reordering in the Windows Forms DataGridView Control Using the Designer](http://msdn.microsoft.com/library/8xwtyc86\(v=vs.110\)) ### To enable column reordering programmatically -- Set the property to `true`. +- Set the property to `true`. [!code-csharp[System.Windows.Forms.DataGridViewMisc#060](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#060)] [!code-vb[System.Windows.Forms.DataGridViewMisc#060](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#060)] @@ -38,10 +38,10 @@ When you enable column reordering in the control named `dataGridView1`. -- References to the and assemblies. +- References to the and assemblies. ## See Also - + [Basic Column, Row, and Cell Features in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-column-row-and-cell-features-wf-datagridview-control.md) [How to: Freeze Columns in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-freeze-columns-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-enable-tile-view-in-a-windows-forms-listview-control.md b/docs/framework/winforms/controls/how-to-enable-tile-view-in-a-windows-forms-listview-control.md index 2f7932d54402d..4f2b4cad86b2e 100644 --- a/docs/framework/winforms/controls/how-to-enable-tile-view-in-a-windows-forms-listview-control.md +++ b/docs/framework/winforms/controls/how-to-enable-tile-view-in-a-windows-forms-listview-control.md @@ -33,7 +33,7 @@ Tile view icons and text To enable tile view, set the property to . You can adjust the size of the tiles by setting the property, and the number of text lines displayed in the tile by adjusting the collection. > [!NOTE] -> The tile view is available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code related to the tile view has no effect, and the control displays in the large icon view. For more information, see . +> The tile view is available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code related to the tile view has no effect, and the control displays in the large icon view. For more information, see . ### To set tile view programmatically diff --git a/docs/framework/winforms/controls/how-to-format-data-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-format-data-in-the-windows-forms-datagridview-control.md index 8e082b6b2f6e2..5fe79e7fb63e4 100644 --- a/docs/framework/winforms/controls/how-to-format-data-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-format-data-in-the-windows-forms-datagridview-control.md @@ -39,14 +39,14 @@ The following procedures demonstrate basic formatting of cell values using the < ### To customize the display of null database values -- Set the property of a . The following code example uses the property to display "no entry" in all cells containing values equal to . +- Set the property of a . The following code example uses the property to display "no entry" in all cells containing values equal to . [!code-csharp[System.Windows.Forms.DataGridViewMisc#073](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#073)] [!code-vb[System.Windows.Forms.DataGridViewMisc#073](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#073)] ### To enable wordwrap in text-based cells -- Set the property of a to one of the enumeration values. The following code example uses the property to set the wrap mode for the entire control. +- Set the property of a to one of the enumeration values. The following code example uses the property to set the wrap mode for the entire control. [!code-csharp[System.Windows.Forms.DataGridViewMisc#074](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#074)] [!code-vb[System.Windows.Forms.DataGridViewMisc#074](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#074)] @@ -67,14 +67,14 @@ The following procedures demonstrate basic formatting of cell values using the < - A control named `dataGridView1` that contains a column named `UnitPrice`, a column named `ShipDate`, and a column named `CustomerName`. -- References to the , , and assemblies. +- References to the , , and assemblies. ## Robust Programming For maximum scalability, you should share objects across multiple rows, columns, or cells that use the same styles rather than setting the style properties for each element separately. For more information, see [Best Practices for Scaling the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md). ## See Also - - + + [Basic Formatting and Styling in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-formatting-and-styling-in-the-windows-forms-datagridview-control.md) [Cell Styles in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-freeze-columns-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-freeze-columns-in-the-windows-forms-datagridview-control.md index 3be5105a02e53..ba0944c00c622 100644 --- a/docs/framework/winforms/controls/how-to-freeze-columns-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-freeze-columns-in-the-windows-forms-datagridview-control.md @@ -35,7 +35,7 @@ When users view data displayed in a Windows Forms property to `true`. +- Set the property to `true`. [!code-csharp[System.Windows.Forms.DataGridViewMisc#061](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#061)] [!code-vb[System.Windows.Forms.DataGridViewMisc#061](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#061)] @@ -45,10 +45,10 @@ When users view data displayed in a Windows Forms control named `dataGridView1` that contains a column named `AddToCartButton`. -- References to the and assemblies. +- References to the and assemblies. ## See Also - + [Basic Column, Row, and Cell Features in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-column-row-and-cell-features-wf-datagridview-control.md) [How to: Enable Column Reordering in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-enable-column-reordering-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-group-items-in-a-windows-forms-listview-control-using-the-designer.md b/docs/framework/winforms/controls/how-to-group-items-in-a-windows-forms-listview-control-using-the-designer.md index 385975c8621b5..0d57b8d0e00b0 100644 --- a/docs/framework/winforms/controls/how-to-group-items-in-a-windows-forms-listview-control-using-the-designer.md +++ b/docs/framework/winforms/controls/how-to-group-items-in-a-windows-forms-listview-control-using-the-designer.md @@ -31,7 +31,7 @@ The grouping feature of the control enables To enable grouping, you must first create one or more objects either in the designer or programmatically. Once a group has been defined, you can assign items to it. > [!NOTE] -> groups are available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code relating to groups has no effect and the groups will not appear. For more information, see . +> groups are available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code relating to groups has no effect and the groups will not appear. For more information, see . > > The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose **Import and Export Settings** on the **Tools** menu. For more information, see [Customizing Development Settings in Visual Studio](http://msdn.microsoft.com/en-us/22c4debb-4e31-47a8-8f19-16f328d7dcd3). diff --git a/docs/framework/winforms/controls/how-to-group-items-in-a-windows-forms-listview-control.md b/docs/framework/winforms/controls/how-to-group-items-in-a-windows-forms-listview-control.md index 7f2e701f8b718..e4d3df63a7785 100644 --- a/docs/framework/winforms/controls/how-to-group-items-in-a-windows-forms-listview-control.md +++ b/docs/framework/winforms/controls/how-to-group-items-in-a-windows-forms-listview-control.md @@ -33,7 +33,7 @@ ListView grouped items To enable grouping, you must first create one or more groups either in the designer or programmatically. After a group has been defined, you can assign items to groups. You can also move items from one group to another programmatically. > [!NOTE] -> groups are available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code relating to groups has no effect and the groups will not appear. For more information, see . +> groups are available only on [!INCLUDE[WinXpFamily](../../../../includes/winxpfamily-md.md)] when your application calls the method. On earlier operating systems, any code relating to groups has no effect and the groups will not appear. For more information, see . ### To add groups @@ -56,14 +56,14 @@ ListView grouped items ### To assign items to groups or move items between groups -1. Set the property of individual items. +1. Set the property of individual items. [!code-csharp[System.Windows.Forms.ListViewLegacyTopics#23](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.ListViewLegacyTopics/CS/Class1.cs#23)] [!code-vb[System.Windows.Forms.ListViewLegacyTopics#23](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.ListViewLegacyTopics/VB/Class1.vb#23)] ## See Also - + [ListView Control](../../../../docs/framework/winforms/controls/listview-control-windows-forms.md) [ListView Control Overview](../../../../docs/framework/winforms/controls/listview-control-overview-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-handle-errors-and-exceptions-that-occur-with-databinding.md b/docs/framework/winforms/controls/how-to-handle-errors-and-exceptions-that-occur-with-databinding.md index d0401847af3fa..e150c1b68fecf 100644 --- a/docs/framework/winforms/controls/how-to-handle-errors-and-exceptions-that-occur-with-databinding.md +++ b/docs/framework/winforms/controls/how-to-handle-errors-and-exceptions-that-occur-with-databinding.md @@ -28,13 +28,13 @@ manager: "wpickett" Oftentimes exceptions and errors occur on the underlying business objects when you bind them to controls. You can intercept these errors and exceptions and then either recover or pass the error information to the user by handling the event for a particular , , or component. ## Example - This code example demonstrates how to handle errors and exceptions that occur during a data-binding operation. It demonstrates how to intercept errors by handling the event of the objects. In order to intercept errors and exceptions by handling this event, you must enable formatting for the binding. You can enable formatting when the binding is constructed or added to the binding collection, or by setting the property to `true`. + This code example demonstrates how to handle errors and exceptions that occur during a data-binding operation. It demonstrates how to intercept errors by handling the event of the objects. In order to intercept errors and exceptions by handling this event, you must enable formatting for the binding. You can enable formatting when the binding is constructed or added to the binding collection, or by setting the property to `true`. [!code-cpp[System.Windows.Forms.DataConnectorBindingComplete#3](../../../../samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataConnectorBindingComplete/CPP/form1.cpp#3)] [!code-csharp[System.Windows.Forms.DataConnectorBindingComplete#3](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataConnectorBindingComplete/CS/form1.cs#3)] [!code-vb[System.Windows.Forms.DataConnectorBindingComplete#3](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataConnectorBindingComplete/VB/form1.vb#3)] - When the code is running and an empty string is entered for the part name or a value less than 100 is entered for the part number, a message box appears. This is a result of handling the event for these textbox bindings. + When the code is running and an empty string is entered for the part name or a value less than 100 is entered for the part number, a message box appears. This is a result of handling the event for these textbox bindings. ## Compiling the Code This example requires: @@ -44,6 +44,6 @@ Oftentimes exceptions and errors occur on the underlying business objects when y For information about building this example from the command line for [!INCLUDE[vbprvb](../../../../includes/vbprvb-md.md)] or [!INCLUDE[csprcs](../../../../includes/csprcs-md.md)], see [Building from the Command Line](~/docs/visual-basic/reference/command-line-compiler/building-from-the-command-line.md) or [Command-line Building With csc.exe](~/docs/csharp/language-reference/compiler-options/command-line-building-with-csc-exe.md). You can also build this example in [!INCLUDE[vsprvs](../../../../includes/vsprvs-md.md)] by pasting the code into a new project. Also see [How to: Compile and Run a Complete Windows Forms Code Example Using Visual Studio](http://msdn.microsoft.com/library/Bb129228\(v=vs.110\)). ## See Also - - + + [BindingSource Component](../../../../docs/framework/winforms/controls/bindingsource-component.md) diff --git a/docs/framework/winforms/controls/how-to-handle-the-contextmenustrip-opening-event.md b/docs/framework/winforms/controls/how-to-handle-the-contextmenustrip-opening-event.md index c98e3e375d89b..02e646b1abb12 100644 --- a/docs/framework/winforms/controls/how-to-handle-the-contextmenustrip-opening-event.md +++ b/docs/framework/winforms/controls/how-to-handle-the-contextmenustrip-opening-event.md @@ -32,7 +32,7 @@ You can customize the behavior of your property to `true` to prevent the menu from opening. + Set the property to `true` to prevent the menu from opening. ## See Also diff --git a/docs/framework/winforms/controls/how-to-hide-column-headers-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-hide-column-headers-in-the-windows-forms-datagridview-control.md index b34d3aa5b05b2..91bc8a9f7a9e6 100644 --- a/docs/framework/winforms/controls/how-to-hide-column-headers-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-hide-column-headers-in-the-windows-forms-datagridview-control.md @@ -26,7 +26,7 @@ Sometimes you will want to display a wi ### To hide the column headers -- Set the property to `false`. +- Set the property to `false`. [!code-csharp[System.Windows.Forms.DataGridViewMisc#062](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#062)] [!code-vb[System.Windows.Forms.DataGridViewMisc#062](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#062)] @@ -36,9 +36,9 @@ Sometimes you will want to display a wi - A control named `dataGridView1`. -- References to the and assemblies. +- References to the and assemblies. ## See Also - + [Basic Column, Row, and Cell Features in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-column-row-and-cell-features-wf-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-hide-columns-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-hide-columns-in-the-windows-forms-datagridview-control.md index abbb4ebdc58bb..2d445c85d97cf 100644 --- a/docs/framework/winforms/controls/how-to-hide-columns-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-hide-columns-in-the-windows-forms-datagridview-control.md @@ -30,7 +30,7 @@ Sometimes you will want to display only some of the columns that are available i ### To hide a column programmatically -- Set the property to `false`. To hide a `CustomerID` column that is automatically generated during data binding, place the following code example in a event handler. +- Set the property to `false`. To hide a `CustomerID` column that is automatically generated during data binding, place the following code example in a event handler. [!code-csharp[System.Windows.Forms.DataGridViewMisc#063](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#063)] [!code-vb[System.Windows.Forms.DataGridViewMisc#063](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#063)] @@ -40,11 +40,11 @@ Sometimes you will want to display only some of the columns that are available i - A control named `dataGridView1` that contains a column named `CustomerID`. -- References to the and assemblies. +- References to the and assemblies. ## See Also - + [Basic Column, Row, and Cell Features in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-column-row-and-cell-features-wf-datagridview-control.md) [How to: Remove Autogenerated Columns from a Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/remove-autogenerated-columns-from-a-wf-datagridview-control.md) [How to: Change the Order of Columns in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-change-the-order-of-columns-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-implement-a-custom-layout-engine.md b/docs/framework/winforms/controls/how-to-implement-a-custom-layout-engine.md index bbd0eb38c893c..198032a5ae719 100644 --- a/docs/framework/winforms/controls/how-to-implement-a-custom-layout-engine.md +++ b/docs/framework/winforms/controls/how-to-implement-a-custom-layout-engine.md @@ -33,4 +33,4 @@ The following code example demonstrates how to create a custom layout engine tha ## See Also - + diff --git a/docs/framework/winforms/controls/how-to-insert-a-menustrip-into-an-mdi-drop-down-menu-windows-forms.md b/docs/framework/winforms/controls/how-to-insert-a-menustrip-into-an-mdi-drop-down-menu-windows-forms.md index 8171be2b6bf6b..51856d0978620 100644 --- a/docs/framework/winforms/controls/how-to-insert-a-menustrip-into-an-mdi-drop-down-menu-windows-forms.md +++ b/docs/framework/winforms/controls/how-to-insert-a-menustrip-into-an-mdi-drop-down-menu-windows-forms.md @@ -98,7 +98,7 @@ In some applications, the kind of a multiple-document interface (MDI) child wind - A control on `Form1` named `menuStrip1`, and a control on `Form2` named `menuStrip2`. -- References to the and assemblies. +- References to the and assemblies. ## See Also [How to: Create MDI Parent Forms](../../../../docs/framework/winforms/advanced/how-to-create-mdi-parent-forms.md) diff --git a/docs/framework/winforms/controls/how-to-load-files-into-the-windows-forms-richtextbox-control.md b/docs/framework/winforms/controls/how-to-load-files-into-the-windows-forms-richtextbox-control.md index 50de7549a007d..8163db34edeeb 100644 --- a/docs/framework/winforms/controls/how-to-load-files-into-the-windows-forms-richtextbox-control.md +++ b/docs/framework/winforms/controls/how-to-load-files-into-the-windows-forms-richtextbox-control.md @@ -82,10 +82,10 @@ The Windows Forms control can display a ``` > [!IMPORTANT] - > To run this process, your assembly may require a privilege level granted by the class. If you are running in a partial-trust context, the process might throw an exception because of insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). + > To run this process, your assembly may require a privilege level granted by the class. If you are running in a partial-trust context, the process might throw an exception because of insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). ## See Also - + [RichTextBox Control](../../../../docs/framework/winforms/controls/richtextbox-control-windows-forms.md) [Controls to Use on Windows Forms](../../../../docs/framework/winforms/controls/controls-to-use-on-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-make-columns-read-only-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-make-columns-read-only-in-the-windows-forms-datagridview-control.md index 8b79fdd72e4c6..544f66683bf84 100644 --- a/docs/framework/winforms/controls/how-to-make-columns-read-only-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-make-columns-read-only-in-the-windows-forms-datagridview-control.md @@ -27,7 +27,7 @@ Not all data is meant for editing. In the property to `true`. +- Set the property to `true`. [!code-csharp[System.Windows.Forms.DataGridViewMisc#064](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#064)] [!code-vb[System.Windows.Forms.DataGridViewMisc#064](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#064)] @@ -37,11 +37,11 @@ Not all data is meant for editing. In the control named `dataGridView1` with a column named `CompanyName`. -- References to the and assemblies. +- References to the and assemblies. ## See Also - - + + [Basic Column, Row, and Cell Features in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-column-row-and-cell-features-wf-datagridview-control.md) [How to: Prevent Row Addition and Deletion in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/prevent-row-addition-and-deletion-datagridview.md) diff --git a/docs/framework/winforms/controls/how-to-manage-toolstrip-overflow-in-windows-forms.md b/docs/framework/winforms/controls/how-to-manage-toolstrip-overflow-in-windows-forms.md index a3c5628bd0628..44550fee4a41b 100644 --- a/docs/framework/winforms/controls/how-to-manage-toolstrip-overflow-in-windows-forms.md +++ b/docs/framework/winforms/controls/how-to-manage-toolstrip-overflow-in-windows-forms.md @@ -26,7 +26,7 @@ manager: "wpickett" # How to: Manage ToolStrip Overflow in Windows Forms When all the items on a control do not fit in the allotted space, you can enable overflow functionality on the and determine the overflow behavior of specific s. - When you add s that require more space than is allotted to the given the form's current size, a automatically appears on the . The appears, and overflow-enabled items are moved into the drop-down overflow menu. This allows you to customize and prioritize how your items properly adjust to different form sizes. You can also change the appearance of your items when they fall into the overflow by using the and properties and the event. If you enlarge the form at either design time or run time, more s can be displayed on the main and the might even disappear until you decrease the size of the form. + When you add s that require more space than is allotted to the given the form's current size, a automatically appears on the . The appears, and overflow-enabled items are moved into the drop-down overflow menu. This allows you to customize and prioritize how your items properly adjust to different form sizes. You can also change the appearance of your items when they fall into the overflow by using the and properties and the event. If you enlarge the form at either design time or run time, more s can be displayed on the main and the might even disappear until you decrease the size of the form. ### To enable overflow on a ToolStrip control diff --git a/docs/framework/winforms/controls/how-to-navigate-to-a-url-with-the-webbrowser-control.md b/docs/framework/winforms/controls/how-to-navigate-to-a-url-with-the-webbrowser-control.md index bda23dc182938..7d3213bc61b1c 100644 --- a/docs/framework/winforms/controls/how-to-navigate-to-a-url-with-the-webbrowser-control.md +++ b/docs/framework/winforms/controls/how-to-navigate-to-a-url-with-the-webbrowser-control.md @@ -48,8 +48,8 @@ this.webBrowser1.Navigate("http://www.microsoft.com"); ## See Also - - - + + + [WebBrowser Control](../../../../docs/framework/winforms/controls/webbrowser-control-windows-forms.md) [How to: Print with a WebBrowser Control](../../../../docs/framework/winforms/controls/how-to-print-with-a-webbrowser-control.md) diff --git a/docs/framework/winforms/controls/how-to-open-files-using-the-openfiledialog-component.md b/docs/framework/winforms/controls/how-to-open-files-using-the-openfiledialog-component.md index 5381ff6410dfa..ef16c37b69e95 100644 --- a/docs/framework/winforms/controls/how-to-open-files-using-the-openfiledialog-component.md +++ b/docs/framework/winforms/controls/how-to-open-files-using-the-openfiledialog-component.md @@ -38,7 +38,7 @@ The component allows users to browse The example below uses the control's event handler to open an instance of the component. When a file is chosen and the user clicks **OK**, the file selected in the dialog box opens. In this case, the contents are displayed in a message box, just to show that the file stream has been read. > [!IMPORTANT] - > To get or set the property, your assembly requires a privilege level granted by the class. If you are running in a partial-trust context, the process might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). + > To get or set the property, your assembly requires a privilege level granted by the class. If you are running in a partial-trust context, the process might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). The example assumes your form has a control and an component. @@ -102,7 +102,7 @@ The component allows users to browse The component's method returns the bytes that compose the file. These bytes give you a stream to read from. In the example below, an component is instantiated with a "cursor" filter on it, allowing the user to choose only files with the file name extension`.cur`. If a`.cur` file is chosen, the form's cursor is set to the selected cursor. > [!IMPORTANT] - > To call the method, your assembly requires a privilege level granted by the class. If you are running in a partial-trust context, the process might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). + > To call the method, your assembly requires a privilege level granted by the class. If you are running in a partial-trust context, the process might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). The example assumes your form has a control. diff --git a/docs/framework/winforms/controls/how-to-play-a-beep-from-a-windows-form.md b/docs/framework/winforms/controls/how-to-play-a-beep-from-a-windows-form.md index 861a5944c2609..b2b0ee2001da2 100644 --- a/docs/framework/winforms/controls/how-to-play-a-beep-from-a-windows-form.md +++ b/docs/framework/winforms/controls/how-to-play-a-beep-from-a-windows-form.md @@ -45,7 +45,7 @@ public void onePing() > The sound played in the C# code sample is determined by the system sound setting. For more information, see . ## Compiling the Code - For C#, this example requires a reference to the namespace. + For C#, this example requires a reference to the namespace. ## See Also diff --git a/docs/framework/winforms/controls/how-to-play-a-sound-embedded-in-a-resource-from-a-windows-form.md b/docs/framework/winforms/controls/how-to-play-a-sound-embedded-in-a-resource-from-a-windows-form.md index 2e16cecab87a0..6c244454c947a 100644 --- a/docs/framework/winforms/controls/how-to-play-a-sound-embedded-in-a-resource-from-a-windows-form.md +++ b/docs/framework/winforms/controls/how-to-play-a-sound-embedded-in-a-resource-from-a-windows-form.md @@ -32,7 +32,7 @@ You can use the class to play a sound from an em ## Compiling the Code This example requires: - Importing the namespace. + Importing the namespace. Including the sound file as an embedded resource in your project. diff --git a/docs/framework/winforms/controls/how-to-play-a-sound-from-a-windows-form.md b/docs/framework/winforms/controls/how-to-play-a-sound-from-a-windows-form.md index 7f2c3a5d8c5ba..a56b9653f7762 100644 --- a/docs/framework/winforms/controls/how-to-play-a-sound-from-a-windows-form.md +++ b/docs/framework/winforms/controls/how-to-play-a-sound-from-a-windows-form.md @@ -48,7 +48,7 @@ private void playSimpleSound() - That you replace the file name `"c:\Windows\Media\chimes.wav"` with a valid file name. -- (C#) A reference to the namespace. +- (C#) A reference to the namespace. ## Robust Programming File operations should be enclosed within appropriate structured exception handling blocks. diff --git a/docs/framework/winforms/controls/how-to-play-a-system-sound-from-a-windows-form.md b/docs/framework/winforms/controls/how-to-play-a-system-sound-from-a-windows-form.md index bcd4496a53cd7..6525760d385cb 100644 --- a/docs/framework/winforms/controls/how-to-play-a-system-sound-from-a-windows-form.md +++ b/docs/framework/winforms/controls/how-to-play-a-system-sound-from-a-windows-form.md @@ -46,7 +46,7 @@ public void playExclamation() ## Compiling the Code This example requires: -- A reference to the namespace. +- A reference to the namespace. ## See Also diff --git a/docs/framework/winforms/controls/how-to-remove-a-toolstripmenuitem-from-an-mdi-drop-down-menu-windows-forms.md b/docs/framework/winforms/controls/how-to-remove-a-toolstripmenuitem-from-an-mdi-drop-down-menu-windows-forms.md index c9e547e90335e..05bc82c60ff02 100644 --- a/docs/framework/winforms/controls/how-to-remove-a-toolstripmenuitem-from-an-mdi-drop-down-menu-windows-forms.md +++ b/docs/framework/winforms/controls/how-to-remove-a-toolstripmenuitem-from-an-mdi-drop-down-menu-windows-forms.md @@ -97,7 +97,7 @@ In some applications, the kind of a multiple-document interface (MDI) child wind - A control on `Form1` named `menuStrip1`, and a control on `Form2` named `menuStrip2`. -- References to the and assemblies. +- References to the and assemblies. ## See Also [How to: Create MDI Parent Forms](../../../../docs/framework/winforms/advanced/how-to-create-mdi-parent-forms.md) diff --git a/docs/framework/winforms/controls/how-to-remove-items-from-windows-forms-domainupdown-controls.md b/docs/framework/winforms/controls/how-to-remove-items-from-windows-forms-domainupdown-controls.md index bd953f8966892..cfdb3b8ba0bdd 100644 --- a/docs/framework/winforms/controls/how-to-remove-items-from-windows-forms-domainupdown-controls.md +++ b/docs/framework/winforms/controls/how-to-remove-items-from-windows-forms-domainupdown-controls.md @@ -60,7 +60,7 @@ You can remove items from the Windows Forms - - + + [DomainUpDown Control](../../../../docs/framework/winforms/controls/domainupdown-control-windows-forms.md) [DomainUpDown Control Overview](../../../../docs/framework/winforms/controls/domainupdown-control-overview-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-render-a-visual-style-element.md b/docs/framework/winforms/controls/how-to-render-a-visual-style-element.md index 94591fde47cf3..8b3ae7a764f52 100644 --- a/docs/framework/winforms/controls/how-to-render-a-visual-style-element.md +++ b/docs/framework/winforms/controls/how-to-render-a-visual-style-element.md @@ -22,11 +22,11 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Render a Visual Style Element -The namespace exposes objects that represent the Windows user interface (UI) elements supported by visual styles. This topic demonstrates how to use the class to render the that represents the **Log Off** and **Shut Down** buttons of the Start menu. +The namespace exposes objects that represent the Windows user interface (UI) elements supported by visual styles. This topic demonstrates how to use the class to render the that represents the **Log Off** and **Shut Down** buttons of the Start menu. ### To render a visual style element -1. Create a and set it to the element you want to draw. Note the use of the property and the method; the constructor will throw an exception if visual styles are disabled or an element is undefined. +1. Create a and set it to the element you want to draw. Note the use of the property and the method; the constructor will throw an exception if visual styles are disabled or an element is undefined. [!code-cpp[System.Windows.Forms.VisualStyles.VisualStyleRenderer_Simple#4](../../../../samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.VisualStyles.VisualStyleRenderer_Simple/cpp/form1.cpp#4)] [!code-csharp[System.Windows.Forms.VisualStyles.VisualStyleRenderer_Simple#4](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.VisualStyles.VisualStyleRenderer_Simple/CS/form1.cs#4)] @@ -45,7 +45,7 @@ The namespace - A that hosts the custom control. -- References to the , , , and namespaces. +- References to the , , , and namespaces. ## See Also [Rendering Controls with Visual Styles](../../../../docs/framework/winforms/controls/rendering-controls-with-visual-styles.md) diff --git a/docs/framework/winforms/controls/how-to-save-files-using-the-savefiledialog-component.md b/docs/framework/winforms/controls/how-to-save-files-using-the-savefiledialog-component.md index ab2eed33b663b..b5d751e6ea5ae 100644 --- a/docs/framework/winforms/controls/how-to-save-files-using-the-savefiledialog-component.md +++ b/docs/framework/winforms/controls/how-to-save-files-using-the-savefiledialog-component.md @@ -36,7 +36,7 @@ The component allows users to browse In the example below, there is a control with an image assigned to it. When you click the button, a component is instantiated with a filter that allows files of type .gif, .jpeg, and .bmp. If a file of this type is selected in the Save File dialog box, the button's image is saved. > [!IMPORTANT] - > To get or set the property, your assembly requires a privilege level granted by the class. If you are running in a partial-trust context, the process might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). + > To get or set the property, your assembly requires a privilege level granted by the class. If you are running in a partial-trust context, the process might throw an exception due to insufficient privileges. For more information, see [Code Access Security Basics](../../../../docs/framework/misc/code-access-security-basics.md). The example assumes your form has a control with its property set to a file of type .gif, .jpeg, or .bmp. diff --git a/docs/framework/winforms/controls/how-to-save-files-with-the-windows-forms-richtextbox-control.md b/docs/framework/winforms/controls/how-to-save-files-with-the-windows-forms-richtextbox-control.md index 8616a1480e81b..041181bb509b7 100644 --- a/docs/framework/winforms/controls/how-to-save-files-with-the-windows-forms-richtextbox-control.md +++ b/docs/framework/winforms/controls/how-to-save-files-with-the-windows-forms-richtextbox-control.md @@ -92,7 +92,7 @@ The Windows Forms control can write the > This example creates a new file, if the file does not already exist. If an application needs to create a file, that application needs Create access for the folder. Permissions are set using access control lists. If the file already exists, the application needs only Write access, a lesser privilege. Where possible, it is more secure to create the file during deployment, and only grant Read access to a single file, rather than Create access for a folder. Also, it is more secure to write data to user folders than to the root folder or the Program Files folder. ## See Also - + [RichTextBox Control](../../../../docs/framework/winforms/controls/richtextbox-control-windows-forms.md) [Controls to Use on Windows Forms](../../../../docs/framework/winforms/controls/controls-to-use-on-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-select-an-item-in-the-windows-forms-listview-control.md b/docs/framework/winforms/controls/how-to-select-an-item-in-the-windows-forms-listview-control.md index 97e6c72309364..291ade7eebfdc 100644 --- a/docs/framework/winforms/controls/how-to-select-an-item-in-the-windows-forms-listview-control.md +++ b/docs/framework/winforms/controls/how-to-select-an-item-in-the-windows-forms-listview-control.md @@ -34,8 +34,8 @@ This example demonstrates how to programmatically select an item in a Windows Fo - A control named `listView1` that contains at least one item. -- References to the and namespaces. +- References to the and namespaces. ## See Also - + diff --git a/docs/framework/winforms/controls/how-to-set-alternating-row-styles-for-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-set-alternating-row-styles-for-the-windows-forms-datagridview-control.md index cbbfcc55f7b19..ff5e12978989e 100644 --- a/docs/framework/winforms/controls/how-to-set-alternating-row-styles-for-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-set-alternating-row-styles-for-the-windows-forms-datagridview-control.md @@ -43,14 +43,14 @@ Tabular data is often presented to users in a ledger-like format where alternati - A control named `dataGridView1`. -- References to the , , and assemblies. +- References to the , , and assemblies. ## Robust Programming For maximum scalability, you should share objects across multiple rows, columns, or cells that use the same styles, rather than setting the style properties for each element separately. For more information, see [Best Practices for Scaling the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md). ## See Also - - + + [Basic Formatting and Styling in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-formatting-and-styling-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-set-default-cell-styles-for-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-set-default-cell-styles-for-the-windows-forms-datagridview-control.md index bb85f721f929a..f46e2e06dfa2e 100644 --- a/docs/framework/winforms/controls/how-to-set-default-cell-styles-for-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-set-default-cell-styles-for-the-windows-forms-datagridview-control.md @@ -28,7 +28,7 @@ With the control, you can specify defau ### To set the default cell styles programmatically -1. Set the properties of the retrieved through the property. +1. Set the properties of the retrieved through the property. [!code-csharp[System.Windows.Forms.DataGridViewMisc#141](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#141)] [!code-vb[System.Windows.Forms.DataGridViewMisc#141](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#141)] @@ -52,16 +52,16 @@ With the control, you can specify defau - A control named `dataGridView1`. -- References to the , , and assemblies. +- References to the , , and assemblies. ## Robust Programming - To achieve maximum scalability when you work with very large data sets, you should share objects across multiple rows, columns, or cells that use the same styles, rather than set the style properties for individual elements separately. Additionally, you should create shared rows and access them by using the property. For more information, see [Best Practices for Scaling the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md). + To achieve maximum scalability when you work with very large data sets, you should share objects across multiple rows, columns, or cells that use the same styles, rather than set the style properties for individual elements separately. Additionally, you should create shared rows and access them by using the property. For more information, see [Best Practices for Scaling the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md). ## See Also - - + + [Basic Formatting and Styling in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-formatting-and-styling-in-the-windows-forms-datagridview-control.md) [Cell Styles in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md) [Best Practices for Scaling the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-set-font-and-color-styles-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-set-font-and-color-styles-in-the-windows-forms-datagridview-control.md index 9e27370401396..f15565feb722e 100644 --- a/docs/framework/winforms/controls/how-to-set-font-and-color-styles-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-set-font-and-color-styles-in-the-windows-forms-datagridview-control.md @@ -31,21 +31,21 @@ You can specify the visual appearance of cells within a property of a . The following code example uses the property to set the font for the entire control. +- Set the property of a . The following code example uses the property to set the font for the entire control. [!code-csharp[System.Windows.Forms.DataGridViewMisc#101](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#101)] [!code-vb[System.Windows.Forms.DataGridViewMisc#101](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#101)] ### To specify the foreground and background colors of DataGridView cells -- Set the and properties of a . The following code example uses the property to set these styles for the entire control. +- Set the and properties of a . The following code example uses the property to set these styles for the entire control. [!code-csharp[System.Windows.Forms.DataGridViewMisc#102](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#102)] [!code-vb[System.Windows.Forms.DataGridViewMisc#102](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#102)] ### To specify the foreground and background colors of selected DataGridView cells -- Set the and properties of a . The following code example uses the property to set these styles for the entire control. +- Set the and properties of a . The following code example uses the property to set these styles for the entire control. [!code-csharp[System.Windows.Forms.DataGridViewMisc#103](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#103)] [!code-vb[System.Windows.Forms.DataGridViewMisc#103](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#103)] @@ -59,13 +59,13 @@ You can specify the visual appearance of cells within a control named `dataGridView1`. -- References to the , , and assemblies. +- References to the , , and assemblies. ## Robust Programming For maximum scalability, you should share objects across multiple rows, columns, or cells that use the same styles, rather than setting the style properties for each element separately. For more information, see [Best Practices for Scaling the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md). ## See Also - + [Basic Formatting and Styling in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-formatting-and-styling-in-the-windows-forms-datagridview-control.md) [Cell Styles in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-set-icons-for-the-windows-forms-treeview-control.md b/docs/framework/winforms/controls/how-to-set-icons-for-the-windows-forms-treeview-control.md index 671a2b4b03204..3d3ae10491be7 100644 --- a/docs/framework/winforms/controls/how-to-set-icons-for-the-windows-forms-treeview-control.md +++ b/docs/framework/winforms/controls/how-to-set-icons-for-the-windows-forms-treeview-control.md @@ -27,7 +27,7 @@ manager: "wpickett" The Windows Forms control can display icons next to each node. The icons are positioned to the immediate left of the node text. To display these icons, you must associate the tree view with an control. For more information about image lists, see [ImageList Component](../../../../docs/framework/winforms/controls/imagelist-component-windows-forms.md) and [How to: Add or Remove Images with the Windows Forms ImageList Component](../../../../docs/framework/winforms/controls/how-to-add-or-remove-images-with-the-windows-forms-imagelist-component.md). > [!NOTE] -> A bug in Microsoft .NET Framework version 1.1 prevents images from appearing on nodes when your application calls . To work around this bug, call in your `Main` method immediately after calling . This bug is fixed in [!INCLUDE[dnprdnlong](../../../../includes/dnprdnlong-md.md)]. +> A bug in Microsoft .NET Framework version 1.1 prevents images from appearing on nodes when your application calls . To work around this bug, call in your `Main` method immediately after calling . This bug is fixed in [!INCLUDE[dnprdnlong](../../../../includes/dnprdnlong-md.md)]. ### To display images in a tree view diff --git a/docs/framework/winforms/controls/how-to-set-pictures-at-run-time-windows-forms.md b/docs/framework/winforms/controls/how-to-set-pictures-at-run-time-windows-forms.md index 9af9310538e11..1121e6332194d 100644 --- a/docs/framework/winforms/controls/how-to-set-pictures-at-run-time-windows-forms.md +++ b/docs/framework/winforms/controls/how-to-set-pictures-at-run-time-windows-forms.md @@ -103,7 +103,7 @@ You can programmatically set the image displayed by a Windows Forms - + [PictureBox Control Overview](../../../../docs/framework/winforms/controls/picturebox-control-overview-windows-forms.md) [How to: Load a Picture Using the Designer](../../../../docs/framework/winforms/controls/how-to-load-a-picture-using-the-designer-windows-forms.md) [How to: Modify the Size or Placement of a Picture at Run Time](../../../../docs/framework/winforms/controls/how-to-modify-the-size-or-placement-of-a-picture-at-run-time-windows-forms.md) diff --git a/docs/framework/winforms/controls/how-to-set-the-background-of-a-windows-forms-panel.md b/docs/framework/winforms/controls/how-to-set-the-background-of-a-windows-forms-panel.md index 011ac720ab94c..0917d3ad5b706 100644 --- a/docs/framework/winforms/controls/how-to-set-the-background-of-a-windows-forms-panel.md +++ b/docs/framework/winforms/controls/how-to-set-the-background-of-a-windows-forms-panel.md @@ -27,7 +27,7 @@ A Windows Forms control can display both a bac ### To set the background programmatically -1. Set the panel's property to a value of type . +1. Set the panel's property to a value of type . ```vb Panel1.BackColor = Color.AliceBlue @@ -41,7 +41,7 @@ A Windows Forms control can display both a bac panel1->BackColor = Color::AliceBlue; ``` -2. Set the panel's property using the method of the class. +2. Set the panel's property using the method of the class. ```vb ' You should replace the bolded image diff --git a/docs/framework/winforms/controls/how-to-set-the-selection-mode-of-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-set-the-selection-mode-of-the-windows-forms-datagridview-control.md index a0690fdf549a2..8a8502a79ca60 100644 --- a/docs/framework/winforms/controls/how-to-set-the-selection-mode-of-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-set-the-selection-mode-of-the-windows-forms-datagridview-control.md @@ -33,7 +33,7 @@ The following code example demonstrates how to configure a control named `dataGridView1`. -- References to the and assemblies. +- References to the and assemblies. ## See Also diff --git a/docs/framework/winforms/controls/how-to-set-the-sizing-modes-of-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-set-the-sizing-modes-of-the-windows-forms-datagridview-control.md index feae1abcef133..7dec9fd37832c 100644 --- a/docs/framework/winforms/controls/how-to-set-the-sizing-modes-of-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-set-the-sizing-modes-of-the-windows-forms-datagridview-control.md @@ -39,7 +39,7 @@ The following procedures demonstrate some common scenarios that customize or com ### To create fill-mode columns for values of varying size and importance -- Set the property to to set the sizing mode for all columns that do not override this value. Set the properties of the columns to values that are proportional to their average content widths. Set the properties of important columns to ensure partial content display. +- Set the property to to set the sizing mode for all columns that do not override this value. Set the properties of the columns to values that are proportional to their average content widths. Set the properties of important columns to ensure partial content display. [!code-csharp[System.Windows.Forms.DataGridViewSizingScenarios#30](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewSizingScenarios/CS/sizingscenarios.cs#30)] [!code-vb[System.Windows.Forms.DataGridViewSizingScenarios#30](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewSizingScenarios/vb/sizingscenarios.vb#30)] @@ -65,10 +65,10 @@ The following procedures demonstrate some common scenarios that customize or com ## See Also - + - - - - - + + + + + diff --git a/docs/framework/winforms/controls/how-to-set-the-text-displayed-by-a-windows-forms-control.md b/docs/framework/winforms/controls/how-to-set-the-text-displayed-by-a-windows-forms-control.md index 04584dc493ea0..36762e3190cca 100644 --- a/docs/framework/winforms/controls/how-to-set-the-text-displayed-by-a-windows-forms-control.md +++ b/docs/framework/winforms/controls/how-to-set-the-text-displayed-by-a-windows-forms-control.md @@ -76,6 +76,6 @@ Windows Forms controls usually display some text that is related to the primary ``` ## See Also - + [How to: Create Access Keys for Windows Forms Controls](../../../../docs/framework/winforms/controls/how-to-create-access-keys-for-windows-forms-controls.md) [How to: Respond to Windows Forms Button Clicks](../../../../docs/framework/winforms/controls/how-to-respond-to-windows-forms-button-clicks.md) diff --git a/docs/framework/winforms/controls/how-to-set-the-toolstrip-renderer-at-run-time.md b/docs/framework/winforms/controls/how-to-set-the-toolstrip-renderer-at-run-time.md index d2a9e6fa37770..b7f1b39fa94f1 100644 --- a/docs/framework/winforms/controls/how-to-set-the-toolstrip-renderer-at-run-time.md +++ b/docs/framework/winforms/controls/how-to-set-the-toolstrip-renderer-at-run-time.md @@ -43,7 +43,7 @@ You can customize the appearance of your c [!code-vb[System.Windows.Forms.ToolStrip.Misc#30](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/VB/Program.vb#30)] ## Assigning a Custom Renderer - Create a new `ToolStripProfessionalRenderer` with a `CustomProfessionalColors` class, and assign it to the property. + Create a new `ToolStripProfessionalRenderer` with a `CustomProfessionalColors` class, and assign it to the property. [!code-csharp[System.Windows.Forms.ToolStrip.Misc#22](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/CS/Program.cs#22)] [!code-vb[System.Windows.Forms.ToolStrip.Misc#22](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/VB/Program.vb#22)] diff --git a/docs/framework/winforms/controls/how-to-set-the-toolstrip-renderer-for-an-application.md b/docs/framework/winforms/controls/how-to-set-the-toolstrip-renderer-for-an-application.md index 96b047f0e942d..47569a30ba127 100644 --- a/docs/framework/winforms/controls/how-to-set-the-toolstrip-renderer-for-an-application.md +++ b/docs/framework/winforms/controls/how-to-set-the-toolstrip-renderer-for-an-application.md @@ -38,9 +38,9 @@ You can customize the appearance of your c [!code-csharp[System.Windows.Forms.ToolStrip.Misc#70](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/CS/Program.cs#70)] [!code-vb[System.Windows.Forms.ToolStrip.Misc#70](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.ToolStrip.Misc/VB/Program.vb#70)] - Set the property to apply a custom renderer to all the controls in your application. + Set the property to apply a custom renderer to all the controls in your application. - Set the property to apply a custom renderer to an individual control. + Set the property to apply a custom renderer to an individual control. ## Compiling the Code This example requires: diff --git a/docs/framework/winforms/controls/how-to-specify-the-edit-mode-for-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/how-to-specify-the-edit-mode-for-the-windows-forms-datagridview-control.md index cf720ad984eec..3767241edd5e3 100644 --- a/docs/framework/winforms/controls/how-to-specify-the-edit-mode-for-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/how-to-specify-the-edit-mode-for-the-windows-forms-datagridview-control.md @@ -37,7 +37,7 @@ By default, users can edit the contents of the current property to the appropriate enumeration. +- Set the property to the appropriate enumeration. [!code-csharp[System.Windows.Forms.DataGridViewMisc#067](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#067)] [!code-vb[System.Windows.Forms.DataGridViewMisc#067](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#067)] @@ -51,5 +51,5 @@ By default, users can edit the contents of the current - + [Data Entry in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/data-entry-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/how-to-use-a-control-rendering-class.md b/docs/framework/winforms/controls/how-to-use-a-control-rendering-class.md index 89e80cfecabd5..6e3747ee4128d 100644 --- a/docs/framework/winforms/controls/how-to-use-a-control-rendering-class.md +++ b/docs/framework/winforms/controls/how-to-use-a-control-rendering-class.md @@ -22,7 +22,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Use a Control Rendering Class -This example demonstrates how to use the class to render the drop-down arrow of a combo box control. The example consists of the method of a simple custom control. The property is used to determine whether visual styles are enabled in the client area of application windows. If visual styles are active, then the method will render the drop-down arrow with visual styles; otherwise, the method will render the drop-down arrow in the classic Windows style. +This example demonstrates how to use the class to render the drop-down arrow of a combo box control. The example consists of the method of a simple custom control. The property is used to determine whether visual styles are enabled in the client area of application windows. If visual styles are active, then the method will render the drop-down arrow with visual styles; otherwise, the method will render the drop-down arrow in the classic Windows style. ## Example [!code-cpp[System.Windows.Forms_ControlRenderer#10](../../../../samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms_ControlRenderer/cpp/form1.cpp#10)] @@ -36,7 +36,7 @@ This example demonstrates how to use the that hosts the custom control. -- References to the , , , and namespaces. +- References to the , , , and namespaces. ## See Also [Rendering Controls with Visual Styles](../../../../docs/framework/winforms/controls/rendering-controls-with-visual-styles.md) diff --git a/docs/framework/winforms/controls/how-to-use-tooltips-in-toolstrip-controls.md b/docs/framework/winforms/controls/how-to-use-tooltips-in-toolstrip-controls.md index fcd0016e68728..53ba45aabf937 100644 --- a/docs/framework/winforms/controls/how-to-use-tooltips-in-toolstrip-controls.md +++ b/docs/framework/winforms/controls/how-to-use-tooltips-in-toolstrip-controls.md @@ -28,13 +28,13 @@ You can display a for the property of the control to `true`. - The default value of is `true`, and the default value of and is `false`. + The default value of is `true`, and the default value of and is `false`. ### To use the ToolTipText property for the ToolTip text of a ToolStripButton 1. Set the property of the button to `true`. -2. Set the property of the button to `false`. +2. Set the property of the button to `false`. The `AutoToolTip` property is `true` by default for , , and . diff --git a/docs/framework/winforms/controls/implement-two-way-com-between-dhtml-and-client.md b/docs/framework/winforms/controls/implement-two-way-com-between-dhtml-and-client.md index ebd07744291d5..6aa7485603ff7 100644 --- a/docs/framework/winforms/controls/implement-two-way-com-between-dhtml-and-client.md +++ b/docs/framework/winforms/controls/implement-two-way-com-between-dhtml-and-client.md @@ -114,6 +114,6 @@ You can use the control to add existing d ## See Also - - + + [WebBrowser Control](../../../../docs/framework/winforms/controls/webbrowser-control-windows-forms.md) diff --git a/docs/framework/winforms/controls/implementing-virtual-mode-wf-datagridview-control.md b/docs/framework/winforms/controls/implementing-virtual-mode-wf-datagridview-control.md index 58d5cf4936bd5..b812efbc78558 100644 --- a/docs/framework/winforms/controls/implementing-virtual-mode-wf-datagridview-control.md +++ b/docs/framework/winforms/controls/implementing-virtual-mode-wf-datagridview-control.md @@ -83,7 +83,7 @@ When you want to display very large quantities of tabular data in a event that indicates whether the event will occur when the user signals row reversion by pressing ESC twice in edit mode or once outside of edit mode. - By default, occurs upon row reversion when any cells in the current row have been modified unless the property is set to `true` in the event handler. This event is useful when the commit scope is determined at run time. + By default, occurs upon row reversion when any cells in the current row have been modified unless the property is set to `true` in the event handler. This event is useful when the commit scope is determined at run time. [!code-cpp[System.Windows.Forms.DataGridView.VirtualMode#160](../../../../samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataGridView.VirtualMode/CPP/virtualmode.cpp#160)] [!code-csharp[System.Windows.Forms.DataGridView.VirtualMode#160](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridView.VirtualMode/CS/virtualmode.cs#160)] @@ -91,7 +91,7 @@ When you want to display very large quantities of tabular data in a event that discards the values of the `Customer` object representing the current row. - This event occurs when the user signals row reversion by pressing ESC twice in edit mode or once outside of edit mode. This event does not occur if no cells in the current row have been modified or if the value of the property has been set to `false` in a event handler. + This event occurs when the user signals row reversion by pressing ESC twice in edit mode or once outside of edit mode. This event does not occur if no cells in the current row have been modified or if the value of the property has been set to `false` in a event handler. [!code-cpp[System.Windows.Forms.DataGridView.VirtualMode#170](../../../../samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataGridView.VirtualMode/CPP/virtualmode.cpp#170)] [!code-csharp[System.Windows.Forms.DataGridView.VirtualMode#170](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridView.VirtualMode/CS/virtualmode.cs#170)] diff --git a/docs/framework/winforms/controls/keyboard-shortcuts-for-the-windows-forms-datagrid-control.md b/docs/framework/winforms/controls/keyboard-shortcuts-for-the-windows-forms-datagrid-control.md index 0cee52c2b97ce..f6fd9a32b17ff 100644 --- a/docs/framework/winforms/controls/keyboard-shortcuts-for-the-windows-forms-datagrid-control.md +++ b/docs/framework/winforms/controls/keyboard-shortcuts-for-the-windows-forms-datagrid-control.md @@ -56,7 +56,7 @@ manager: "wpickett" |Extend the selection down one screen (excluding child table links).|SHIFT+PAGE DOWN| |Extend the selection up one screen (excluding child table links).|SHIFT+PAGE UP| |Call the method for the current row.|CTRL+ENTER| -|Enter a value into a cell when in edit mode.|CTRL+0| +|Enter a value into a cell when in edit mode.|CTRL+0| ## See Also [DataGrid Control Overview](../../../../docs/framework/winforms/controls/datagrid-control-overview-windows-forms.md) diff --git a/docs/framework/winforms/controls/layout-in-windows-forms-controls.md b/docs/framework/winforms/controls/layout-in-windows-forms-controls.md index 7e866aee4ade9..0a59324d9ff9d 100644 --- a/docs/framework/winforms/controls/layout-in-windows-forms-controls.md +++ b/docs/framework/winforms/controls/layout-in-windows-forms-controls.md @@ -24,7 +24,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # Layout in Windows Forms Controls -Precise placement of controls on your form is a high priority for many applications. The namespace gives you many layout tools to accomplish this. +Precise placement of controls on your form is a high priority for many applications. The namespace gives you many layout tools to accomplish this. ## In This Section [AutoSize Property Overview](../../../../docs/framework/winforms/controls/autosize-property-overview.md) diff --git a/docs/framework/winforms/controls/link-to-an-object-or-web-page-with-wf-linklabel-control.md b/docs/framework/winforms/controls/link-to-an-object-or-web-page-with-wf-linklabel-control.md index 2220542a28abc..9606a5ba65c1e 100644 --- a/docs/framework/winforms/controls/link-to-an-object-or-web-page-with-wf-linklabel-control.md +++ b/docs/framework/winforms/controls/link-to-an-object-or-web-page-with-wf-linklabel-control.md @@ -105,7 +105,7 @@ The Windows Forms control allows you to cr 2. Set the property to determine which part of the caption will be indicated as a link. -3. In the event handler, in the midst of an exception-handling block, call a second procedure that sets the property to `true` and uses the method to start the default browser with a URL. To use the method you need to add a reference to the namespace. +3. In the event handler, in the midst of an exception-handling block, call a second procedure that sets the property to `true` and uses the method to start the default browser with a URL. To use the method you need to add a reference to the namespace. > [!IMPORTANT] > If the code below is run in a partial-trust environment (such as on a shared drive), the JIT compiler fails when the `VisitLink` method is called. The `System.Diagnostics.Process.Start` statement causes a link demand that fails. By catching the exception when the `VisitLink` method is called, the code below ensures that if the JIT compiler fails, the error is handled gracefully. @@ -183,7 +183,7 @@ The Windows Forms control allows you to cr ``` ## See Also - + [LinkLabel Control Overview](../../../../docs/framework/winforms/controls/linklabel-control-overview-windows-forms.md) [How to: Change the Appearance of the Windows Forms LinkLabel Control](../../../../docs/framework/winforms/controls/how-to-change-the-appearance-of-the-windows-forms-linklabel-control.md) [LinkLabel Control](../../../../docs/framework/winforms/controls/linklabel-control-windows-forms.md) diff --git a/docs/framework/winforms/controls/make-columns-read-only-in-the-datagrid-using-the-designer.md b/docs/framework/winforms/controls/make-columns-read-only-in-the-datagrid-using-the-designer.md index 9a39472f1296b..c34b8937c2870 100644 --- a/docs/framework/winforms/controls/make-columns-read-only-in-the-datagrid-using-the-designer.md +++ b/docs/framework/winforms/controls/make-columns-read-only-in-the-datagrid-using-the-designer.md @@ -43,7 +43,7 @@ By default, users can modify text and numerical data displayed in the Windows Fo ## See Also - + [How to: Add and Remove Columns in the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/add-and-remove-columns-in-the-datagrid-using-the-designer.md) [How to: Prevent Row Addition and Deletion in the Windows Forms DataGridView Control Using the Designer](../../../../docs/framework/winforms/controls/prevent-row-addition-and-deletion-in-the-datagrid-using-the-designer.md) [How to: Create a Windows Application Project](http://msdn.microsoft.com/en-us/b2f93fed-c635-4705-8d0e-cf079a264efa) diff --git a/docs/framework/winforms/controls/margin-and-padding-in-windows-forms-controls.md b/docs/framework/winforms/controls/margin-and-padding-in-windows-forms-controls.md index fe4e8003b2caf..fc8740e079468 100644 --- a/docs/framework/winforms/controls/margin-and-padding-in-windows-forms-controls.md +++ b/docs/framework/winforms/controls/margin-and-padding-in-windows-forms-controls.md @@ -23,7 +23,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # Margin and Padding in Windows Forms Controls -Precise placement of controls on your form is a high priority for many applications. The namespace gives you many layout features to accomplish this. Two of the most important are the and properties. +Precise placement of controls on your form is a high priority for many applications. The namespace gives you many layout features to accomplish this. Two of the most important are the and properties. The property defines the space around the control that keeps other controls a specified distance from the control's borders. diff --git a/docs/framework/winforms/controls/menustrip-control-overview-windows-forms.md b/docs/framework/winforms/controls/menustrip-control-overview-windows-forms.md index e9aff2b9d3f70..af5ffc61f71fe 100644 --- a/docs/framework/winforms/controls/menustrip-control-overview-windows-forms.md +++ b/docs/framework/winforms/controls/menustrip-control-overview-windows-forms.md @@ -45,9 +45,9 @@ Menus expose functionality to your users by holding commands that are grouped by |Property|Description| |--------------|-----------------| ||Gets or sets the that is used to display a list of MDI child forms.| -||Gets or sets how child menus are merged with parent menus in MDI applications.| -||Gets or sets the position of a merged item within a menu in MDI applications.| -||Gets or sets a value indicating whether the form is a container for MDI child forms.| +||Gets or sets how child menus are merged with parent menus in MDI applications.| +||Gets or sets the position of a merged item within a menu in MDI applications.| +||Gets or sets a value indicating whether the form is a container for MDI child forms.| ||Gets or sets a value indicating whether tool tips are shown for the .| ||Gets or sets a value indicating whether the supports overflow functionality.| ||Gets or sets the shortcut keys associated with the .| diff --git a/docs/framework/winforms/controls/multithreading-in-windows-forms-controls.md b/docs/framework/winforms/controls/multithreading-in-windows-forms-controls.md index 117e1d79f8940..9f4140c6453b3 100644 --- a/docs/framework/winforms/controls/multithreading-in-windows-forms-controls.md +++ b/docs/framework/winforms/controls/multithreading-in-windows-forms-controls.md @@ -22,10 +22,10 @@ ms.author: dotnetcontent manager: "wpickett" --- # Multithreading in Windows Forms Controls -In many applications, you can make your user interface (UI) more responsive by performing time-consuming operations on another thread. A number of tools are available for multithreading your Windows Forms controls, including the namespace, the method, and the `BackgroundWorker` component. +In many applications, you can make your user interface (UI) more responsive by performing time-consuming operations on another thread. A number of tools are available for multithreading your Windows Forms controls, including the namespace, the method, and the `BackgroundWorker` component. > [!NOTE] -> The `BackgroundWorker` component replaces and adds functionality to the namespace and the method; however, these are retained for both backward compatibility and future use, if you choose. For more information, see [BackgroundWorker Component Overview](../../../../docs/framework/winforms/controls/backgroundworker-component-overview.md). +> The `BackgroundWorker` component replaces and adds functionality to the namespace and the method; however, these are retained for both backward compatibility and future use, if you choose. For more information, see [BackgroundWorker Component Overview](../../../../docs/framework/winforms/controls/backgroundworker-component-overview.md). ## In This Section [How to: Make Thread-Safe Calls to Windows Forms Controls](../../../../docs/framework/winforms/controls/how-to-make-thread-safe-calls-to-windows-forms-controls.md) diff --git a/docs/framework/winforms/controls/overriding-the-onpaint-method.md b/docs/framework/winforms/controls/overriding-the-onpaint-method.md index af2af1c129378..ce23036a5f4e0 100644 --- a/docs/framework/winforms/controls/overriding-the-onpaint-method.md +++ b/docs/framework/winforms/controls/overriding-the-onpaint-method.md @@ -87,7 +87,7 @@ public class PaintEventArgs : EventArgs { } ``` - is the rectangle to be painted, and the property refers to a object. The classes in the namespace are managed classes that provide access to the functionality of [!INCLUDE[ndptecgdiplus](../../../../includes/ndptecgdiplus-md.md)], the new Windows graphics library. The object has methods to draw points, strings, lines, arcs, ellipses, and many other shapes. + is the rectangle to be painted, and the property refers to a object. The classes in the namespace are managed classes that provide access to the functionality of [!INCLUDE[ndptecgdiplus](../../../../includes/ndptecgdiplus-md.md)], the new Windows graphics library. The object has methods to draw points, strings, lines, arcs, ellipses, and many other shapes. A control invokes its method whenever it needs to change its visual display. This method in turn raises the event. diff --git a/docs/framework/winforms/controls/overview-of-using-controls-in-windows-forms.md b/docs/framework/winforms/controls/overview-of-using-controls-in-windows-forms.md index 8f9cf804c05be..625d7b937383b 100644 --- a/docs/framework/winforms/controls/overview-of-using-controls-in-windows-forms.md +++ b/docs/framework/winforms/controls/overview-of-using-controls-in-windows-forms.md @@ -27,7 +27,7 @@ This topic describes the essential elements of a Windows Forms application and p ## Simple Windows Forms Applications At a minimum, a Windows Forms application consists of the following elements: -- One or more classes that derive from . +- One or more classes that derive from . - A `Main` method that invokes the `static` (`shared` in Visual Basic) method and passes a instance to it. The method processes messages from the operating system to the application. diff --git a/docs/framework/winforms/controls/perform-a-custom-action-based-on-changes-in-a-cell-of-a-datagrid.md b/docs/framework/winforms/controls/perform-a-custom-action-based-on-changes-in-a-cell-of-a-datagrid.md index a19f52c39394d..ed08a32a24411 100644 --- a/docs/framework/winforms/controls/perform-a-custom-action-based-on-changes-in-a-cell-of-a-datagrid.md +++ b/docs/framework/winforms/controls/perform-a-custom-action-based-on-changes-in-a-cell-of-a-datagrid.md @@ -43,11 +43,11 @@ The control has a number of events you - A control named `dataGridView1`. For C#, the event handlers must be connected to the corresponding events. -- References to the and assemblies. +- References to the and assemblies. ## See Also - - + + [Programming with Cells, Rows, and Columns in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/programming-with-cells-rows-and-columns-in-the-datagrid.md) [Walkthrough: Validating Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/walkthrough-validating-data-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/prevent-row-addition-and-deletion-datagridview.md b/docs/framework/winforms/controls/prevent-row-addition-and-deletion-datagridview.md index b3c4f27b74ec7..d0c455879b0f8 100644 --- a/docs/framework/winforms/controls/prevent-row-addition-and-deletion-datagridview.md +++ b/docs/framework/winforms/controls/prevent-row-addition-and-deletion-datagridview.md @@ -35,12 +35,12 @@ Sometimes you will want to prevent users from entering new rows of data or delet - A control named `dataGridView1`. -- References to the and assemblies. +- References to the and assemblies. ## See Also - - - - + + + + [Basic Column, Row, and Cell Features in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-column-row-and-cell-features-wf-datagridview-control.md) diff --git a/docs/framework/winforms/controls/prevent-row-addition-and-deletion-in-the-datagrid-using-the-designer.md b/docs/framework/winforms/controls/prevent-row-addition-and-deletion-in-the-datagrid-using-the-designer.md index 059d619871fc7..bdb0ba0b2ce51 100644 --- a/docs/framework/winforms/controls/prevent-row-addition-and-deletion-in-the-datagrid-using-the-designer.md +++ b/docs/framework/winforms/controls/prevent-row-addition-and-deletion-in-the-datagrid-using-the-designer.md @@ -36,6 +36,6 @@ Sometimes you will want to prevent users from entering new rows of data or delet ## See Also - + [How to: Create a Windows Application Project](http://msdn.microsoft.com/en-us/b2f93fed-c635-4705-8d0e-cf079a264efa) [How to: Add Controls to Windows Forms](../../../../docs/framework/winforms/controls/how-to-add-controls-to-windows-forms.md) diff --git a/docs/framework/winforms/controls/programmatically-resize-cells-to-fit-content-in-the-datagrid.md b/docs/framework/winforms/controls/programmatically-resize-cells-to-fit-content-in-the-datagrid.md index 2565f46c9b7a0..49ec9d79ed5b3 100644 --- a/docs/framework/winforms/controls/programmatically-resize-cells-to-fit-content-in-the-datagrid.md +++ b/docs/framework/winforms/controls/programmatically-resize-cells-to-fit-content-in-the-datagrid.md @@ -43,12 +43,12 @@ You can use the control methods to resi ## See Also - - - - - - + + + + + + diff --git a/docs/framework/winforms/controls/properties-in-windows-forms-controls.md b/docs/framework/winforms/controls/properties-in-windows-forms-controls.md index 97d68173def1c..61557b21bc5f7 100644 --- a/docs/framework/winforms/controls/properties-in-windows-forms-controls.md +++ b/docs/framework/winforms/controls/properties-in-windows-forms-controls.md @@ -22,7 +22,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # Properties in Windows Forms Controls -A Windows Forms control inherits many properties form the base class . These include properties such as , , , , , , , , , , , , and many others. For details about inherited properties, see . +A Windows Forms control inherits many properties form the base class . These include properties such as , , , , , , , , , , , , and many others. For details about inherited properties, see . You can override inherited properties in your control as well as define new properties. diff --git a/docs/framework/winforms/controls/providing-accessibility-information-for-controls-on-a-windows-form.md b/docs/framework/winforms/controls/providing-accessibility-information-for-controls-on-a-windows-form.md index 2b06ab5172cb4..b8d724b009e01 100644 --- a/docs/framework/winforms/controls/providing-accessibility-information-for-controls-on-a-windows-form.md +++ b/docs/framework/winforms/controls/providing-accessibility-information-for-controls-on-a-windows-form.md @@ -98,9 +98,9 @@ pictureBox1->AccessibleRole = AccessibleRole::Chart; ## See Also - - - - - + + + + + diff --git a/docs/framework/winforms/controls/remove-autogenerated-columns-from-a-wf-datagridview-control.md b/docs/framework/winforms/controls/remove-autogenerated-columns-from-a-wf-datagridview-control.md index c4fcd23f87761..9c7b65958b214 100644 --- a/docs/framework/winforms/controls/remove-autogenerated-columns-from-a-wf-datagridview-control.md +++ b/docs/framework/winforms/controls/remove-autogenerated-columns-from-a-wf-datagridview-control.md @@ -46,12 +46,12 @@ When your control is set to autogenerat - A control named `dataGridView1` bound to a table that contains `Fax` and `CustomerID` columns, such as the `Customers` table in the Northwind sample database. -- References to the and assemblies. +- References to the and assemblies. ## See Also - - - - + + + + [Displaying Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/displaying-data-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/rendering-a-windows-forms-control.md b/docs/framework/winforms/controls/rendering-a-windows-forms-control.md index e281a6c6b60f1..07cfc98679e7f 100644 --- a/docs/framework/winforms/controls/rendering-a-windows-forms-control.md +++ b/docs/framework/winforms/controls/rendering-a-windows-forms-control.md @@ -23,11 +23,11 @@ ms.author: dotnetcontent manager: "wpickett" --- # Rendering a Windows Forms Control -Rendering refers to the process of creating a visual representation on a user's screen. Windows Forms uses [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)] (the new Windows graphics library) for rendering. The managed classes that provide access to [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)] are in the namespace and its subnamespaces. +Rendering refers to the process of creating a visual representation on a user's screen. Windows Forms uses [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)] (the new Windows graphics library) for rendering. The managed classes that provide access to [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)] are in the namespace and its subnamespaces. The following elements are involved in control rendering: -- The drawing functionality provided by the base class . +- The drawing functionality provided by the base class . - The essential elements of the [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)] graphics library. @@ -98,7 +98,7 @@ protected virtual void OnPaintBackground(PaintEventArgs pevent); While has an event-like nomenclature and takes the same argument as the `OnPaint` method, is not a true event method. There is no `PaintBackground` event and does not invoke event delegates. When overriding the method, a derived class is not required to invoke the method of its base class. ## GDI+ Basics - The class provides methods for drawing various shapes such as circles, triangles, arcs, and ellipses, as well as methods for displaying text. The namespace and its subnamespaces contain classes that encapsulate graphics elements such as shapes (circles, rectangles, arcs, and others), colors, fonts, brushes, and so on. For more information about [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)], see [Using Managed Graphics Classes](../../../../docs/framework/winforms/advanced/using-managed-graphics-classes.md). The essentials of [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)] are also described in the [How to: Create a Windows Forms Control That Shows Progress](../../../../docs/framework/winforms/controls/how-to-create-a-windows-forms-control-that-shows-progress.md). + The class provides methods for drawing various shapes such as circles, triangles, arcs, and ellipses, as well as methods for displaying text. The namespace and its subnamespaces contain classes that encapsulate graphics elements such as shapes (circles, rectangles, arcs, and others), colors, fonts, brushes, and so on. For more information about [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)], see [Using Managed Graphics Classes](../../../../docs/framework/winforms/advanced/using-managed-graphics-classes.md). The essentials of [!INCLUDE[ndptecgdi](../../../../includes/ndptecgdi-md.md)] are also described in the [How to: Create a Windows Forms Control That Shows Progress](../../../../docs/framework/winforms/controls/how-to-create-a-windows-forms-control-that-shows-progress.md). ## Geometry of the Drawing Region The property of a control specifies the rectangular region available to the control on the user's screen, while the property of specifies the area that is actually painted. (Remember that painting is done in the event method that takes a instance as its argument). A control might need to paint only a portion of its available area, as is the case when a small section of the control's display changes. In those situations, a control developer must compute the actual rectangle to draw in and pass that to . The overloaded versions of that take a or as an argument use that argument to generate the property of . @@ -109,7 +109,7 @@ protected virtual void OnPaintBackground(PaintEventArgs pevent); [!code-vb[System.Windows.Forms.FlashTrackBar#6](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/VB/FlashTrackBar.vb#6)] ## Freeing Graphics Resources - Graphics objects are expensive because they use system resources. Such objects include instances of the class as well as instances of , , and other graphics classes. It is important that you create a graphics resource only when you need it and release it soon as you are finished using it. If you create a type that implements the interface, call its method when you are finished with it in order to free resources. + Graphics objects are expensive because they use system resources. Such objects include instances of the class as well as instances of , , and other graphics classes. It is important that you create a graphics resource only when you need it and release it soon as you are finished using it. If you create a type that implements the interface, call its method when you are finished with it in order to free resources. The following code fragment shows how the `FlashTrackBar` custom control creates and releases a resource. For the complete source code, see [How to: Create a Windows Forms Control That Shows Progress](../../../../docs/framework/winforms/controls/how-to-create-a-windows-forms-control-that-shows-progress.md). diff --git a/docs/framework/winforms/controls/rendering-controls-with-visual-styles.md b/docs/framework/winforms/controls/rendering-controls-with-visual-styles.md index af218687955cc..884d68a18019e 100644 --- a/docs/framework/winforms/controls/rendering-controls-with-visual-styles.md +++ b/docs/framework/winforms/controls/rendering-controls-with-visual-styles.md @@ -29,9 +29,9 @@ manager: "wpickett" The [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] provides support for rendering controls and other Windows user interface (UI) elements using visual styles in operating systems that support them. This topic discusses the several levels of support in the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] for rendering controls and other UI elements with the current visual style of the operating system. ## Rendering Classes for Common Controls - Rendering a control refers to drawing the user interface of a control. The namespace provides the class for rendering some common Windows Forms controls. However, this class draws controls in the classic Windows style, which can make it difficult to maintain a consistent UI experience when drawing custom controls in applications with visual styles enabled. + Rendering a control refers to drawing the user interface of a control. The namespace provides the class for rendering some common Windows Forms controls. However, this class draws controls in the classic Windows style, which can make it difficult to maintain a consistent UI experience when drawing custom controls in applications with visual styles enabled. - The [!INCLUDE[dnprdnlong](../../../../includes/dnprdnlong-md.md)] includes classes in the namespace that render the parts and states of common controls with visual styles. Each of these classes includes `static` methods for drawing the control or parts of the control in a particular state with the current visual style of the operating system. + The [!INCLUDE[dnprdnlong](../../../../includes/dnprdnlong-md.md)] includes classes in the namespace that render the parts and states of common controls with visual styles. Each of these classes includes `static` methods for drawing the control or parts of the control in a particular state with the current visual style of the operating system. Some of these classes are designed to draw the related control regardless of whether visual styles are available. If visual styles are enabled, then the class members will draw the related control with visual styles; if visual styles are disabled, then the class members will draw the control in the classic Windows style. These classes include: @@ -60,16 +60,16 @@ The [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] provides sup For more information on using these classes to draw a control, see [How to: Use a Control Rendering Class](../../../../docs/framework/winforms/controls/how-to-use-a-control-rendering-class.md). ## Visual Style Element and Rendering Classes - The namespace includes classes that can be used to draw and get information about any control or UI element that is supported by visual styles. Supported controls include common controls that have a rendering class in the namespace (see the previous section), as well as other controls, such as tab controls and rebar controls. Other supported UI elements include the parts of the **Start** menu, the taskbar, and the nonclient area of windows. + The namespace includes classes that can be used to draw and get information about any control or UI element that is supported by visual styles. Supported controls include common controls that have a rendering class in the namespace (see the previous section), as well as other controls, such as tab controls and rebar controls. Other supported UI elements include the parts of the **Start** menu, the taskbar, and the nonclient area of windows. - The main classes of the namespace are and . is a foundation class for identifying any control or user interface element supported by visual styles. In addition to itself, the namespace includes many nested classes of with `static` properties that return a for every state of a control, control part, or other UI element supported by visual styles. + The main classes of the namespace are and . is a foundation class for identifying any control or user interface element supported by visual styles. In addition to itself, the namespace includes many nested classes of with `static` properties that return a for every state of a control, control part, or other UI element supported by visual styles. provides the methods that draw and get information about each defined by the current visual style of the operating system. Information that can be retrieved about an element includes its default size, background type, and color definitions. wraps the functionality of the visual styles (UxTheme) API from the Windows Shell portion of the Windows Platform SDK. For more information, see "Using Windows XP Visual Styles" in the Platform SDK portion of the MSDN Library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library/). For more information about using and , see [How to: Render a Visual Style Element](../../../../docs/framework/winforms/controls/how-to-render-a-visual-style-element.md). ## Enabling Visual Styles - To enable visual styles for an application written for the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] version 1.0, programmers must include an application manifest that specifies that ComCtl32.dll version 6 or later will be used to draw controls. Applications built with the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] version 1.1 or later can use the method of the class. + To enable visual styles for an application written for the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] version 1.0, programmers must include an application manifest that specifies that ComCtl32.dll version 6 or later will be used to draw controls. Applications built with the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] version 1.1 or later can use the method of the class. ## Checking for Visual Styles Support The property of the class indicates whether the current application is drawing controls with visual styles. When painting a custom control, you can check the value of to determine whether you should render your control with or without visual styles. The following table lists the four conditions that must exist for to return `true`. @@ -78,10 +78,10 @@ The [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] provides sup |---------------|-----------| |The operating system supports visual styles.|To verify this condition separately, use the property of the class.| |The user has enabled visual styles in the operating system.|To verify this condition separately, use the property of the class.| -|Visual styles are enabled in the application.|Visual styles can be enabled in an application by calling the method or by using an application manifest that specifies that ComCtl32.dll version 6 or later will be used to draw controls.| -|Visual styles are being used to draw the client area of application windows.|To verify this condition separately, use the property of the class and verify that it has the value or .| +|Visual styles are enabled in the application.|Visual styles can be enabled in an application by calling the method or by using an application manifest that specifies that ComCtl32.dll version 6 or later will be used to draw controls.| +|Visual styles are being used to draw the client area of application windows.|To verify this condition separately, use the property of the class and verify that it has the value or .| - To determine when a user enables or disables visual styles, or switches from one visual style to another, check for the value in the handlers for the or events. + To determine when a user enables or disables visual styles, or switches from one visual style to another, check for the value in the handlers for the or events. > [!IMPORTANT] > If you want to use to render a control or UI element when the user enables or switches visual styles, make sure that you do this when handling the event instead of the event. An exception will be thrown if you use the class when handling . diff --git a/docs/framework/winforms/controls/selected-cells-rows-and-columns-datagridview.md b/docs/framework/winforms/controls/selected-cells-rows-and-columns-datagridview.md index 6d070cafaf0fc..5d60286401cf3 100644 --- a/docs/framework/winforms/controls/selected-cells-rows-and-columns-datagridview.md +++ b/docs/framework/winforms/controls/selected-cells-rows-and-columns-datagridview.md @@ -55,7 +55,7 @@ You can get the selected cells, rows, or columns from a control named `dataGridView1`. -- References to the , , and assemblies. +- References to the , , and assemblies. ## Robust Programming The collections described in this topic do not perform efficiently when large numbers of cells, rows, or columns are selected. For more information about using these collections with large amounts of data, see [Best Practices for Scaling the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/best-practices-for-scaling-the-windows-forms-datagridview-control.md). diff --git a/docs/framework/winforms/controls/selection-and-clipboard-use-with-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/selection-and-clipboard-use-with-the-windows-forms-datagridview-control.md index f502911deb599..01a402fcf2adb 100644 --- a/docs/framework/winforms/controls/selection-and-clipboard-use-with-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/selection-and-clipboard-use-with-the-windows-forms-datagridview-control.md @@ -44,7 +44,7 @@ The `DataGridView` control provides you with a variety of options for configurin Provides reference documentation for the control. - + Provides reference documentation for the property. diff --git a/docs/framework/winforms/controls/selection-modes-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/selection-modes-in-the-windows-forms-datagridview-control.md index add031e197c0a..8d3c6f4900fe0 100644 --- a/docs/framework/winforms/controls/selection-modes-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/selection-modes-in-the-windows-forms-datagridview-control.md @@ -23,7 +23,7 @@ manager: "wpickett" # Selection Modes in the Windows Forms DataGridView Control Sometimes you want your application to perform actions based on user selections within a control. Depending on the actions, you may want to restrict the kinds of selection that are possible. For example, suppose your application can print a report for the currently selected record. In this case, you may want to configure the control so that clicking anywhere within a row always selects the entire row, and so that only one row at a time can be selected. - You can specify the selections allowed by setting the property to one of the following enumeration values. + You can specify the selections allowed by setting the property to one of the following enumeration values. |DataGridViewSelectionMode value|Description| |-------------------------------------|-----------------| diff --git a/docs/framework/winforms/controls/serializing-collections-designerserializationvisibilityattribute.md b/docs/framework/winforms/controls/serializing-collections-designerserializationvisibilityattribute.md index 9a74e33f9de89..07dea488fb849 100644 --- a/docs/framework/winforms/controls/serializing-collections-designerserializationvisibilityattribute.md +++ b/docs/framework/winforms/controls/serializing-collections-designerserializationvisibilityattribute.md @@ -45,7 +45,7 @@ Your custom controls will sometimes expose a collection as a property. This walk 2. Rename `UserControl1` to `SerializationDemoControl`. For more information, see [How to: Rename Identifiers](http://msdn.microsoft.com/en-us/2430f732-2b70-4516-8cf6-a7bb71cc9724). -3. In the **Properties** window, set the value of the property to `10`. +3. In the **Properties** window, set the value of the property to `10`. 4. Place a control in the `SerializationDemoControl`. diff --git a/docs/framework/winforms/controls/set-and-return-numeric-values-with-wf-numericupdown-control.md b/docs/framework/winforms/controls/set-and-return-numeric-values-with-wf-numericupdown-control.md index 5d8ee83e9934d..289782b389a80 100644 --- a/docs/framework/winforms/controls/set-and-return-numeric-values-with-wf-numericupdown-control.md +++ b/docs/framework/winforms/controls/set-and-return-numeric-values-with-wf-numericupdown-control.md @@ -95,9 +95,9 @@ The numeric value of the Windows Forms ## See Also - - - - + + + + [NumericUpDown Control](../../../../docs/framework/winforms/controls/numericupdown-control-windows-forms.md) [NumericUpDown Control Overview](../../../../docs/framework/winforms/controls/numericupdown-control-overview-windows-forms.md) diff --git a/docs/framework/winforms/controls/set-the-sort-modes-for-columns-wf-datagridview-control.md b/docs/framework/winforms/controls/set-the-sort-modes-for-columns-wf-datagridview-control.md index 0089a4785e257..02bc9a2992db2 100644 --- a/docs/framework/winforms/controls/set-the-sort-modes-for-columns-wf-datagridview-control.md +++ b/docs/framework/winforms/controls/set-the-sort-modes-for-columns-wf-datagridview-control.md @@ -30,7 +30,7 @@ In the control, text box columns use au ### To set the sort mode for a column -- Set the property. +- Set the property. [!code-csharp[System.Windows.Forms.DataGridViewMisc#066](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/CS/datagridviewmisc.cs#066)] [!code-vb[System.Windows.Forms.DataGridViewMisc#066](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewMisc/VB/datagridviewmisc.vb#066)] @@ -40,11 +40,11 @@ In the control, text box columns use au - A control named `dataGridView1` that contains a column named `Priority`. -- References to the and assemblies. +- References to the and assemblies. ## See Also - + [Sorting Data in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/sorting-data-in-the-windows-forms-datagridview-control.md) [Column Sort Modes in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/column-sort-modes-in-the-windows-forms-datagridview-control.md) [How to: Customize Sorting in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-customize-sorting-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/sizing-options-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/sizing-options-in-the-windows-forms-datagridview-control.md index a5a5df50ef26e..f0ffee57f9d15 100644 --- a/docs/framework/winforms/controls/sizing-options-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/sizing-options-in-the-windows-forms-datagridview-control.md @@ -101,13 +101,13 @@ manager: "wpickett" ## Programmatic Resizing When automatic sizing is disabled, you can programmatically set the exact width or height of rows, columns, or headers through the following properties: -- +- -- +- -- +- -- +- You can also programmatically resize rows, columns, and headers to fit their contents using the following methods: @@ -130,32 +130,32 @@ manager: "wpickett" You will typically call the programmatic resizing methods at specific times. For example, you might programmatically resize all columns immediately after loading data, or you might programmatically resize a specific row after a particular cell value has been modified. ## Customizing Content-based Sizing Behavior - You can customize sizing behaviors when working with derived cell, row, and column types by overriding the , , or methods or by calling protected resizing method overloads in a derived control. The protected resizing method overloads are designed to work in pairs to achieve an ideal cell height-to-width ratio, avoiding overly wide or tall cells. For example, if you call the `AutoResizeRows(DataGridViewAutoSizeRowsMode,Boolean)` overload of the method and pass in a value of `false` for the parameter, the overload will calculate the ideal heights and widths for cells in the row, but it will adjust the row heights only. You must then call the method to adjust the column widths to the calculated ideal. + You can customize sizing behaviors when working with derived cell, row, and column types by overriding the , , or methods or by calling protected resizing method overloads in a derived control. The protected resizing method overloads are designed to work in pairs to achieve an ideal cell height-to-width ratio, avoiding overly wide or tall cells. For example, if you call the `AutoResizeRows(DataGridViewAutoSizeRowsMode,Boolean)` overload of the method and pass in a value of `false` for the parameter, the overload will calculate the ideal heights and widths for cells in the row, but it will adjust the row heights only. You must then call the method to adjust the column widths to the calculated ideal. ## Content-based Sizing Options The enumerations used by sizing properties and methods have similar values for content-based sizing. With these values, you can limit which cells are used to calculate the preferred sizes. For all sizing enumerations, values with names that refer to displayed cells limit their calculations to cells in displayed rows. Excluding rows is useful to avoid a performance penalty when you are working with a large quantity of rows. You can also restrict calculations to cell values in header or nonheader cells. ## See Also - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + diff --git a/docs/framework/winforms/controls/sorting-data-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/sorting-data-in-the-windows-forms-datagridview-control.md index 44bfd6dd7665c..305f9eeded1f5 100644 --- a/docs/framework/winforms/controls/sorting-data-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/sorting-data-in-the-windows-forms-datagridview-control.md @@ -32,16 +32,16 @@ By default, users can sort the data in a `DataGridView` control by clicking the Describes how to enable users to sort by columns that are not sortable by default. [How to: Customize Sorting in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/how-to-customize-sorting-in-the-windows-forms-datagridview-control.md) - Describes how to sort data programmatically and how to customize sorting by using the event or by implementing the interface. + Describes how to sort data programmatically and how to customize sorting by using the event or by implementing the interface. ## Reference Provides reference documentation for the control. - + Provides reference documentation for the method. - + Provides reference documentation for the property. diff --git a/docs/framework/winforms/controls/specify-default-values-for-new-rows-in-the-datagrid.md b/docs/framework/winforms/controls/specify-default-values-for-new-rows-in-the-datagrid.md index 1c039a18f4092..ca20100bb707a 100644 --- a/docs/framework/winforms/controls/specify-default-values-for-new-rows-in-the-datagrid.md +++ b/docs/framework/winforms/controls/specify-default-values-for-new-rows-in-the-datagrid.md @@ -38,10 +38,10 @@ You can make data entry more convenient when the application fills in default va - A `NewCustomerId` function for generating unique `CustomerID` values. -- References to the and assemblies. +- References to the and assemblies. ## See Also - + [Data Entry in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/data-entry-in-the-windows-forms-datagridview-control.md) [Using the Row for New Records in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/using-the-row-for-new-records-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/statusstrip-control-overview.md b/docs/framework/winforms/controls/statusstrip-control-overview.md index 92ae92408f0a2..6bd2c54b23329 100644 --- a/docs/framework/winforms/controls/statusstrip-control-overview.md +++ b/docs/framework/winforms/controls/statusstrip-control-overview.md @@ -25,7 +25,7 @@ manager: "wpickett" # StatusStrip Control Overview A control displays information about an object being viewed on a , the object's components, or contextual information that relates to that object's operation within your application. Typically, a control consists of objects, each of which displays text, an icon, or both. The can also contain , , and controls. - The default has no panels. To add panels to a , use the method. + The default has no panels. To add panels to a , use the method. There is extensive support for handling items and common commands in Visual Studio. diff --git a/docs/framework/winforms/controls/stretch-a-toolstriptextbox-to-fill-the-remaining-width-of-a-toolstrip-wf.md b/docs/framework/winforms/controls/stretch-a-toolstriptextbox-to-fill-the-remaining-width-of-a-toolstrip-wf.md index 10b0f5f0c006c..9922cec6e85f8 100644 --- a/docs/framework/winforms/controls/stretch-a-toolstriptextbox-to-fill-the-remaining-width-of-a-toolstrip-wf.md +++ b/docs/framework/winforms/controls/stretch-a-toolstriptextbox-to-fill-the-remaining-width-of-a-toolstrip-wf.md @@ -36,8 +36,8 @@ When you set the property of a ## See Also - + - + [ToolStrip Control Architecture](../../../../docs/framework/winforms/controls/toolstrip-control-architecture.md) [How to: Use the Spring Property Interactively in a StatusStrip](../../../../docs/framework/winforms/controls/how-to-use-the-spring-property-interactively-in-a-statusstrip.md) diff --git a/docs/framework/winforms/controls/timer-component-windows-forms.md b/docs/framework/winforms/controls/timer-component-windows-forms.md index 930980d196e80..ce4de7584d30b 100644 --- a/docs/framework/winforms/controls/timer-component-windows-forms.md +++ b/docs/framework/winforms/controls/timer-component-windows-forms.md @@ -35,11 +35,11 @@ The Windows Forms is a component that raises a Describes how to react to timed intervals in your Windows-based applications. ## Reference - class + class Provides reference information on the class, used for Windows Forms timers, and its members. - class - Provides reference information on the class that is used by server-based timers. + class + Provides reference information on the class that is used by server-based timers. ## Related Sections [Controls to Use on Windows Forms](../../../../docs/framework/winforms/controls/controls-to-use-on-windows-forms.md) diff --git a/docs/framework/winforms/controls/toolstrip-technology-summary.md b/docs/framework/winforms/controls/toolstrip-technology-summary.md index 7e772eeba710d..1db016b93ccff 100644 --- a/docs/framework/winforms/controls/toolstrip-technology-summary.md +++ b/docs/framework/winforms/controls/toolstrip-technology-summary.md @@ -28,7 +28,7 @@ This topic summarizes information about the `ToolStrip` control and the classes The `ToolStrip` control and its associated classes provide a complete solution for creating toolbars, status bars, and menus. ## Namespaces - + ## Background With the `ToolStrip` control and its associated classes, you can create advanced toolbar functionality that has consistent and professional appearance and behavior. The `ToolStrip` control and classes offer the following improvements over previous controls: diff --git a/docs/framework/winforms/controls/unbound-column-to-a-data-bound-datagridview.md b/docs/framework/winforms/controls/unbound-column-to-a-data-bound-datagridview.md index 097832206bf8a..7ea606ee090ad 100644 --- a/docs/framework/winforms/controls/unbound-column-to-a-data-bound-datagridview.md +++ b/docs/framework/winforms/controls/unbound-column-to-a-data-bound-datagridview.md @@ -24,7 +24,7 @@ manager: "wpickett" # How to: Add an Unbound Column to a Data-Bound Windows Forms DataGridView Control The data you display in the control will normally come from a data source of some kind, but you might want to display a column of data that does not come from the data source. This kind of column is called an unbound column. Unbound columns can take many forms. Frequently, they are used to provide access to the details of a data row. - The following code example demonstrates how to create an unbound column of **Details** buttons to display a child table related to a particular row in a parent table when you implement a master/detail scenario. To respond to button clicks, implement a event handler that displays a form containing the child table. + The following code example demonstrates how to create an unbound column of **Details** buttons to display a child table related to a particular row in a parent table when you implement a master/detail scenario. To respond to button clicks, implement a event handler that displays a form containing the child table. There is support for this task in Visual Studio. Also see [How to: Add and Remove Columns in the Windows Forms DataGridView Control Using the Designer](http://msdn.microsoft.com/library/dyyesckz\(v=vs.110\)) @@ -37,7 +37,7 @@ The data you display in the control wil - A control named `dataGridView1`. -- References to the and assemblies. +- References to the and assemblies. ## See Also diff --git a/docs/framework/winforms/controls/use-the-row-template-to-customize-rows-in-the-datagrid.md b/docs/framework/winforms/controls/use-the-row-template-to-customize-rows-in-the-datagrid.md index 9000ba0a0811c..8a6ebf07370f6 100644 --- a/docs/framework/winforms/controls/use-the-row-template-to-customize-rows-in-the-datagrid.md +++ b/docs/framework/winforms/controls/use-the-row-template-to-customize-rows-in-the-datagrid.md @@ -21,7 +21,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Use the Row Template to Customize Rows in the Windows Forms DataGridView Control -The control uses the row template as a basis for all rows that it adds to the control either through data binding or when you call the method without specifying an existing row to use. +The control uses the row template as a basis for all rows that it adds to the control either through data binding or when you call the method without specifying an existing row to use. The row template gives you greater control over the appearance and behavior of rows than the property provides. With the row template, you can set any properties, including . @@ -32,7 +32,7 @@ The control uses the row template as a ### To use the row template -- Set properties on the object retrieved from the property. +- Set properties on the object retrieved from the property. [!code-cpp[System.Windows.Forms.DataGridView.RowTemplate#1](../../../../samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataGridView.RowTemplate/CPP/datagridviewrowtemplate.cpp#1)] [!code-csharp[System.Windows.Forms.DataGridView.RowTemplate#1](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridView.RowTemplate/CS/datagridviewrowtemplate.cs#1)] @@ -43,12 +43,12 @@ The control uses the row template as a - A control named `dataGridView1`. -- References to the , , and assemblies. +- References to the , , and assemblies. ## See Also - + [Basic Formatting and Styling in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/basic-formatting-and-styling-in-the-windows-forms-datagridview-control.md) [Cell Styles in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/cell-styles-in-the-windows-forms-datagridview-control.md) diff --git a/docs/framework/winforms/controls/user-drawn-controls.md b/docs/framework/winforms/controls/user-drawn-controls.md index 7407a578ea433..2c23076fddb85 100644 --- a/docs/framework/winforms/controls/user-drawn-controls.md +++ b/docs/framework/winforms/controls/user-drawn-controls.md @@ -77,7 +77,7 @@ SetStyle(ControlStyles.ResizeRedraw, true); ``` > [!NOTE] -> Use the property to implement a non-rectangular control. +> Use the property to implement a non-rectangular control. ## See Also diff --git a/docs/framework/winforms/controls/using-the-row-for-new-records-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/using-the-row-for-new-records-in-the-windows-forms-datagridview-control.md index ac9256f3ca76a..082ab6b9e8bb8 100644 --- a/docs/framework/winforms/controls/using-the-row-for-new-records-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/using-the-row-for-new-records-in-the-windows-forms-datagridview-control.md @@ -27,7 +27,7 @@ When you use a for editing data in your ## Displaying the Row for New Records Use the property to indicate whether the row for new records is displayed. The default value of this property is `true`. - For the data bound case, the row for new records will be shown if the property of the control and the property of the data source are both `true`. If either is `false` then the row will not be shown. + For the data bound case, the row for new records will be shown if the property of the control and the property of the data source are both `true`. If either is `false` then the row will not be shown. ## Populating the Row for New Records with Default Data When the user selects the row for new records as the current row, the control raises the event. @@ -37,7 +37,7 @@ When you use a for editing data in your ## The Rows Collection The row for new records is contained in the control's collection but behaves differently in two respects: -- The row for new records cannot be removed from the collection programmatically. An is thrown if this is attempted. The user also cannot delete the row for new records. The method does not remove this row from the collection. +- The row for new records cannot be removed from the collection programmatically. An is thrown if this is attempted. The user also cannot delete the row for new records. The method does not remove this row from the collection. - No row can be added after the row for new records. An is raised if this is attempted. As a result, the row for new records is always the last row in the control. The methods on that add rows—, , and —all call insertion methods internally when the row for new records is present. @@ -67,6 +67,6 @@ When you use a for editing data in your ## See Also - + [Data Entry in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/data-entry-in-the-windows-forms-datagridview-control.md) [How to: Specify Default Values for New Rows in the Windows Forms DataGridView Control](../../../../docs/framework/winforms/controls/specify-default-values-for-new-rows-in-the-datagrid.md) diff --git a/docs/framework/winforms/controls/virtual-mode-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/virtual-mode-in-the-windows-forms-datagridview-control.md index 2c4dd56b4323b..0ca97f2360dea 100644 --- a/docs/framework/winforms/controls/virtual-mode-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/virtual-mode-in-the-windows-forms-datagridview-control.md @@ -30,7 +30,7 @@ With virtual mode, you can manage the interaction between the control interact with it. - For more information about using virtual mode to maintain the values in unbound columns, see the examples in the property and class reference topics. + For more information about using virtual mode to maintain the values in unbound columns, see the examples in the property and class reference topics. ## Replacing Bound Mode If bound mode does not meet your performance needs, you can manage all your data in a custom cache through virtual-mode event handlers. For example, you can use virtual mode to implement a just-in-time data loading mechanism that retrieves only as much data from a networked database as is necessary for optimal performance. This scenario is particularly useful when working with large amounts of data over a slow network connection or with client machines that have a limited amount of RAM or storage space. diff --git a/docs/framework/winforms/controls/walkthrough-creating-an-mdi-form-with-menu-merging-and-toolstrip-controls.md b/docs/framework/winforms/controls/walkthrough-creating-an-mdi-form-with-menu-merging-and-toolstrip-controls.md index 4f8954485d5bd..3feee906424c2 100644 --- a/docs/framework/winforms/controls/walkthrough-creating-an-mdi-form-with-menu-merging-and-toolstrip-controls.md +++ b/docs/framework/winforms/controls/walkthrough-creating-an-mdi-form-with-menu-merging-and-toolstrip-controls.md @@ -27,7 +27,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # Walkthrough: Creating an MDI Form with Menu Merging and ToolStrip Controls -The namespace supports multiple document interface (MDI) applications, and the control supports menu merging. MDI forms can also controls. +The namespace supports multiple document interface (MDI) applications, and the control supports menu merging. MDI forms can also controls. This walkthrough demonstrates how to use controls with an MDI form. The form also supports menu merging with child menus. The following tasks are illustrated in this walkthrough: diff --git a/docs/framework/winforms/controls/walkthrough-debugging-custom-windows-forms-controls-at-design-time.md b/docs/framework/winforms/controls/walkthrough-debugging-custom-windows-forms-controls-at-design-time.md index 1c0346a58ce04..5c30986fd66f0 100644 --- a/docs/framework/winforms/controls/walkthrough-debugging-custom-windows-forms-controls-at-design-time.md +++ b/docs/framework/winforms/controls/walkthrough-debugging-custom-windows-forms-controls-at-design-time.md @@ -173,7 +173,7 @@ When you create a custom control, you will often find it necessary to debug its - You can use the property of the class to write code that will only execute at design time. For details, see . -- There are several attributes you can apply to your control's properties to manipulate your custom control's interaction with the designer. You can find these attributes in the namespace. +- There are several attributes you can apply to your control's properties to manipulate your custom control's interaction with the designer. You can find these attributes in the namespace. - You can write a custom designer for your custom control. This gives you complete control over the design experience using the extensible designer infrastructure exposed by Visual Studio. For details, see [Walkthrough: Creating a Windows Forms Control That Takes Advantage of Visual Studio Design-Time Features](../../../../docs/framework/winforms/controls/creating-a-wf-control-design-time-features.md). diff --git a/docs/framework/winforms/controls/walkthrough-updating-status-bar-information-at-run-time.md b/docs/framework/winforms/controls/walkthrough-updating-status-bar-information-at-run-time.md index db037e4522704..1a69053068df6 100644 --- a/docs/framework/winforms/controls/walkthrough-updating-status-bar-information-at-run-time.md +++ b/docs/framework/winforms/controls/walkthrough-updating-status-bar-information-at-run-time.md @@ -43,7 +43,7 @@ manager: "wpickett" 5. Add a Windows Forms component to the form. > [!NOTE] - > The Windows Forms component is designed for a Windows Forms environment. If you need a timer that is suitable for a server environment, see [Introduction to Server-Based Timers](http://msdn.microsoft.com/en-us/adc0bc0a-a519-4812-bafc-fb9d1a5801fc). + > The Windows Forms component is designed for a Windows Forms environment. If you need a timer that is suitable for a server environment, see [Introduction to Server-Based Timers](http://msdn.microsoft.com/en-us/adc0bc0a-a519-4812-bafc-fb9d1a5801fc). 6. Set the property to `true`. diff --git a/docs/framework/winforms/controls/walkthrough-validating-data-in-the-windows-forms-datagridview-control.md b/docs/framework/winforms/controls/walkthrough-validating-data-in-the-windows-forms-datagridview-control.md index a326570fee1a8..a9406158d300b 100644 --- a/docs/framework/winforms/controls/walkthrough-validating-data-in-the-windows-forms-datagridview-control.md +++ b/docs/framework/winforms/controls/walkthrough-validating-data-in-the-windows-forms-datagridview-control.md @@ -66,7 +66,7 @@ When you display data entry functionality to users, you frequently have to valid 4. Implement handlers for the control's and events. - The event handler is where you determine whether the value of a cell in the `CompanyName` column is empty. If the cell value fails validation, set the property of the class to `true`. This causes the control to prevent the cursor from leaving the cell. Set the property on the row to an explanatory string. This displays an error icon with a ToolTip that contains the error text. In the event handler, set the property on the row to the empty string. The event occurs only when the cell exits edit mode, which it cannot do if it fails validation. + The event handler is where you determine whether the value of a cell in the `CompanyName` column is empty. If the cell value fails validation, set the property of the class to `true`. This causes the control to prevent the cursor from leaving the cell. Set the property on the row to an explanatory string. This displays an error icon with a ToolTip that contains the error text. In the event handler, set the property on the row to the empty string. The event occurs only when the cell exits edit mode, which it cannot do if it fails validation. [!code-csharp[System.Windows.Forms.DataGridViewDataValidation#20](../../../../samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewDataValidation/CS/datavalidation.cs#20)] [!code-vb[System.Windows.Forms.DataGridViewDataValidation#20](../../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.DataGridViewDataValidation/VB/datavalidation.vb#20)] diff --git a/docs/framework/winforms/controls/windows-forms-control-development-basics.md b/docs/framework/winforms/controls/windows-forms-control-development-basics.md index 514f010d4a959..a71dd87024f6b 100644 --- a/docs/framework/winforms/controls/windows-forms-control-development-basics.md +++ b/docs/framework/winforms/controls/windows-forms-control-development-basics.md @@ -22,11 +22,11 @@ ms.author: dotnetcontent manager: "wpickett" --- # Windows Forms Control Development Basics -A Windows Forms control is a class that derives directly or indirectly from . The following list describes common scenarios for developing Windows Forms controls: +A Windows Forms control is a class that derives directly or indirectly from . The following list describes common scenarios for developing Windows Forms controls: - Combining existing controls to author a composite control. - Composite controls encapsulate a user interface that can be reused as a control. An example of a composite control is a control that consists of a text box and a reset button. Visual designers offer rich support for creating composite controls. To author a composite control, derive from . The base class provides keyboard routing for child controls and enables child controls to work as a group. For more information, see [Developing a Composite Windows Forms Control](../../../../docs/framework/winforms/controls/developing-a-composite-windows-forms-control.md). + Composite controls encapsulate a user interface that can be reused as a control. An example of a composite control is a control that consists of a text box and a reset button. Visual designers offer rich support for creating composite controls. To author a composite control, derive from . The base class provides keyboard routing for child controls and enables child controls to work as a group. For more information, see [Developing a Composite Windows Forms Control](../../../../docs/framework/winforms/controls/developing-a-composite-windows-forms-control.md). - Extending an existing control to customize it or to add to its functionality. diff --git a/docs/framework/winforms/how-to-simulate-mouse-and-keyboard-events-in-code.md b/docs/framework/winforms/how-to-simulate-mouse-and-keyboard-events-in-code.md index 652e03548cb04..542abb98acf91 100644 --- a/docs/framework/winforms/how-to-simulate-mouse-and-keyboard-events-in-code.md +++ b/docs/framework/winforms/how-to-simulate-mouse-and-keyboard-events-in-code.md @@ -31,7 +31,7 @@ Windows Forms provides several options for programmatically simulating mouse and #### To programmatically click the right mouse button -1. Create a whose property is set to the value. +1. Create a whose property is set to the value. 2. Call the method with this as the argument. @@ -43,7 +43,7 @@ Windows Forms provides several options for programmatically simulating mouse and Although you can simulate keyboard input by using the strategies discussed above for mouse input, Windows Forms also provides the class for sending keystrokes to the active application. > [!CAUTION] -> If your application is intended for international use with a variety of keyboards, the use of could yield unpredictable results and should be avoided. +> If your application is intended for international use with a variety of keyboards, the use of could yield unpredictable results and should be avoided. > [!NOTE] > The class has been updated for the .NET Framework 3.0 to enable its use in applications that run on Windows Vista. The enhanced security of Windows Vista (known as User Account Control or UAC) prevents the previous implementation from working as expected. diff --git a/docs/framework/winforms/mouse-pointers-in-windows-forms.md b/docs/framework/winforms/mouse-pointers-in-windows-forms.md index abe27c32da29e..3d903cfb7bb54 100644 --- a/docs/framework/winforms/mouse-pointers-in-windows-forms.md +++ b/docs/framework/winforms/mouse-pointers-in-windows-forms.md @@ -28,7 +28,7 @@ manager: "wpickett" The mouse *pointer*, which is sometimes referred to as the cursor, is a bitmap that specifies a focus point on the screen for user input with the mouse. This topic provides an overview of the mouse pointer in Windows Forms and describes some of the ways to modify and control the mouse pointer. ## Accessing the Mouse Pointer - The mouse pointer is represented by the class, and each has a property that specifies the pointer for that control. The class contains properties that describe the pointer, such as the and properties, and methods that can modify the appearance of the pointer, such as the , , and methods. + The mouse pointer is represented by the class, and each has a property that specifies the pointer for that control. The class contains properties that describe the pointer, such as the and properties, and methods that can modify the appearance of the pointer, such as the , , and methods. ## Controlling the Mouse Pointer Sometimes you may want to limit the area in which the mouse pointer can be used or change the position the mouse. You can get or set the current location of the mouse using the property of the . In addition, you can limit the area the mouse pointer can be used be setting the property. The clip area, by default, is the entire screen. @@ -36,7 +36,7 @@ The mouse *pointer*, which is sometimes referred to as the cursor, is a bitmap t ## Changing the Mouse Pointer Changing the mouse pointer is an important way of providing feedback to the user. For example, the mouse pointer can be modified in the handlers of the and events to tell the user that computations are occurring and to limit user interaction in the control. Sometimes, the mouse pointer will change because of system events, such as when your application is involved in a drag-and-drop operation. - The primary way to change the mouse pointer is by setting the or property of a control to a new . For examples of changing the mouse pointer, see the code example in the class. In addition, the class exposes a set of objects for many different types of pointers, such as a pointer that resembles a hand. To display the wait pointer, which resembles an hourglass, whenever the mouse pointer is on the control, use the property of the class. + The primary way to change the mouse pointer is by setting the or property of a control to a new . For examples of changing the mouse pointer, see the code example in the class. In addition, the class exposes a set of objects for many different types of pointers, such as a pointer that resembles a hand. To display the wait pointer, which resembles an hourglass, whenever the mouse pointer is on the control, use the property of the class. ## See Also diff --git a/docs/framework/winforms/order-of-events-in-windows-forms.md b/docs/framework/winforms/order-of-events-in-windows-forms.md index 94fb695fbecd5..fee5e1b31e140 100644 --- a/docs/framework/winforms/order-of-events-in-windows-forms.md +++ b/docs/framework/winforms/order-of-events-in-windows-forms.md @@ -30,34 +30,34 @@ The order in which events are raised in Windows Forms applications is of particu ## Application Startup and Shutdown Events The and classes expose a set of events related to application startup and shutdown. When a Windows Forms application starts, the startup events of the main form are raised in the following order: -- +- -- +- -- +- -- +- -- +- -- +- When an application closes, the shutdown events of the main form are raised in the following order: -- +- -- +- -- +- -- +- -- +- The event of the class is raised after the shutdown events of the main form. > [!NOTE] -> Visual Basic 2005 includes additional application events, such as and . +> Visual Basic 2005 includes additional application events, such as and . ## Focus and Validation Events When you change the focus by using the keyboard (TAB, SHIFT+TAB, and so on), by calling the or methods, or by setting the property to the current form, focus events of the class occur in the following order: diff --git a/docs/framework/winforms/user-input-validation-in-windows-forms.md b/docs/framework/winforms/user-input-validation-in-windows-forms.md index 32aae6b7dfa22..16ad6ab1e9d10 100644 --- a/docs/framework/winforms/user-input-validation-in-windows-forms.md +++ b/docs/framework/winforms/user-input-validation-in-windows-forms.md @@ -93,14 +93,14 @@ When users enter data into your application, you may want to verify that the dat - By calling the method programmatically. - However, in some cases, you might want to let the user close the form regardless of whether the values in the controls are valid. You can override validation and close a form that still contains invalid data by creating a handler for the form's event. In the event, set the property to `false`. This forces the form to close. For more information and an example, see . + However, in some cases, you might want to let the user close the form regardless of whether the values in the controls are valid. You can override validation and close a form that still contains invalid data by creating a handler for the form's event. In the event, set the property to `false`. This forces the form to close. For more information and an example, see . > [!NOTE] > If you force the form to close in this manner, any data in the form's controls that has not already been saved is lost. In addition, modal forms do not validate the contents of controls when they are closed. You can still use control validation to lock focus to a control, but you do not have to be concerned about the behavior associated with closing the form. ## See Also - - - + + + [MaskedTextBox Control](../../../docs/framework/winforms/controls/maskedtextbox-control-windows-forms.md) [Regular Expression Examples](../../../docs/standard/base-types/regular-expression-examples.md) diff --git a/docs/framework/winforms/windows-forms-data-binding.md b/docs/framework/winforms/windows-forms-data-binding.md index cfaad4984e171..f4c388522a2f5 100644 --- a/docs/framework/winforms/windows-forms-data-binding.md +++ b/docs/framework/winforms/windows-forms-data-binding.md @@ -63,10 +63,10 @@ Data binding in Windows Forms gives you the means to display and make changes to Also see [Interfaces Related to Data Binding](http://msdn.microsoft.com/library/41e17s4b\(v=vs.110\)), [How to: Navigate Data in Windows Forms](http://msdn.microsoft.com/library/b63ha24w\(v=vs.110\)), [How to: Create a Simple-Bound Control on a Windows Form](http://msdn.microsoft.com/library/sw223a62\(v=vs.110\)). ## Reference - + Describes the class that represents the binding between a bindable component and a data source. - + Describes the class that encapsulates a data source for binding to controls. ## Related Sections diff --git a/docs/framework/wpf/advanced/attached-events-overview.md b/docs/framework/wpf/advanced/attached-events-overview.md index 87b08cb26e2c9..300587c077014 100644 --- a/docs/framework/wpf/advanced/attached-events-overview.md +++ b/docs/framework/wpf/advanced/attached-events-overview.md @@ -53,7 +53,7 @@ manager: "wpickett" Although [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] defines a number of attached events, the scenarios where you will either use or handle the attached event directly are very limited. Generally, the attached event serves an architecture purpose, but is then forwarded to a non-attached (backed with a [!INCLUDE[TLA2#tla_clr](../../../../includes/tla2sharptla-clr-md.md)] event "wrapper") routed event. - For instance, the underlying attached event can more easily be handled on any given by using on that rather than dealing with attached event syntax either in [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] or code. The attached event serves a purpose in the architecture because it allows for future expansion of input devices. The hypothetical device would only need to raise in order to simulate mouse input, and would not need to derive from to do so. However, this scenario involves code handling of the events, and [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] handling of the attached event is not relevant to this scenario. + For instance, the underlying attached event can more easily be handled on any given by using on that rather than dealing with attached event syntax either in [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] or code. The attached event serves a purpose in the architecture because it allows for future expansion of input devices. The hypothetical device would only need to raise in order to simulate mouse input, and would not need to derive from to do so. However, this scenario involves code handling of the events, and [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] handling of the attached event is not relevant to this scenario. ## Handling an Attached Event in WPF diff --git a/docs/framework/wpf/advanced/attached-properties-overview.md b/docs/framework/wpf/advanced/attached-properties-overview.md index 1a0dc3a35ca4a..d3ed5f66828e9 100644 --- a/docs/framework/wpf/advanced/attached-properties-overview.md +++ b/docs/framework/wpf/advanced/attached-properties-overview.md @@ -27,13 +27,13 @@ An attached property is a concept defined by XAML. An attached property is inten ## Why Use Attached Properties - One purpose of an attached property is to allow different child elements to specify unique values for a property that is actually defined in a parent element. A specific application of this scenario is having child elements inform the parent element of how they are to be presented in the [!INCLUDE[TLA#tla_ui](../../../../includes/tlasharptla-ui-md.md)]. One example is the property. The property is created as an attached property because it is designed to be set on elements that are contained within a , rather than on itself. The class defines the static field named , and then provides the and methods as public accessors for the attached property. + One purpose of an attached property is to allow different child elements to specify unique values for a property that is actually defined in a parent element. A specific application of this scenario is having child elements inform the parent element of how they are to be presented in the [!INCLUDE[TLA#tla_ui](../../../../includes/tlasharptla-ui-md.md)]. One example is the property. The property is created as an attached property because it is designed to be set on elements that are contained within a , rather than on itself. The class defines the static field named , and then provides the and methods as public accessors for the attached property. ## Attached Properties in XAML In XAML, you set attached properties by using the syntax *AttachedPropertyProvider*.*PropertyName* - The following is an example of how you can set in XAML: + The following is an example of how you can set in XAML: [!code-xaml[PropertiesOvwSupport#APBasicUsage](../../../../samples/snippets/csharp/VS_Snippets_Wpf/PropertiesOvwSupport/CSharp/page4.xaml#apbasicusage)] @@ -57,7 +57,7 @@ An attached property is a concept defined by XAML. An attached property is inten ### An Example of a Parent-Defined Attached Property The most typical scenario where [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] defines an attached property is when a parent element supports a child element collection, and also implements a behavior where the specifics of the behavior are reported individually for each child element. - defines the attached property, and has class-level code as part of its rendering logic (specifically, and ). A instance will always check to see whether any of its immediate child elements have set a value for . If so, those values become input for the rendering logic applied to that particular child element. Nested instances each treat their own immediate child element collections, but that behavior is implementation-specific to how processes values. It is theoretically possible to have attached properties that influence elements beyond the immediate parent. If the attached property is set on an element that has no parent element to act upon it, no error or exception is raised. This simply means that a global property value was set, but it has no current parent that could consume the information. + defines the attached property, and has class-level code as part of its rendering logic (specifically, and ). A instance will always check to see whether any of its immediate child elements have set a value for . If so, those values become input for the rendering logic applied to that particular child element. Nested instances each treat their own immediate child element collections, but that behavior is implementation-specific to how processes values. It is theoretically possible to have attached properties that influence elements beyond the immediate parent. If the attached property is set on an element that has no parent element to act upon it, no error or exception is raised. This simply means that a global property value was set, but it has no current parent that could consume the information. ## Attached Properties in Code @@ -68,7 +68,7 @@ An attached property is a concept defined by XAML. An attached property is inten [!code-csharp[PropertiesOvwSupport#APCode](../../../../samples/snippets/csharp/VS_Snippets_Wpf/PropertiesOvwSupport/CSharp/page4.xaml.cs#apcode)] [!code-vb[PropertiesOvwSupport#APCode](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/PropertiesOvwSupport/visualbasic/page4.xaml.vb#apcode)] - Similar to the XAML case, if `myCheckBox` had not already been added as a child element of `myDockPanel` by the third line of code, the fourth line of code would not raise an exception, but the property value would not interact with a parent and thus would do nothing. Only a value set on a child element combined with the presence of a parent element will cause an effective behavior in the rendered application. (In this case, you could set the attached property, then attach to the tree. Or you could attach to the tree then set the attached property. Either action order provides the same result.) + Similar to the XAML case, if `myCheckBox` had not already been added as a child element of `myDockPanel` by the third line of code, the fourth line of code would not raise an exception, but the property value would not interact with a parent and thus would do nothing. Only a value set on a child element combined with the presence of a parent element will cause an effective behavior in the rendered application. (In this case, you could set the attached property, then attach to the tree. Or you could attach to the tree then set the attached property. Either action order provides the same result.) ## Attached Property Metadata @@ -81,7 +81,7 @@ An attached property is a concept defined by XAML. An attached property is inten ### When to Create an Attached Property - You might create an attached property when there is a reason to have a property setting mechanism available for classes other than the defining class. The most common scenario for this is layout. Examples of existing layout properties are , , and . The scenario enabled here is that elements that exist as child elements to layout-controlling elements are able to express layout requirements to their layout parent elements individually, each setting a property value that the parent defined as an attached property. + You might create an attached property when there is a reason to have a property setting mechanism available for classes other than the defining class. The most common scenario for this is layout. Examples of existing layout properties are , , and . The scenario enabled here is that elements that exist as child elements to layout-controlling elements are able to express layout requirements to their layout parent elements individually, each setting a property value that the parent defined as an attached property. Another scenario for using an attached property is when your class represents a service, and you want classes to be able to integrate the service more transparently. @@ -103,7 +103,7 @@ An attached property is a concept defined by XAML. An attached property is inten `public static object Get` *PropertyName* `(object` `target` `)` -- The `target` object can be specified as a more specific type in your implementation. For example, the method types the parameter as , because the attached property is only intended to be set on instances. +- The `target` object can be specified as a more specific type in your implementation. For example, the method types the parameter as , because the attached property is only intended to be set on instances. - The return value can be specified as a more specific type in your implementation. For example, the method types it as , because the value can only be set to that enumeration. @@ -139,7 +139,7 @@ An attached property is a concept defined by XAML. An attached property is inten - For more advanced usage scenarios for dependency properties and attached properties, see [Custom Dependency Properties](../../../../docs/framework/wpf/advanced/custom-dependency-properties.md). -- You can also register a property as an attached property, and as a dependency property, but then still expose "wrapper" implementations. In this case, the property can be set either on that element, or on any element through the XAML attached property syntax. An example of a property with an appropriate scenario for both standard and attached usages is . +- You can also register a property as an attached property, and as a dependency property, but then still expose "wrapper" implementations. In this case, the property can be set either on that element, or on any element through the XAML attached property syntax. An example of a property with an appropriate scenario for both standard and attached usages is . ## See Also diff --git a/docs/framework/wpf/advanced/bidirectional-features-in-wpf-overview.md b/docs/framework/wpf/advanced/bidirectional-features-in-wpf-overview.md index 4294c0d44704a..9c5e781f63977 100644 --- a/docs/framework/wpf/advanced/bidirectional-features-in-wpf-overview.md +++ b/docs/framework/wpf/advanced/bidirectional-features-in-wpf-overview.md @@ -200,7 +200,7 @@ Unlike any other development platform, [!INCLUDE[TLA2#tla_winclient - Override: Number culture is that of property. -- Text: Number culture is the culture of the text run. In markup, this would be `xml:lang`, or its alias `Language` property ( or ). Also, it is the default for classes deriving from . Such classes include , , and so forth. +- Text: Number culture is the culture of the text run. In markup, this would be `xml:lang`, or its alias `Language` property ( or ). Also, it is the default for classes deriving from . Such classes include , , and so forth. - User: Number culture is the culture of the current thread. This property is the default for all subclasses of such as , and . @@ -212,7 +212,7 @@ Unlike any other development platform, [!INCLUDE[TLA2#tla_winclient This property specifies the type of number substitution to perform. It takes one of the following enumeration values. -- : The substitution method is determined based on the number culture's property. This is the default. +- : The substitution method is determined based on the number culture's property. This is the default. - : If the number culture is an Arabic or Farsi culture, it specifies that the digits depend on the context. diff --git a/docs/framework/wpf/advanced/binding-markup-extension.md b/docs/framework/wpf/advanced/binding-markup-extension.md index 0aaed00ee9374..afc2c09c7433c 100644 --- a/docs/framework/wpf/advanced/binding-markup-extension.md +++ b/docs/framework/wpf/advanced/binding-markup-extension.md @@ -47,16 +47,16 @@ Defers a property value to be a data-bound value, creating an intermediate expre |-|-| |`bindProp1, bindPropN`|The name of the or property to set. Not all properties can be set with the `Binding` extension, and some properties are settable within a `Binding` expression only by using further nested markup extensions. See "Binding Properties That Can Be Set with the Binding Extension" section.| |`value1, valueN`|The value to set the property to. The handling of the attribute value is ultimately specific to the type and logic of the specific property being set.| -|`path`|The path string that sets the implicit property. See also [PropertyPath XAML Syntax](../../../../docs/framework/wpf/advanced/propertypath-xaml-syntax.md).| +|`path`|The path string that sets the implicit property. See also [PropertyPath XAML Syntax](../../../../docs/framework/wpf/advanced/propertypath-xaml-syntax.md).| ## Unqualified {Binding} - The `{Binding}` usage shown in "Binding Expression Usage" creates a object with default values, which includes an initial of `null`. This is still useful in many scenarios, because the created might be relying on key data binding properties such as and being set in the run-time data context. For more information on the concept of data context, see [Data Binding](../../../../docs/framework/wpf/data/data-binding-wpf.md). + The `{Binding}` usage shown in "Binding Expression Usage" creates a object with default values, which includes an initial of `null`. This is still useful in many scenarios, because the created might be relying on key data binding properties such as and being set in the run-time data context. For more information on the concept of data context, see [Data Binding](../../../../docs/framework/wpf/data/data-binding-wpf.md). ## Implicit Path - The `Binding` markup extension uses as a conceptual "default property", where `Path=` does not need to appear in the expression. If you specify a `Binding` expression with an implicit path, the implicit path must appear first in the expression, prior to any other `bindProp`=`value` pairs where the property is specified by name. For example: `{Binding PathString}`, where `PathString` is a string that is evaluated to be the value of in the created by the markup extension usage. You can append an implicit path with other named properties after the comma separator, for example, `{Binding LastName, Mode=TwoWay}`. + The `Binding` markup extension uses as a conceptual "default property", where `Path=` does not need to appear in the expression. If you specify a `Binding` expression with an implicit path, the implicit path must appear first in the expression, prior to any other `bindProp`=`value` pairs where the property is specified by name. For example: `{Binding PathString}`, where `PathString` is a string that is evaluated to be the value of in the created by the markup extension usage. You can append an implicit path with other named properties after the comma separator, for example, `{Binding LastName, Mode=TwoWay}`. ## Binding Properties That Can Be Set with the Binding Extension - The syntax shown in this topic uses the generic `bindProp`=`value` approximation, because there are many read/write properties of or that can be set through the `Binding` markup extension / expression syntax. They can be set in any order, with the exception of an implicit . (You do have the option to explicitly specify `Path=`, in which case it can be set in any order). Basically, you can set zero or more of the properties in the list below, using `bindProp`=`value` pairs separated by commas. + The syntax shown in this topic uses the generic `bindProp`=`value` approximation, because there are many read/write properties of or that can be set through the `Binding` markup extension / expression syntax. They can be set in any order, with the exception of an implicit . (You do have the option to explicitly specify `Path=`, in which case it can be set in any order). Basically, you can set zero or more of the properties in the list below, using `bindProp`=`value` pairs separated by commas. Several of these property values require object types that do not support a native type conversion from a text syntax in XAML, and thus require markup extensions in order to be set as an attribute value. Check the XAML Attribute Usage section in the .NET Framework Class Library for each property for more information; the string you use for XAML attribute syntax with or without further markup extension usage is basically the same as the value you specify in a `Binding` expression, with the exception that you do not place quotation marks around each `bindProp`=`value` in the `Binding` expression. diff --git a/docs/framework/wpf/advanced/componentresourcekey-markup-extension.md b/docs/framework/wpf/advanced/componentresourcekey-markup-extension.md index ef440c9e8dc24..69add54725bbb 100644 --- a/docs/framework/wpf/advanced/componentresourcekey-markup-extension.md +++ b/docs/framework/wpf/advanced/componentresourcekey-markup-extension.md @@ -70,7 +70,7 @@ Defines and references keys for resources that are loaded from external assembli For both establishing keys and referencing keyed resources, attribute syntax is commonly used for the `ComponentResourceKey` markup extension. - The compact syntax shown relies on the constructor signature and positional parameter usage of a markup extension. The order in which the `targetTypeName` and `targetID` are given is important. The verbose syntax relies on the default constructor, and then sets the and in a way that is analogous to a true attribute syntax on an object element. In the verbose syntax, the order in which the properties are set is not important. The relationship and mechanisms of these two alternatives (compact and verbose) is described in more detail in the topic [Markup Extensions and WPF XAML](../../../../docs/framework/wpf/advanced/markup-extensions-and-wpf-xaml.md). + The compact syntax shown relies on the constructor signature and positional parameter usage of a markup extension. The order in which the `targetTypeName` and `targetID` are given is important. The verbose syntax relies on the default constructor, and then sets the and in a way that is analogous to a true attribute syntax on an object element. In the verbose syntax, the order in which the properties are set is not important. The relationship and mechanisms of these two alternatives (compact and verbose) is described in more detail in the topic [Markup Extensions and WPF XAML](../../../../docs/framework/wpf/advanced/markup-extensions-and-wpf-xaml.md). Technically, the value for `targetID` can be any object, it does not have to be a string. However, the most common usage in WPF is to align the `targetID` value with forms that are strings, and where such strings are valid in the [XamlName Grammar](../../../../docs/framework/xaml-services/xamlname-grammar.md). diff --git a/docs/framework/wpf/advanced/custom-dependency-properties.md b/docs/framework/wpf/advanced/custom-dependency-properties.md index 3373fc8882b37..54f35d01334ee 100644 --- a/docs/framework/wpf/advanced/custom-dependency-properties.md +++ b/docs/framework/wpf/advanced/custom-dependency-properties.md @@ -138,7 +138,7 @@ This topic describes the reasons that [!INCLUDE[TLA#tla_winclient](../../../../i - By default, dependency properties support data binding. You can deliberately disable data binding, for cases where there is no realistic scenario for data binding, or where performance in data binding for a large object is recognized as a problem. -- By default, data binding for dependency properties defaults to . You can always change the binding to be per binding instance; for details, see [Specify the Direction of the Binding](../../../../docs/framework/wpf/data/how-to-specify-the-direction-of-the-binding.md). But as the dependency property author, you can choose to make the property use binding mode by default. An example of an existing dependency property is ; the scenario for this property is that the setting logic and the compositing of interact with the default theme style. The property logic uses data binding natively to maintain the state of the property in accordance to other state properties and method calls. Another example property that binds by default is . +- By default, data binding for dependency properties defaults to . You can always change the binding to be per binding instance; for details, see [Specify the Direction of the Binding](../../../../docs/framework/wpf/data/how-to-specify-the-direction-of-the-binding.md). But as the dependency property author, you can choose to make the property use binding mode by default. An example of an existing dependency property is ; the scenario for this property is that the setting logic and the compositing of interact with the default theme style. The property logic uses data binding natively to maintain the state of the property in accordance to other state properties and method calls. Another example property that binds by default is . - You can also enable property inheritance in a custom dependency property by setting the flag. Property inheritance is useful for a scenario where parent elements and child elements have a property in common, and it makes sense for the child elements to have that particular property value set to the same value as the parent set it. An example inheritable property is , which is used for binding operations to enable the important master-detail scenario for data presentation. By making inheritable, any child elements inherit that data context also. Because of property value inheritance, you can specify a data context at the page or application root, and do not need to respecify it for bindings in all possible child elements. is also a good example to illustrate that inheritance overrides the default value, but it can always be set locally on any particular child element; for details, see [Use the Master-Detail Pattern with Hierarchical Data](../../../../docs/framework/wpf/data/how-to-use-the-master-detail-pattern-with-hierarchical-data.md). Property value inheritance does have a possible performance cost, and thus should be used sparingly; for details, see [Property Value Inheritance](../../../../docs/framework/wpf/advanced/property-value-inheritance.md). diff --git a/docs/framework/wpf/advanced/custom-rendering-ink.md b/docs/framework/wpf/advanced/custom-rendering-ink.md index 71681d60a7089..eab09efefa16e 100644 --- a/docs/framework/wpf/advanced/custom-rendering-ink.md +++ b/docs/framework/wpf/advanced/custom-rendering-ink.md @@ -85,7 +85,7 @@ The property of a stroke a - Create a class that derives from the . -- Assign your customized to the property. +- Assign your customized to the property. - Override the method. In this method, remove the original stroke that was added to the InkCanvas. Then create a custom stroke, add it to the property, and call the base class with a new that contains the custom stroke. diff --git a/docs/framework/wpf/advanced/datetime-xaml-syntax.md b/docs/framework/wpf/advanced/datetime-xaml-syntax.md index d32798ccce270..a12d286f444cc 100644 --- a/docs/framework/wpf/advanced/datetime-xaml-syntax.md +++ b/docs/framework/wpf/advanced/datetime-xaml-syntax.md @@ -28,7 +28,7 @@ Some controls, such as and ## When To Use DateTime XAML Syntax - Setting dates in XAML is not always necessary and may not even be desirable. For example, you could use the property to initialize a date at run time, or you could do all your date adjustments for a calendar in the code-behind based on user input. However, there are scenarios where you may want to hard-code dates into a and in a control template. The XAML syntax must be used for these scenarios. + Setting dates in XAML is not always necessary and may not even be desirable. For example, you could use the property to initialize a date at run time, or you could do all your date adjustments for a calendar in the code-behind based on user input. However, there are scenarios where you may want to hard-code dates into a and in a control template. The XAML syntax must be used for these scenarios. ### DateTime XAML Syntax is a Native Behavior is a class that is defined in the base class libraries of the CLR. Because of how the base class libraries relate to the rest of the CLR, it is not possible to apply to the class and use a type converter to process strings from XAML and convert them to in the run time object model. There is no `DateTimeConverter` class that provides the conversion behavior; the conversion behavior described in this topic is native to the WPF XAML parser. @@ -39,7 +39,7 @@ Some controls, such as and in XAML, you can use any of the format strings interchangeably. - You can also use formats and format strings that are not specifically shown in this topic. Technically, the XAML for any value that is specified and then parsed by the WPF XAML parser uses an internal call to , therefore you could use any string accepted by for your XAML input. For more information, see . + You can also use formats and format strings that are not specifically shown in this topic. Technically, the XAML for any value that is specified and then parsed by the WPF XAML parser uses an internal call to , therefore you could use any string accepted by for your XAML input. For more information, see . > [!IMPORTANT] > The DateTime XAML syntax always uses `en-us` as the for its native conversion. This is not influenced by value or `xml:lang` value in the XAML, because XAML attribute-level type conversion acts without that context. Do not attempt to interpolate the format strings shown here due to cultural variations, such as the order in which day and month appear. The format strings shown here are the exact format strings used when parsing the XAML regardless of other culture settings. @@ -57,7 +57,7 @@ Some controls, such as and . + For more information, see . ### Sortable DateTime Pattern ("s") The following shows the sortable pattern in XAML: @@ -78,7 +78,7 @@ Some controls, such as and in XAML can be specified as any string that is acceptable as input for . This includes other formalized formats (for example ), and formats that are not formalized as a particular form. For example, the form `YYYY/mm/dd` is acceptable as input for . This topic does not attempt to describe all possible formats that work, and instead recommends the short date pattern as a standard practice. + As stated previously, a in XAML can be specified as any string that is acceptable as input for . This includes other formalized formats (for example ), and formats that are not formalized as a particular form. For example, the form `YYYY/mm/dd` is acceptable as input for . This topic does not attempt to describe all possible formats that work, and instead recommends the short date pattern as a standard practice. ## See Also [XAML Overview (WPF)](../../../../docs/framework/wpf/advanced/xaml-overview-wpf.md) diff --git a/docs/framework/wpf/advanced/drag-and-drop-overview.md b/docs/framework/wpf/advanced/drag-and-drop-overview.md index 0630b04484aee..8bee6f8eb1b99 100644 --- a/docs/framework/wpf/advanced/drag-and-drop-overview.md +++ b/docs/framework/wpf/advanced/drag-and-drop-overview.md @@ -36,7 +36,7 @@ This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_wi The drag-and-drop facilities provided by [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] are designed to be highly flexible and customizable to support a wide variety of drag-and-drop scenarios. Drag-and-drop supports manipulating objects within a single application, or between different applications. Dragging-and-dropping between [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] applications and other [!INCLUDE[TLA2#tla_win](../../../../includes/tla2sharptla-win-md.md)] applications is also fully supported. - In [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)], any or can participate in drag-and-drop. The events and methods required for drag-and-drop operations are defined in the class. The and classes contain aliases for the attached events so that the events appear in the class members list when a or is inherited as a base element. Event handlers that are attached to these events are attached to the underlying attached event and receive the same event data instance. For more information, see the event. + In [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)], any or can participate in drag-and-drop. The events and methods required for drag-and-drop operations are defined in the class. The and classes contain aliases for the attached events so that the events appear in the class members list when a or is inherited as a base element. Event handlers that are attached to these events are attached to the underlying attached event and receive the same event data instance. For more information, see the event. > [!IMPORTANT] > OLE drag-and-drop does not work while in the Internet zone. @@ -53,7 +53,7 @@ This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_wi In a copy-and-paste operation, the system clipboard is used to temporarily store the transferred data; in a drag-and-drop operation, a is used to store the data. Conceptually, a data object consists of one or more pairs of an that contains the actual data, and a corresponding data format identifier. - The drag source initiates a drag-and-drop operation by calling the static method and passing the transferred data to it. The method will automatically wrap the data in a if necessary. For greater control over the data format, you can wrap the data in a before passing it to the method. The drop target is responsible for extracting the data from the . For more information about working with data objects, see [Data and Data Objects](../../../../docs/framework/wpf/advanced/data-and-data-objects.md). + The drag source initiates a drag-and-drop operation by calling the static method and passing the transferred data to it. The method will automatically wrap the data in a if necessary. For greater control over the data format, you can wrap the data in a before passing it to the method. The drop target is responsible for extracting the data from the . For more information about working with data objects, see [Data and Data Objects](../../../../docs/framework/wpf/advanced/data-and-data-objects.md). The source and target of a drag-and-drop operation are UI elements; however, the data that is actually being transferred typically does not have a visual representation. You can write code to provide a visual representation of the data that is dragged, such as occurs when dragging files in Windows Explorer. By default, feedback is provided to the user by changing the cursor to represent the effect that the drag-and-drop operation will have on the data, such as whether the data will be moved or copied. @@ -191,16 +191,16 @@ This topic provides an overview of drag-and-drop support in [!INCLUDE[TLA#tla_wi 3. or - The event occurs when the data is dragged into the drop target's boundary. You typically handle this event to provide a preview of the effects of the drag-and-drop operation, if appropriate for your application. Do not set the property in the event, as it will be overwritten in the event. + The event occurs when the data is dragged into the drop target's boundary. You typically handle this event to provide a preview of the effects of the drag-and-drop operation, if appropriate for your application. Do not set the property in the event, as it will be overwritten in the event. The following example shows the event handler for an element. This code previews the effects of the drag-and-drop operation by saving the current brush. It then uses the method to check whether the being dragged over the ellipse contains string data that can be converted to a . If so, the data is extracted using the method. It is then converted to a and applied to the ellipse. The change is reverted in the event handler. If the data cannot be converted to a , no action is performed. [!code-csharp[DragDropSnippets#DragEnter](../../../../samples/snippets/csharp/VS_Snippets_Wpf/dragdropsnippets/cs/mainwindow.xaml.cs#dragenter)] [!code-vb[DragDropSnippets#DragEnter](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/dragdropsnippets/vb/mainwindow.xaml.vb#dragenter)] - The event occurs continuously while the data is dragged over the drop target. This event is paired with the event on the drag source. In the event handler, you typically use the and methods to check whether the transferred data is in a format that the drop target can process. You can also check whether any modifier keys are pressed, which will typically indicate whether the user intends a move or copy action. After these checks are performed, you set the property to notify the drag source what effect dropping the data will have. The drag source receives this information in the event args, and can set an appropriate cursor to give feedback to the user. + The event occurs continuously while the data is dragged over the drop target. This event is paired with the event on the drag source. In the event handler, you typically use the and methods to check whether the transferred data is in a format that the drop target can process. You can also check whether any modifier keys are pressed, which will typically indicate whether the user intends a move or copy action. After these checks are performed, you set the property to notify the drag source what effect dropping the data will have. The drag source receives this information in the event args, and can set an appropriate cursor to give feedback to the user. - The following example shows the event handler for an element. This code checks to see if the being dragged over the ellipse contains string data that can be converted to a . If so, it sets the property to . This indicates to the drag source that the data can be copied to the ellipse. If the data cannot be converted to a , the property is set to . This indicates to the drag source that the ellipse is not a valid drop target for the data. + The following example shows the event handler for an element. This code checks to see if the being dragged over the ellipse contains string data that can be converted to a . If so, it sets the property to . This indicates to the drag source that the data can be copied to the ellipse. If the data cannot be converted to a , the property is set to . This indicates to the drag source that the ellipse is not a valid drop target for the data. [!code-csharp[DragDropSnippets#DragOver](../../../../samples/snippets/csharp/VS_Snippets_Wpf/dragdropsnippets/cs/mainwindow.xaml.cs#dragover)] [!code-vb[DragDropSnippets#DragOver](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/dragdropsnippets/vb/mainwindow.xaml.vb#dragover)] diff --git a/docs/framework/wpf/advanced/dynamicresource-markup-extension.md b/docs/framework/wpf/advanced/dynamicresource-markup-extension.md index f1c5df2884294..d4fc8834da2d4 100644 --- a/docs/framework/wpf/advanced/dynamicresource-markup-extension.md +++ b/docs/framework/wpf/advanced/dynamicresource-markup-extension.md @@ -44,7 +44,7 @@ Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharp ||| |-|-| -|`key`|The key for the requested resource. This key was initially assigned by the [x:Key Directive](../../../../docs/framework/xaml-services/x-key-directive.md) if a resource was created in markup, or was provided as the `key` parameter when calling if the resource was created in code.| +|`key`|The key for the requested resource. This key was initially assigned by the [x:Key Directive](../../../../docs/framework/xaml-services/x-key-directive.md) if a resource was created in markup, or was provided as the `key` parameter when calling if the resource was created in code.| ## Remarks A `DynamicResource` will create a temporary expression during the initial compilation and thus defer lookup for resources until the requested resource value is actually required in order to construct an object. This may potentially be after the [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] page is loaded. The resource value will be found based on key search against all active resource dictionaries starting from the current page scope, and is substituted for the placeholder expression from compilation. diff --git a/docs/framework/wpf/advanced/flow-document-overview.md b/docs/framework/wpf/advanced/flow-document-overview.md index 1b933fd7832b1..055a177653a45 100644 --- a/docs/framework/wpf/advanced/flow-document-overview.md +++ b/docs/framework/wpf/advanced/flow-document-overview.md @@ -158,7 +158,7 @@ Flow documents are designed to optimize viewing and readability. Rather than bei [!code-xaml[FlowOvwSnippets_snip#RunExample1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/FlowOvwSnippets_snip/CS/RunSnippetsExample.xaml#runexample1)] - **Note:** Starting in the [!INCLUDE[net_v40_short](../../../../includes/net-v40-short-md.md)], the property of the object is a dependency property. You can bind the property to a data source, such as a . The property fully supports one-way binding. The property also supports two-way binding, except for . For an example, see . + **Note:** Starting in the [!INCLUDE[net_v40_short](../../../../includes/net-v40-short-md.md)], the property of the object is a dependency property. You can bind the property to a data source, such as a . The property fully supports one-way binding. The property also supports two-way binding, except for . For an example, see . **Span** diff --git a/docs/framework/wpf/advanced/focus-overview.md b/docs/framework/wpf/advanced/focus-overview.md index 72a227bc0545b..8916fe00b0c67 100644 --- a/docs/framework/wpf/advanced/focus-overview.md +++ b/docs/framework/wpf/advanced/focus-overview.md @@ -46,7 +46,7 @@ In [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md. ## Logical Focus - Logical focus refers to the in a focus scope. A focus scope is an element that keeps track of the within its scope. When keyboard focus leaves a focus scope, the focused element will lose keyboard focus but will retain logical focus. When keyboard focus returns to the focus scope, the focused element will obtain keyboard focus. This allows for keyboard focus to be changed between multiple focus scopes but ensures that the focused element in the focus scope regains keyboard focus when focus returns to the focus scope. + Logical focus refers to the in a focus scope. A focus scope is an element that keeps track of the within its scope. When keyboard focus leaves a focus scope, the focused element will lose keyboard focus but will retain logical focus. When keyboard focus returns to the focus scope, the focused element will obtain keyboard focus. This allows for keyboard focus to be changed between multiple focus scopes but ensures that the focused element in the focus scope regains keyboard focus when focus returns to the focus scope. There can be multiple elements that have logical focus in an application, but there may only be one element that has logical focus in a particular focus scope. diff --git a/docs/framework/wpf/advanced/framework-property-metadata.md b/docs/framework/wpf/advanced/framework-property-metadata.md index 27d649f246abd..7a3ef336afeb2 100644 --- a/docs/framework/wpf/advanced/framework-property-metadata.md +++ b/docs/framework/wpf/advanced/framework-property-metadata.md @@ -33,7 +33,7 @@ Framework property metadata options are reported for the properties of object el - Reporting layout properties that affect an element (, , ). You might set these flags in metadata if the property affects those respective aspects, and you are also implementing the / methods in your class to supply specific rendering behavior and information to the layout system. Typically, such an implementation would check for property invalidations in dependency properties where any of these layout properties were true in the property metadata, and only those invalidations would necessitate requesting a new layout pass. -- Reporting layout properties that affect the parent element of an element (, ). Some examples where these flags are set by default are and . +- Reporting layout properties that affect the parent element of an element (, ). Some examples where these flags are set by default are and . - . By default, dependency properties do not inherit values. allows the pathway of inheritance to also travel into a visual tree, which is necessary for some control compositing scenarios. @@ -74,7 +74,7 @@ Framework property metadata options are reported for the properties of object el - The property system behavior is that only the in the immediate metadata is invoked. No references to other implementations in the hierarchy are retained. -- The flags of enumeration are combined as a bitwise OR operation. If you specify , the original options are not overwritten. To change an option, set the corresponding property on . For example, if the original object sets the flag, you can change that by setting to `false`. +- The flags of enumeration are combined as a bitwise OR operation. If you specify , the original options are not overwritten. To change an option, set the corresponding property on . For example, if the original object sets the flag, you can change that by setting to `false`. This behavior is implemented by , and can be overridden on derived metadata classes. diff --git a/docs/framework/wpf/advanced/graphics-rendering-tiers.md b/docs/framework/wpf/advanced/graphics-rendering-tiers.md index 1d94f7337e6b6..372d12f25b7e2 100644 --- a/docs/framework/wpf/advanced/graphics-rendering-tiers.md +++ b/docs/framework/wpf/advanced/graphics-rendering-tiers.md @@ -48,7 +48,7 @@ A rendering tier defines a level of graphics hardware capability and performance - **Rendering Tier 2** Most graphics features use graphics hardware acceleration. The [!INCLUDE[TLA2#tla_dx](../../../../includes/tla2sharptla-dx-md.md)] version level is greater than or equal to version 9.0. - The property allows you to retrieve the rendering tier at application run time. You use the rendering tier to determine whether the device supports certain hardware-accelerated graphics features. Your application can then take different code paths at run time depending on the rendering tier supported by the device. + The property allows you to retrieve the rendering tier at application run time. You use the rendering tier to determine whether the device supports certain hardware-accelerated graphics features. Your application can then take different code paths at run time depending on the rendering tier supported by the device. ### Rendering Tier 0 A rendering tier value of 0 means that there is no graphics hardware acceleration available for the application on the device. At this tier level, you should assume that all graphics will be rendered by software with no hardware acceleration. This tier's functionality corresponds to a [!INCLUDE[TLA2#tla_dx](../../../../includes/tla2sharptla-dx-md.md)] version that is less than 9.0. diff --git a/docs/framework/wpf/advanced/how-to-clone-a-printer.md b/docs/framework/wpf/advanced/how-to-clone-a-printer.md index 7c9233efbc8ce..7201ecd18b93e 100644 --- a/docs/framework/wpf/advanced/how-to-clone-a-printer.md +++ b/docs/framework/wpf/advanced/how-to-clone-a-printer.md @@ -22,7 +22,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Clone a Printer -Most businesses will, at some point, buy multiple printers of the same model. Typically, these are all installed with virtually identical configuration settings. Installing each printer can be time-consuming and error prone. The namespace and the class that are exposed with [!INCLUDE[TLA#tla_avalonwinfx](../../../../includes/tlasharptla-avalonwinfx-md.md)] makes it possible to instantly install any number of additional print queues that are cloned from an existing print queue. +Most businesses will, at some point, buy multiple printers of the same model. Typically, these are all installed with virtually identical configuration settings. Installing each printer can be time-consuming and error prone. The namespace and the class that are exposed with [!INCLUDE[TLA#tla_avalonwinfx](../../../../includes/tlasharptla-avalonwinfx-md.md)] makes it possible to instantly install any number of additional print queues that are cloned from an existing print queue. ## Example In the example below, a second print queue is cloned from an existing print queue. The second differs from the first only in its name, location, port, and shared status. The major steps for doing this are as follows. diff --git a/docs/framework/wpf/advanced/how-to-diagnose-problematic-print-job.md b/docs/framework/wpf/advanced/how-to-diagnose-problematic-print-job.md index adbc8b9b36227..efbd8b037be97 100644 --- a/docs/framework/wpf/advanced/how-to-diagnose-problematic-print-job.md +++ b/docs/framework/wpf/advanced/how-to-diagnose-problematic-print-job.md @@ -39,7 +39,7 @@ Network administrators often field complaints from users about print jobs that d The code below is series of code examples. The first code example contains the loop through the print queues. (Step 1c above.) The variable `myPrintQueues` is the object for the current print server. - The code example begins by refreshing the current print queue object with . This ensures that the object's properties accurately represent the state of the physical printer that it represents. Then the application gets the collection of print jobs currently in the print queue by using . + The code example begins by refreshing the current print queue object with . This ensures that the object's properties accurately represent the state of the physical printer that it represents. Then the application gets the collection of print jobs currently in the print queue by using . Next the application loops through the collection and compares each property with the alias of the complaining user. If they match, the application adds identifying information about the job to the string that will be presented. (The `userName` and `jobList` variables are initialized earlier in the application.) @@ -75,9 +75,9 @@ Network administrators often field complaints from users about print jobs that d [!code-csharp[DiagnoseProblematicPrintJob#SpotTroubleUsingJobProperties](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CSharp/Program.cs#spottroubleusingjobproperties)] [!code-vb[DiagnoseProblematicPrintJob#SpotTroubleUsingJobProperties](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb#spottroubleusingjobproperties)] - The **HandlePausedJob** method enables the application's user to remotely resume paused jobs. Because there might be a good reason why the print queue was paused, the method begins by prompting for a user decision about whether to resume it. If the answer is "Y", then the method is called. + The **HandlePausedJob** method enables the application's user to remotely resume paused jobs. Because there might be a good reason why the print queue was paused, the method begins by prompting for a user decision about whether to resume it. If the answer is "Y", then the method is called. - Next the user is prompted to decide if the job itself should be resumed, just in case it is paused independently of the print queue. (Compare and .) If the answer is "Y", then is called; otherwise is called. + Next the user is prompted to decide if the job itself should be resumed, just in case it is paused independently of the print queue. (Compare and .) If the answer is "Y", then is called; otherwise is called. [!code-cpp[DiagnoseProblematicPrintJob#HandlePausedJob](../../../../samples/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp#handlepausedjob)] [!code-csharp[DiagnoseProblematicPrintJob#HandlePausedJob](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CSharp/Program.cs#handlepausedjob)] diff --git a/docs/framework/wpf/advanced/how-to-handle-a-loaded-event.md b/docs/framework/wpf/advanced/how-to-handle-a-loaded-event.md index 50f5499a1a974..1055e1eade2bd 100644 --- a/docs/framework/wpf/advanced/how-to-handle-a-loaded-event.md +++ b/docs/framework/wpf/advanced/how-to-handle-a-loaded-event.md @@ -20,7 +20,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Handle a Loaded Event -This example shows how handle the event, and an appropriate scenario for handling that event. The handler creates a when the page loads . +This example shows how handle the event, and an appropriate scenario for handling that event. The handler creates a when the page loads . ## Example The following example uses [!INCLUDE[TLA#tla_xaml](../../../../includes/tlasharptla-xaml-md.md)] together with a code-behind file. diff --git a/docs/framework/wpf/advanced/how-to-handle-a-routed-event.md b/docs/framework/wpf/advanced/how-to-handle-a-routed-event.md index bdd8cef87ac22..0e2d05a91c610 100644 --- a/docs/framework/wpf/advanced/how-to-handle-a-routed-event.md +++ b/docs/framework/wpf/advanced/how-to-handle-a-routed-event.md @@ -24,7 +24,7 @@ This example shows how bubbling events work and how to write a handler that can ## Example In [!INCLUDE[TLA#tla_winclient](../../../../includes/tlasharptla-winclient-md.md)], elements are arranged in an element tree structure. The parent element can participate in the handling of events that are initially raised by child elements in the element tree. This is possible because of event routing. - Routed events typically follow one of two routing strategies, bubbling or tunneling. This example focuses on the bubbling event and uses the event to show how routing works. + Routed events typically follow one of two routing strategies, bubbling or tunneling. This example focuses on the bubbling event and uses the event to show how routing works. The following example creates two controls and uses [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] attribute syntax to attach an event handler to a common parent element, which in this example is . Instead of attaching individual event handlers for each child element, the example uses attribute syntax to attach the event handler to the parent element. This event-handling pattern shows how to use event routing as a technique for reducing the number of elements where a handler is attached. All the bubbling events for each route through the parent element. diff --git a/docs/framework/wpf/advanced/how-to-handle-the-contextmenuopening-event.md b/docs/framework/wpf/advanced/how-to-handle-the-contextmenuopening-event.md index 15663b27f69be..f4ce3005663a9 100644 --- a/docs/framework/wpf/advanced/how-to-handle-the-contextmenuopening-event.md +++ b/docs/framework/wpf/advanced/how-to-handle-the-contextmenuopening-event.md @@ -38,7 +38,7 @@ The event can be handl [!code-csharp[ContextMenuOpeningHandlers#AddItemNoHandle](../../../../samples/snippets/csharp/VS_Snippets_Wpf/ContextMenuOpeningHandlers/CSharp/Pane1.xaml.cs#additemnohandle)] ## Replacing the Entire Menu Before Display - An alternative scenario is if you want to replace the entire context menu. You could of course also use a variation of the preceding code, to remove every item of an existing context menu and add new ones starting with item zero. But the more intuitive approach for replacing all items in the context menu is to create a new , populate it with items, and then set the property of a control to be the new . + An alternative scenario is if you want to replace the entire context menu. You could of course also use a variation of the preceding code, to remove every item of an existing context menu and add new ones starting with item zero. But the more intuitive approach for replacing all items in the context menu is to create a new , populate it with items, and then set the property of a control to be the new . The following is the simple handler code for replacing a . The code references a custom `BuildMenu` method, which is separated out because it is called by more than one of the example handlers. @@ -54,7 +54,7 @@ The event can be handl 2. Assume that the initial value might be null, based on some preliminary logic. You could either check for null, or use a flag in your code to check whether your handler has been run at least once. Because you assume that the is about to be displayed, your handler then sets to `true` in the event data. To the that is responsible for context menu display, a `true` value for in the event data represents a request to cancel the display for the context menu / control combination that raised the event. - Now that you have suppressed the potentially suspect context menu, the next step is to supply a new one, then display it. Setting the new one is basically the same as the previous handler: you build a new and set the control source's property with it. The additional step is that you must now force the display of the context menu, because you suppressed the first attempt. To force the display, you set the property to `true` within the handler. Be careful when you do this, because opening the context menu in the handler raises the event again. If you reenter your handler, it becomes infinitely recursive. This is why you always need to check for `null` or use a flag if you open a context menu from within a event handler. + Now that you have suppressed the potentially suspect context menu, the next step is to supply a new one, then display it. Setting the new one is basically the same as the previous handler: you build a new and set the control source's property with it. The additional step is that you must now force the display of the context menu, because you suppressed the first attempt. To force the display, you set the property to `true` within the handler. Be careful when you do this, because opening the context menu in the handler raises the event again. If you reenter your handler, it becomes infinitely recursive. This is why you always need to check for `null` or use a flag if you open a context menu from within a event handler. ## Suppressing Any Existing Context Menu and Displaying No Context Menu The final scenario, writing a handler that suppresses a menu totally, is uncommon. If a given control is not supposed to display a context menu, there are probably more appropriate ways to assure this than by suppressing the menu just when a user requests it. But if you want to use the handler to suppress a context menu and show nothing, then your handler should simply set to `true` in the event data. The that is responsible for displaying a context menu will check the event data of the event it raised on the control. If the event was marked anywhere along the route, then the context menu open action that initiated the event is suppressed. @@ -63,6 +63,6 @@ The event can be handl ## See Also - + [Base Elements Overview](../../../../docs/framework/wpf/advanced/base-elements-overview.md) [ContextMenu Overview](../../../../docs/framework/wpf/controls/contextmenu-overview.md) diff --git a/docs/framework/wpf/advanced/how-to-invoke-a-print-dialog.md b/docs/framework/wpf/advanced/how-to-invoke-a-print-dialog.md index 903fc4a8e5119..21c63f5369ba3 100644 --- a/docs/framework/wpf/advanced/how-to-invoke-a-print-dialog.md +++ b/docs/framework/wpf/advanced/how-to-invoke-a-print-dialog.md @@ -30,7 +30,7 @@ To provide the ability to print from you application, you can simply create and Once the dialog is open, users will be able to select from the printers installed on their computer. They will also have the option of selecting the [Microsoft XPS Document Writer](http://go.microsoft.com/fwlink/?LinkId=147319) to create an [!INCLUDE[TLA#tla_xps](../../../../includes/tlasharptla-xps-md.md)] file instead of printing. > [!NOTE] -> The control of [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)], which is discussed in this topic, should not be confused with the component of [!INCLUDE[TLA2#tla_winforms](../../../../includes/tla2sharptla-winforms-md.md)]. +> The control of [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)], which is discussed in this topic, should not be confused with the component of [!INCLUDE[TLA2#tla_winforms](../../../../includes/tla2sharptla-winforms-md.md)]. Strictly speaking, you can use the method without ever opening the dialog. In that sense, the control can be used as an unseen printing component. But for performance reasons, it would be better to use either the method or one of the many and methods of the . For more about this, see [Programmatically Print XPS Files](../../../../docs/framework/wpf/advanced/how-to-programmatically-print-xps-files.md) and . diff --git a/docs/framework/wpf/advanced/how-to-select-ink-from-a-custom-control.md b/docs/framework/wpf/advanced/how-to-select-ink-from-a-custom-control.md index 40b06f3568b99..05822b5c98240 100644 --- a/docs/framework/wpf/advanced/how-to-select-ink-from-a-custom-control.md +++ b/docs/framework/wpf/advanced/how-to-select-ink-from-a-custom-control.md @@ -73,7 +73,7 @@ By adding an to your custom [!code-csharp[HowToSelectInk#10](../../../../samples/snippets/csharp/VS_Snippets_Wpf/HowToSelectInk/CSharp/InkSelector.cs#10)] [!code-vb[HowToSelectInk#10](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/HowToSelectInk/VisualBasic/InkSelector.vb#10)] - Handle the event to respond when the user selects and unselects strokes. The class has the and properties that get the strokes that were selected and unselected, respectively. + Handle the event to respond when the user selects and unselects strokes. The class has the and properties that get the strokes that were selected and unselected, respectively. [!code-csharp[HowToSelectInk#11](../../../../samples/snippets/csharp/VS_Snippets_Wpf/HowToSelectInk/CSharp/InkSelector.cs#11)] [!code-vb[HowToSelectInk#11](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/HowToSelectInk/VisualBasic/InkSelector.vb#11)] diff --git a/docs/framework/wpf/advanced/initialization-for-object-elements-not-in-an-object-tree.md b/docs/framework/wpf/advanced/initialization-for-object-elements-not-in-an-object-tree.md index b1a9a947661dd..3844d058ff431 100644 --- a/docs/framework/wpf/advanced/initialization-for-object-elements-not-in-an-object-tree.md +++ b/docs/framework/wpf/advanced/initialization-for-object-elements-not-in-an-object-tree.md @@ -38,7 +38,7 @@ Some aspects of [!INCLUDE[TLA#tla_winclient](../../../../includes/tlasharptla-wi If the element you are setting properties on is a or derived class, then you can call the class versions of and rather than casting to . ### Sample Code - The following example is sample code for a console application that uses rendering [!INCLUDE[TLA2#tla_api#plural](../../../../includes/tla2sharptla-apisharpplural-md.md)] and of a loose [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] file to illustrate the proper placement of and around other [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] calls that adjust properties that affect rendering. + The following example is sample code for a console application that uses rendering [!INCLUDE[TLA2#tla_api#plural](../../../../includes/tla2sharptla-apisharpplural-md.md)] and of a loose [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] file to illustrate the proper placement of and around other [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] calls that adjust properties that affect rendering. The example illustrates the main function only. The functions `Rasterize` and `Save` (not shown) are utility functions that take care of image processing and IO. diff --git a/docs/framework/wpf/advanced/input-overview.md b/docs/framework/wpf/advanced/input-overview.md index 101918f3891f0..c866fb9765d10 100644 --- a/docs/framework/wpf/advanced/input-overview.md +++ b/docs/framework/wpf/advanced/input-overview.md @@ -119,7 +119,7 @@ manager: "wpickett" For keyboard input, [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] first sends the appropriate / events. If those events are not handled and the key is textual (rather than a control key such as directional arrows or function keys), then a event is raised. There is not always a simple one-to-one mapping between / and events because multiple keystrokes can generate a single character of text input and single keystrokes can generate multi-character strings. This is especially true for languages such as Chinese, Japanese, and Korean which use [!INCLUDE[TLA#tla_ime#plural](../../../../includes/tlasharptla-imesharpplural-md.md)] to generate the thousands of possible characters in their corresponding alphabets. - When [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] sends a / event, is set to if the keystrokes could become part of a event (if ALT+S is pressed, for example). This allows code in a event handler to check for and, if found, leave processing for the handler of the subsequently raised event. In these cases, the various properties of the argument can be used to determine the original keystrokes. Similarly, if an [!INCLUDE[TLA2#tla_ime](../../../../includes/tla2sharptla-ime-md.md)] is active, has the value of , and gives the original keystroke or keystrokes. + When [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] sends a / event, is set to if the keystrokes could become part of a event (if ALT+S is pressed, for example). This allows code in a event handler to check for and, if found, leave processing for the handler of the subsequently raised event. In these cases, the various properties of the argument can be used to determine the original keystrokes. Similarly, if an [!INCLUDE[TLA2#tla_ime](../../../../includes/tla2sharptla-ime-md.md)] is active, has the value of , and gives the original keystroke or keystrokes. The following example defines a handler for the event and a handler for the event. @@ -186,7 +186,7 @@ manager: "wpickett" - - The defines the attached property that enables you to specify whether touch panning is enabled horizontally, vertically, both, or neither. The property specifies how quickly the scrolling slows down when the user lifts the finger from the touchscreen. The attached property specifies the ratio of scrolling offset to translate manipulation offset. + The defines the attached property that enables you to specify whether touch panning is enabled horizontally, vertically, both, or neither. The property specifies how quickly the scrolling slows down when the user lifts the finger from the touchscreen. The attached property specifies the ratio of scrolling offset to translate manipulation offset. ### Touch Events The base classes, , , and , define events that you can subscribe to so your application will respond to touch. Touch events are useful when your application interprets touch as something other than manipulating an object. For example, an application that enables a user to draw with one or more fingers would subscribe to touch events. @@ -263,7 +263,7 @@ Touch events - - By default, a does not receive these manipulation events. To receive manipulation events on a , set to `true`. + By default, a does not receive these manipulation events. To receive manipulation events on a , set to `true`. #### The Execution Path of Manipulation Events Consider a scenario where a user "throws" an object. The user puts a finger on the object, moves the finger across the touchscreen for a short distance, and then lifts the finger while it is moving. The result of this is that the object will move under the user's finger and continue to move after the user lifts the finger. @@ -283,7 +283,7 @@ Manipulation events 4. The event occurs when the user's fingers lose contact with the object. This event enables you to specify the deceleration of the manipulations during inertia. This is so your object can emulate different physical spaces or attributes if you choose. For example, suppose your application has two objects that represent items in the physical world, and one is heavier than the other. You can make the heavier object decelerate faster than the lighter object. -5. The event occurs multiple times as inertia occurs. Note that this event occurs when the user's fingers move across the touchscreen and when [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] simulates inertia. In other words, occurs before and after the event. The property reports whether the event occurs during inertia, so you can check that property and perform different actions, depending on its value. +5. The event occurs multiple times as inertia occurs. Note that this event occurs when the user's fingers move across the touchscreen and when [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] simulates inertia. In other words, occurs before and after the event. The property reports whether the event occurs during inertia, so you can check that property and perform different actions, depending on its value. 6. The event occurs when the manipulation and any inertia ends. That is, after all the events occur, the event occurs to signal that the manipulation is complete. @@ -309,7 +309,7 @@ Touch and manipulation events - When the first touch device generates a event on a , the manipulation logic calls the method, which generates the event. -- When the occurs, the manipulation logic calls the method, which generates the event. +- When the occurs, the manipulation logic calls the method, which generates the event. - When the events occur, the manipulation logic generates the events that occur before the event. @@ -334,7 +334,7 @@ Touch and manipulation events For more information about keyboard focus, see [Focus Overview](../../../../docs/framework/wpf/advanced/focus-overview.md). ### Logical Focus - Logical focus refers to the in a focus scope. There can be multiple elements that have logical focus in an application, but there may only be one element that has logical focus in a particular focus scope. + Logical focus refers to the in a focus scope. There can be multiple elements that have logical focus in an application, but there may only be one element that has logical focus in a particular focus scope. A focus scope is a container element that keeps track of the within its scope. When focus leaves a focus scope, the focused element will lose keyboard focus but will retain logical focus. When focus returns to the focus scope, the focused element will obtain keyboard focus. This allows for keyboard focus to be changed between multiple focus scopes but insures that the focused element within the focus scope remains the focused element when focus returns. diff --git a/docs/framework/wpf/advanced/layout-considerations-for-the-windowsformshost-element.md b/docs/framework/wpf/advanced/layout-considerations-for-the-windowsformshost-element.md index c88383d1d5034..20bf7817c4d14 100644 --- a/docs/framework/wpf/advanced/layout-considerations-for-the-windowsformshost-element.md +++ b/docs/framework/wpf/advanced/layout-considerations-for-the-windowsformshost-element.md @@ -37,7 +37,7 @@ This topic describes how the and .| +|Anchoring and docking|[!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls support positioning and sizing based on the parent container. For more information, see and .| |Autoscaling|Container controls resize themselves and their children based on the resolution of the output device or the size, in pixels, of the default container font. For more information, see [Automatic Scaling in Windows Forms](../../../../docs/framework/winforms/automatic-scaling-in-windows-forms.md).| |Layout containers|The and controls arrange their child controls and size themselves according to their contents.| diff --git a/docs/framework/wpf/advanced/merged-resource-dictionaries.md b/docs/framework/wpf/advanced/merged-resource-dictionaries.md index 880b532666d33..656b178c15a67 100644 --- a/docs/framework/wpf/advanced/merged-resource-dictionaries.md +++ b/docs/framework/wpf/advanced/merged-resource-dictionaries.md @@ -35,7 +35,7 @@ manager: "wpickett" Resources in a merged dictionary occupy a location in the resource lookup scope that is just after the scope of the main resource dictionary they are merged into. Although a resource key must be unique within any individual dictionary, a key can exist multiple times in a set of merged dictionaries. In this case, the resource that is returned will come from the last dictionary found sequentially in the collection. If the collection was defined in [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)], then the order of the merged dictionaries in the collection is the order of the elements as provided in the markup. If a key is defined in the primary dictionary and also in a dictionary that was merged, then the resource that is returned will come from the primary dictionary. These scoping rules apply equally for both static resource references and dynamic resource references. ### Merged Dictionaries and Code - Merged dictionaries can be added to a `Resources` dictionary through code. The default, initially empty that exists for any `Resources` property also has a default, initially empty collection property. To add a merged dictionary through code, you obtain a reference to the desired primary , get its property value, and call `Add` on the generic `Collection` that is contained in . The object you add must be a new . In code, you do not set the property. Instead, you must obtain a object by either creating one or loading one. One way to load an existing to call on an existing [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] file stream that has a root, then casting the return value to . + Merged dictionaries can be added to a `Resources` dictionary through code. The default, initially empty that exists for any `Resources` property also has a default, initially empty collection property. To add a merged dictionary through code, you obtain a reference to the desired primary , get its property value, and call `Add` on the generic `Collection` that is contained in . The object you add must be a new . In code, you do not set the property. Instead, you must obtain a object by either creating one or loading one. One way to load an existing to call on an existing [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] file stream that has a root, then casting the return value to . ### Merged Resource Dictionary URIs There are several techniques for how to include a merged resource dictionary, which are indicated by the [!INCLUDE[TLA#tla_uri](../../../../includes/tlasharptla-uri-md.md)] format that you will use. Broadly speaking, these techniques can be divided into two categories: resources that are compiled as part of the project, and resources that are not compiled as part of the project. diff --git a/docs/framework/wpf/advanced/opentype-font-features.md b/docs/framework/wpf/advanced/opentype-font-features.md index e62aee59e7dff..03c7ae79a66ad 100644 --- a/docs/framework/wpf/advanced/opentype-font-features.md +++ b/docs/framework/wpf/advanced/opentype-font-features.md @@ -320,7 +320,7 @@ Text using OpenType capitals |Property|Value(s)|Default Value| |--------------|----------------|-------------------| ||Numeric value - byte|0| -|| | | | | | | || +|| | | | | | | || |||`false`| |||`false`| |||`true`| @@ -328,15 +328,15 @@ Text using OpenType capitals ||Numeric value - byte|0| |||`false`| |||`false`| -|| | | | | | | | | | || -|| | | | | | || -|| | | || +|| | | | | | | | | | || +|| | | | | | || +|| | | || |||`false`| |||`false`| |||`true`| |||`false`| -|| | | || -|||| +|| | | || +|||| |||`false`| |||`true`| ||numeric value – byte|0| @@ -361,7 +361,7 @@ Text using OpenType capitals |||`false`| |||`false`| |||`false`| -|| | | | | | || +|| | | | | | || ## See Also diff --git a/docs/framework/wpf/advanced/optimizing-performance-controls.md b/docs/framework/wpf/advanced/optimizing-performance-controls.md index 377bbbc2cd737..85d1ac51f0939 100644 --- a/docs/framework/wpf/advanced/optimizing-performance-controls.md +++ b/docs/framework/wpf/advanced/optimizing-performance-controls.md @@ -30,7 +30,7 @@ manager: "wpickett" UI Virtualization is an important aspect of list controls. UI virtualization should not be confused with data virtualization. UI virtualization stores only visible items in memory but in a data-binding scenario stores the entire data structure in memory. In contrast, data virtualization stores only the data items that are visible on the screen in memory. - By default, UI virtualization is enabled for the and controls when their list items are bound to data. virtualization can be enabled by setting the `IsVirtualizing` attached property to `true`. If you want to enable UI virtualization for custom controls that derive from or existing item controls that use the class, such as , you can set the to and set to `true`. Unfortunately, you can disable UI virtualization for these controls without realizing it. The following is a list of conditions that disable UI virtualization. + By default, UI virtualization is enabled for the and controls when their list items are bound to data. virtualization can be enabled by setting the `IsVirtualizing` attached property to `true`. If you want to enable UI virtualization for custom controls that derive from or existing item controls that use the class, such as , you can set the to and set to `true`. Unfortunately, you can disable UI virtualization for these controls without realizing it. The following is a list of conditions that disable UI virtualization. - Item containers are added directly to the . For example, if an application explicitly adds objects to a , the does not virtualize the objects. diff --git a/docs/framework/wpf/advanced/optimizing-performance-other-recommendations.md b/docs/framework/wpf/advanced/optimizing-performance-other-recommendations.md index d0025658abbc3..019143482494f 100644 --- a/docs/framework/wpf/advanced/optimizing-performance-other-recommendations.md +++ b/docs/framework/wpf/advanced/optimizing-performance-other-recommendations.md @@ -40,7 +40,7 @@ manager: "wpickett" ## Opacity on Brushes Versus Opacity on Elements - When you use a to set the or of an element, it is better to set the value rather than the setting the element's property. Modifying an element's property can cause [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] to create a temporary surface. + When you use a to set the or of an element, it is better to set the value rather than the setting the element's property. Modifying an element's property can cause [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] to create a temporary surface. ## Navigation to Object @@ -63,11 +63,11 @@ manager: "wpickett" ## CompositionTarget.Rendering Event - The event causes [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] to continuously animate. If you use this event, detach it at every opportunity. + The event causes [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] to continuously animate. If you use this event, detach it at every opportunity. ## Avoid Using ScrollBarVisibility=Auto - Whenever possible, avoid using the value for the `HorizontalScrollBarVisibility` and `VerticalScrollBarVisibility` properties. These properties are defined for , , and objects, and as an attached property for the object. Instead, set to , , or . + Whenever possible, avoid using the value for the `HorizontalScrollBarVisibility` and `VerticalScrollBarVisibility` properties. These properties are defined for , , and objects, and as an attached property for the object. Instead, set to , , or . The value is intended for cases when space is limited and scrollbars should only be displayed when necessary. For example, it may be useful to use this value with a of 30 items as opposed to a with hundreds of lines of text. diff --git a/docs/framework/wpf/advanced/printing-overview.md b/docs/framework/wpf/advanced/printing-overview.md index 83d1cfc9bdba9..62109e415c362 100644 --- a/docs/framework/wpf/advanced/printing-overview.md +++ b/docs/framework/wpf/advanced/printing-overview.md @@ -80,7 +80,7 @@ With [!INCLUDE[TLA#tla_winfx](../../../../includes/tlasharptla-winfx-md.md)], ap [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] defines both a basic and advanced [!INCLUDE[TLA#tla_api](../../../../includes/tlasharptla-api-md.md)]. For those applications that do not require extensive print customization or access to the complete [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] feature set, basic print support is available. Basic print support is exposed through a print dialog control that requires minimal configuration and features a familiar [!INCLUDE[TLA2#tla_ui](../../../../includes/tla2sharptla-ui-md.md)]. Many [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] features are available using this simplified print model. #### PrintDialog - The control provides a single entry point for [!INCLUDE[TLA2#tla_ui](../../../../includes/tla2sharptla-ui-md.md)], configuration, and [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] job submission. For information about how to instantiate and use the control, see [Invoke a Print Dialog](../../../../docs/framework/wpf/advanced/how-to-invoke-a-print-dialog.md). + The control provides a single entry point for [!INCLUDE[TLA2#tla_ui](../../../../includes/tla2sharptla-ui-md.md)], configuration, and [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] job submission. For information about how to instantiate and use the control, see [Invoke a Print Dialog](../../../../docs/framework/wpf/advanced/how-to-invoke-a-print-dialog.md). ### Advanced XPS Printing To access the complete set of [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] features, the advanced print [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] must be used. Several relevant [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] are described in greater detail below. For a complete list of [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] print path [!INCLUDE[TLA2#tla_api#plural](../../../../includes/tla2sharptla-apisharpplural-md.md)], see the and namespace references. diff --git a/docs/framework/wpf/advanced/propertypath-xaml-syntax.md b/docs/framework/wpf/advanced/propertypath-xaml-syntax.md index 873348122354e..60a673e23c80a 100644 --- a/docs/framework/wpf/advanced/propertypath-xaml-syntax.md +++ b/docs/framework/wpf/advanced/propertypath-xaml-syntax.md @@ -28,7 +28,7 @@ The object supports a complex inline [!INCLUD Primarily, [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] uses to describe object-model paths for traversing the properties of an object data source, and to describe the target path for targeted animations. - Some style and template properties such as take a qualified property name that superficially resembles a . But this is not a true ; instead it is a qualified *owner.property* string format usage that is enabled by the WPF [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] processor in combination with the type converter for . + Some style and template properties such as take a qualified property name that superficially resembles a . But this is not a true ; instead it is a qualified *owner.property* string format usage that is enabled by the WPF [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] processor in combination with the type converter for . ## PropertyPath for Objects in Data Binding @@ -56,7 +56,7 @@ The object supports a complex inline [!INCLUD `key` must be either the typed index to a dictionary or hash table, or the integer index of an array. Also, the value of the key must be a type that is directly bindable to the property where it is applied. For instance, a hash table that contains string keys and string values can be used this way to bind to Text for a . Or, if the key points to a collection or subindex, you could use this syntax to bind to a target collection property. Otherwise, you need to reference a specific property, through a syntax such as ``. - You can specify the type of the index if necessary. For details on this aspect of an indexed property path, see . + You can specify the type of the index if necessary. For details on this aspect of an indexed property path, see . ### Multiple Property (Indirect Property Targeting) @@ -112,7 +112,7 @@ or If a given object supports multiple indexers, those indexers can be specified in order, similar to an array referencing syntax. The object in question can be either the current context or the value of a property that contains a multiple index object. - By default, the indexer values are typed by using the characteristics of the underlying object. You can specify the type of the index if necessary. For details on typing the indexers, see . + By default, the indexer values are typed by using the characteristics of the underlying object. You can specify the type of the index if necessary. For details on typing the indexers, see . ### Mixing Syntaxes diff --git a/docs/framework/wpf/advanced/resources-and-code.md b/docs/framework/wpf/advanced/resources-and-code.md index 98cf1c5842cc0..137301dc0f59d 100644 --- a/docs/framework/wpf/advanced/resources-and-code.md +++ b/docs/framework/wpf/advanced/resources-and-code.md @@ -43,7 +43,7 @@ This overview concentrates on how [!INCLUDE[TLA#tla_winclient](../../../../inclu ## Creating Resources with Code - If you want to create an entire [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] application in code, you might also want to create any resources in that application in code. To achieve this, create a new instance, and then add all the resources to the dictionary using successive calls to . Then, use the thus created to set the property on an element that is present in a page scope, or the . You could also maintain the as a standalone object without adding it to an element. However, if you do this, you must access the resources within it by item key, as if it were a generic dictionary. A that is not attached to an element `Resources` property would not exist as part of the element tree and has no scope in a lookup sequence that can be used by and related methods. + If you want to create an entire [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] application in code, you might also want to create any resources in that application in code. To achieve this, create a new instance, and then add all the resources to the dictionary using successive calls to . Then, use the thus created to set the property on an element that is present in a page scope, or the . You could also maintain the as a standalone object without adding it to an element. However, if you do this, you must access the resources within it by item key, as if it were a generic dictionary. A that is not attached to an element `Resources` property would not exist as part of the element tree and has no scope in a lookup sequence that can be used by and related methods. ## Using Objects as Keys diff --git a/docs/framework/wpf/advanced/routed-events-overview.md b/docs/framework/wpf/advanced/routed-events-overview.md index ebf59212e07de..938d3ee92d983 100644 --- a/docs/framework/wpf/advanced/routed-events-overview.md +++ b/docs/framework/wpf/advanced/routed-events-overview.md @@ -182,7 +182,7 @@ This topic describes the concept of routed events in [!INCLUDE[TLA#tla_winclient ## Attached Events in WPF The [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] language also defines a special type of event called an *attached event*. An attached event enables you to add a handler for a particular event to an arbitrary element. The element handling the event need not define or inherit the attached event, and neither the object potentially raising the event nor the destination handling instance must define or otherwise "own" that event as a class member. - The [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] input system uses attached events extensively. However, nearly all of these attached events are forwarded through base elements. The input events then appear as equivalent non-attached routed events that are members of the base element class. For instance, the underlying attached event can more easily be handled on any given by using on that rather than dealing with attached event syntax either in [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] or code. + The [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] input system uses attached events extensively. However, nearly all of these attached events are forwarded through base elements. The input events then appear as equivalent non-attached routed events that are members of the base element class. For instance, the underlying attached event can more easily be handled on any given by using on that rather than dealing with attached event syntax either in [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] or code. For more information about attached events in [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)], see [Attached Events Overview](../../../../docs/framework/wpf/advanced/attached-events-overview.md). diff --git a/docs/framework/wpf/advanced/staticresource-markup-extension.md b/docs/framework/wpf/advanced/staticresource-markup-extension.md index 21a054ce40a69..39fe68ec237f7 100644 --- a/docs/framework/wpf/advanced/staticresource-markup-extension.md +++ b/docs/framework/wpf/advanced/staticresource-markup-extension.md @@ -44,7 +44,7 @@ Provides a value for any [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharp ||| |-|-| -|`key`|The key for the requested resource. This key was initially assigned by the [x:Key Directive](../../../../docs/framework/xaml-services/x-key-directive.md) if a resource was created in markup, or was provided as the `key` parameter when calling if the resource was created in code.| +|`key`|The key for the requested resource. This key was initially assigned by the [x:Key Directive](../../../../docs/framework/xaml-services/x-key-directive.md) if a resource was created in markup, or was provided as the `key` parameter when calling if the resource was created in code.| ## Remarks diff --git a/docs/framework/wpf/advanced/templatebinding-markup-extension.md b/docs/framework/wpf/advanced/templatebinding-markup-extension.md index f8175d93a8bb6..493c1ecef905b 100644 --- a/docs/framework/wpf/advanced/templatebinding-markup-extension.md +++ b/docs/framework/wpf/advanced/templatebinding-markup-extension.md @@ -40,8 +40,8 @@ Links the value of a property in a control template to be the value of another p ||| |-|-| -|`propertyName`| of the property being set in the setter syntax.| -|`sourceProperty`|Another dependency property that exists on the type being templated, specified by its .

- or -

A "dotted-down" property name that is defined by a different type than the target type being templated. This is actually a . See [PropertyPath XAML Syntax](../../../../docs/framework/wpf/advanced/propertypath-xaml-syntax.md).| +|`propertyName`| of the property being set in the setter syntax.| +|`sourceProperty`|Another dependency property that exists on the type being templated, specified by its .

- or -

A "dotted-down" property name that is defined by a different type than the target type being templated. This is actually a . See [PropertyPath XAML Syntax](../../../../docs/framework/wpf/advanced/propertypath-xaml-syntax.md).| ## Remarks A `TemplateBinding` is an optimized form of a [Binding](../../../../docs/framework/wpf/advanced/binding-markup-extension.md) for template scenarios, analogous to a `Binding` constructed with `{Binding RelativeSource={RelativeSource TemplatedParent}}`. A `TemplateBinding` is always a one-way binding, even if properties involved default to two-way binding. Both properties involved must be dependency properties. diff --git a/docs/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md b/docs/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md index 1c2defdf55655..ae2d4c2020272 100644 --- a/docs/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md +++ b/docs/framework/wpf/advanced/the-ink-object-model-windows-forms-and-com-versus-wpf.md @@ -35,15 +35,15 @@ There are essentially three platforms that support digital ink: the Tablet PC Wi |Enable ink on a custom control|See [Creating an Ink Input Control](../../../../docs/framework/wpf/advanced/creating-an-ink-input-control.md).|See [Ink Clipboard Sample](http://msdn.microsoft.com/a0c42f1c-543d-44f8-83d9-fe810de410ff).| ## Ink Data - On the Windows Forms and COM platforms, [Microsoft.Ink.InkCollector](https://msdn.microsoft.com/library/ms836493.aspx), [Microsoft.Ink.InkOverlay](https://msdn.microsoft.com/library/ms833057.aspx), [Microsoft.Ink.InkEdit](https://msdn.microsoft.com/library/ms835842.aspx), and [Microsoft.Ink.InkPicture](https://msdn.microsoft.com/library/aa514604.aspx) each expose a [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx?displayProperty=fullName) object. The [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object contains the data for one or more [Microsoft.Ink.Stroke](https://msdn.microsoft.com/library/ms827842.aspx?displayProperty=fullName) objects and exposes common methods and properties to manage and manipulate those strokes. The [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object manages the lifetime of the strokes it contains; the [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object creates and deletes the strokes that it owns. Each [Microsoft.Ink.Stroke](https://msdn.microsoft.com/library/ms827842.aspx) has an identifier that is unique within its parent [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object. + On the Windows Forms and COM platforms, [Microsoft.Ink.InkCollector](https://msdn.microsoft.com/library/ms836493.aspx), [Microsoft.Ink.InkOverlay](https://msdn.microsoft.com/library/ms833057.aspx), [Microsoft.Ink.InkEdit](https://msdn.microsoft.com/library/ms835842.aspx), and [Microsoft.Ink.InkPicture](https://msdn.microsoft.com/library/aa514604.aspx) each expose a [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx?displayProperty=nameWithType) object. The [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object contains the data for one or more [Microsoft.Ink.Stroke](https://msdn.microsoft.com/library/ms827842.aspx?displayProperty=nameWithType) objects and exposes common methods and properties to manage and manipulate those strokes. The [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object manages the lifetime of the strokes it contains; the [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object creates and deletes the strokes that it owns. Each [Microsoft.Ink.Stroke](https://msdn.microsoft.com/library/ms827842.aspx) has an identifier that is unique within its parent [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx) object. - On the WPF platform, the class owns and manages its own lifetime. A group of objects can be collected together in a , which provides methods for common ink data management operations such as hit testing, erasing, transforming, and serializing the ink. A can belong to zero, one, or more objects at any give time. Instead of having a [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx?displayProperty=fullName) object, the and contain a . + On the WPF platform, the class owns and manages its own lifetime. A group of objects can be collected together in a , which provides methods for common ink data management operations such as hit testing, erasing, transforming, and serializing the ink. A can belong to zero, one, or more objects at any give time. Instead of having a [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx?displayProperty=nameWithType) object, the and contain a . - The following pair of illustrations compares the ink data object models. On the Windows Forms and COM platforms, the [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx?displayProperty=fullName) object constrains the lifetime of the [Microsoft.Ink.Stroke](https://msdn.microsoft.com/library/ms827842.aspx?displayProperty=fullName) objects, and the stylus packets belong to the individual strokes. Two or more strokes can reference the same [Microsoft.Ink.DrawingAttributes](https://msdn.microsoft.com/library/ms837931.aspx?displayProperty=fullName) object, as shown in the following illustration. + The following pair of illustrations compares the ink data object models. On the Windows Forms and COM platforms, the [Microsoft.Ink.Ink](https://msdn.microsoft.com/library/aa515768.aspx?displayProperty=nameWithType) object constrains the lifetime of the [Microsoft.Ink.Stroke](https://msdn.microsoft.com/library/ms827842.aspx?displayProperty=nameWithType) objects, and the stylus packets belong to the individual strokes. Two or more strokes can reference the same [Microsoft.Ink.DrawingAttributes](https://msdn.microsoft.com/library/ms837931.aspx?displayProperty=nameWithType) object, as shown in the following illustration. ![Diagram of the Ink Object Model for COM/Winforms.](../../../../docs/framework/wpf/advanced/media/ink-inkownsstrokes.png "Ink_InkOwnsStrokes") - On the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)], each is a common language runtime object that exists as long as something has a reference to it. Each references a and object, which are also common language runtime objects. + On the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)], each is a common language runtime object that exists as long as something has a reference to it. Each references a and object, which are also common language runtime objects. ![Diagram of the Ink Object Model for WPF.](../../../../docs/framework/wpf/advanced/media/ink-wpfinkobjectmodel.png "Ink_WPFInkObjectModel") diff --git a/docs/framework/wpf/advanced/themedictionary-markup-extension.md b/docs/framework/wpf/advanced/themedictionary-markup-extension.md index 5d10ce324a606..471da5e7540da 100644 --- a/docs/framework/wpf/advanced/themedictionary-markup-extension.md +++ b/docs/framework/wpf/advanced/themedictionary-markup-extension.md @@ -47,7 +47,7 @@ Provides a way for custom control authors or applications that integrate third-p |`assemblyUri`|The [!INCLUDE[TLA#tla_uri](../../../../includes/tlasharptla-uri-md.md)] of the assembly that contains theme information. Typically, this is a pack URI that references an assembly in the larger package. Assembly resources and pack URIs simplify deployment issues. For more information see [Pack URIs in WPF](../../../../docs/framework/wpf/app-development/pack-uris-in-wpf.md).| ## Remarks - This extension is intended to fill only one specific property value: a value for . + This extension is intended to fill only one specific property value: a value for . By using this extension, you can specify a single resources-only assembly that contains some styles to use only when the [!INCLUDE[TLA#tla_aero](../../../../includes/tlasharptla-aero-md.md)] theme is applied to the user's system, other styles when Luna theme is active, and so on. By using this extension, the contents of a control-specific resource dictionary can be automatically invalidated and reloaded to be specific for another theme when required. diff --git a/docs/framework/wpf/advanced/threading-model.md b/docs/framework/wpf/advanced/threading-model.md index 92eb3d8c15745..8837b42ac4086 100644 --- a/docs/framework/wpf/advanced/threading-model.md +++ b/docs/framework/wpf/advanced/threading-model.md @@ -40,7 +40,7 @@ manager: "wpickett" > [!NOTE] -> This topic discusses threading by using the method for asynchronous calls. You can also make asynchronous calls by calling the method, which take an or as a parameter. The method returns a or , which has a property. You can use the `await` keyword with either the or the associated . If you need to wait synchronously for the that is returned by a or , call the extension method. Calling will result in a deadlock. For more information about using a to perform asynchronous operations, see Task Parallelism. The method also has overloads that take an or as a parameter. You can use the method to make synchronous calls by passing in a delegate, or . +> This topic discusses threading by using the method for asynchronous calls. You can also make asynchronous calls by calling the method, which take an or as a parameter. The method returns a or , which has a property. You can use the `await` keyword with either the or the associated . If you need to wait synchronously for the that is returned by a or , call the extension method. Calling will result in a deadlock. For more information about using a to perform asynchronous operations, see Task Parallelism. The method also has overloads that take an or as a parameter. You can use the method to make synchronous calls by passing in a delegate, or . ## Overview and the Dispatcher diff --git a/docs/framework/wpf/advanced/troubleshooting-hybrid-applications.md b/docs/framework/wpf/advanced/troubleshooting-hybrid-applications.md index ef3d02342bf28..0bc43eb934d30 100644 --- a/docs/framework/wpf/advanced/troubleshooting-hybrid-applications.md +++ b/docs/framework/wpf/advanced/troubleshooting-hybrid-applications.md @@ -37,7 +37,7 @@ manager: "wpickett" ## Child Property - The and classes can host only a single child control or element. To host more than one control or element, you must use a container as the child content. For example, you could add [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] button and check box controls to a control, and then assign the panel to a control's property. However, you cannot add the button and check box controls separately to the same control. + The and classes can host only a single child control or element. To host more than one control or element, you must use a container as the child content. For example, you could add [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] button and check box controls to a control, and then assign the panel to a control's property. However, you cannot add the button and check box controls separately to the same control. ## Scaling @@ -45,7 +45,7 @@ manager: "wpickett" ## Adapter - There may be confusion when working the and classes, because they include a hidden container. Both the and classes have a hidden container, called an *adapter*, which they use to host content. For the element, the adapter derives from the class. For the control, the adapter derives from the element. When you see references to the adapter in other interoperation topics, this container is what is being discussed. + There may be confusion when working the and classes, because they include a hidden container. Both the and classes have a hidden container, called an *adapter*, which they use to host content. For the element, the adapter derives from the class. For the control, the adapter derives from the element. When you see references to the adapter in other interoperation topics, this container is what is being discussed. ## Nesting @@ -63,7 +63,7 @@ manager: "wpickett" ## Layout-related Properties on Hosted Content - When the or property is assigned, several layout-related properties on the hosted content are set automatically. Changing these content properties can cause unexpected layout behaviors. + When the or property is assigned, several layout-related properties on the hosted content are set automatically. Changing these content properties can cause unexpected layout behaviors. Your hosted content is docked to fill the and parent. To enable this fill behavior, several properties are set when you set the child property. The following table lists which content properties are set by the and classes. @@ -80,9 +80,9 @@ manager: "wpickett" ## Message Loop Interoperation - When working with [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] message loops, messages may not be processed as expected. The method is called by the constructor. This method adds a message filter to the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] message loop. This filter calls the method if a was the target of the message and translates/dispatches the message. + When working with [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] message loops, messages may not be processed as expected. The method is called by the constructor. This method adds a message filter to the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] message loop. This filter calls the method if a was the target of the message and translates/dispatches the message. - If you show a in a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] message loop with , you cannot type anything unless you call the method. The method takes a and adds a , which reroutes key-related messages to the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] message loop. For more information, see [Windows Forms and WPF Interoperability Input Architecture](../../../../docs/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md). + If you show a in a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] message loop with , you cannot type anything unless you call the method. The method takes a and adds a , which reroutes key-related messages to the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] message loop. For more information, see [Windows Forms and WPF Interoperability Input Architecture](../../../../docs/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md). ## Opacity and Layering @@ -94,13 +94,13 @@ manager: "wpickett" ## Enabling Visual Styles - [!INCLUDE[TLA#tla_winxp](../../../../includes/tlasharptla-winxp-md.md)] visual styles on a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control may not be enabled. The method is called in the template for a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] application. Although this method is not called by default, if you use [!INCLUDE[TLA2#tla_visualstu](../../../../includes/tla2sharptla-visualstu-md.md)] to create a project, you will get [!INCLUDE[TLA#tla_winxp](../../../../includes/tlasharptla-winxp-md.md)] visual styles for controls, if version 6.0 of Comctl32.dll is available. You must call the method before handles are created on the thread. For more information, see [How to: Enable Visual Styles in a Hybrid Application](../../../../docs/framework/wpf/advanced/how-to-enable-visual-styles-in-a-hybrid-application.md). + [!INCLUDE[TLA#tla_winxp](../../../../includes/tlasharptla-winxp-md.md)] visual styles on a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control may not be enabled. The method is called in the template for a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] application. Although this method is not called by default, if you use [!INCLUDE[TLA2#tla_visualstu](../../../../includes/tla2sharptla-visualstu-md.md)] to create a project, you will get [!INCLUDE[TLA#tla_winxp](../../../../includes/tlasharptla-winxp-md.md)] visual styles for controls, if version 6.0 of Comctl32.dll is available. You must call the method before handles are created on the thread. For more information, see [How to: Enable Visual Styles in a Hybrid Application](../../../../docs/framework/wpf/advanced/how-to-enable-visual-styles-in-a-hybrid-application.md). ## Licensed Controls Licensed [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls that display licensing information in a message box to the user might cause unexpected behavior for a hybrid application. Some licensed controls show a dialog box in response to handle creation. For example, a licensed control might inform the user that a license is required, or that the user has three remaining trial uses of the control. - The element derives from the class, and the child control’s handle is created inside the method. The class does not allow messages to be processed in the method, but displaying a dialog box causes messages to be sent. To enable this licensing scenario, call the method on the control before assigning it as the element's child. + The element derives from the class, and the child control’s handle is created inside the method. The class does not allow messages to be processed in the method, but displaying a dialog box causes messages to be sent. To enable this licensing scenario, call the method on the control before assigning it as the element's child. ## WPF Designer diff --git a/docs/framework/wpf/advanced/use-automatic-layout-overview.md b/docs/framework/wpf/advanced/use-automatic-layout-overview.md index a398179ff7abc..e6ffbf49a44c6 100644 --- a/docs/framework/wpf/advanced/use-automatic-layout-overview.md +++ b/docs/framework/wpf/advanced/use-automatic-layout-overview.md @@ -75,7 +75,7 @@ Grid ## Automatic Layout and Grids Using the IsSharedSizeScope Property - A element is useful in localizable applications to create controls that adjust to fit content. However, at times you want controls to maintain a particular size regardless of content. For example, if you have "OK", "Cancel" and "Browse" buttons you probably do not want the buttons sized to fit the content. In this case the attached property is useful for sharing the same sizing among multiple grid elements. The following example demonstrates how to share column and row sizing data between multiple elements. + A element is useful in localizable applications to create controls that adjust to fit content. However, at times you want controls to maintain a particular size regardless of content. For example, if you have "OK", "Cancel" and "Browse" buttons you probably do not want the buttons sized to fit the content. In this case the attached property is useful for sharing the same sizing among multiple grid elements. The following example demonstrates how to share column and row sizing data between multiple elements. [!code-xaml[gridIssharedsizescopeProp#2](../../../../samples/snippets/csharp/VS_Snippets_Wpf/gridIssharedsizescopeProp/CSharp/Window1.xaml#2)] diff --git a/docs/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md b/docs/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md index 2e15f3fe5658e..a0e8dacea4e24 100644 --- a/docs/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md +++ b/docs/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md @@ -95,7 +95,7 @@ This walkthrough shows you how to use [!INCLUDE[TLA2#tla_winclient] [!code-xaml[WpfLayoutHostingWfWithXaml#3](../../../../samples/snippets/csharp/VS_Snippets_Wpf/WpfLayoutHostingWfWithXaml/CSharp/Window1.xaml#3)] -2. Press F5 to build and run the application. The [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control appears in the . The hosted control is sized based on its content, and the element is sized to accommodate the hosted control. +2. Press F5 to build and run the application. The [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control appears in the . The hosted control is sized based on its content, and the element is sized to accommodate the hosted control. ## Sizing to Content The element ensures that the hosted control is sized to display its content properly. diff --git a/docs/framework/wpf/advanced/walkthrough-binding-to-data-in-hybrid-applications.md b/docs/framework/wpf/advanced/walkthrough-binding-to-data-in-hybrid-applications.md index 7eed9a2d22b08..3da1c404a4dbe 100644 --- a/docs/framework/wpf/advanced/walkthrough-binding-to-data-in-hybrid-applications.md +++ b/docs/framework/wpf/advanced/walkthrough-binding-to-data-in-hybrid-applications.md @@ -110,7 +110,7 @@ Binding a data source to a control is essential for providing users with access [!code-xaml[WPFWithWFAndDatabinding#6](../../../../samples/snippets/csharp/VS_Snippets_Wpf/WPFWithWFAndDatabinding/CSharp/WPFWithWFAndDatabinding/Window1.xaml#6)] ## Displaying Data by Using Interoperation - The orders corresponding to the selected customer are displayed in a control named `dataGridView1`. The `dataGridView1` control is bound to the data source in the code-behind file. A control is the parent of this [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control. + The orders corresponding to the selected customer are displayed in a control named `dataGridView1`. The `dataGridView1` control is bound to the data source in the code-behind file. A control is the parent of this [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control. #### To display data in the DataGridView control @@ -132,7 +132,7 @@ Binding a data source to a control is essential for providing users with access 4. When you are prompted to choose your database objects, select the `Customers` and `Orders` tables, and name the generated data set `NorthwindDataSet`. ## Binding to the Data Source - The component provides a uniform interface for the application's data source. Binding to the data source is implemented in the code-behind file. + The component provides a uniform interface for the application's data source. Binding to the data source is implemented in the code-behind file. #### To bind to the data source diff --git a/docs/framework/wpf/advanced/walkthrough-creating-your-first-touch-application.md b/docs/framework/wpf/advanced/walkthrough-creating-your-first-touch-application.md index 9027d5a550a18..f2e0457dd28d5 100644 --- a/docs/framework/wpf/advanced/walkthrough-creating-your-first-touch-application.md +++ b/docs/framework/wpf/advanced/walkthrough-creating-your-first-touch-application.md @@ -59,7 +59,7 @@ manager: "wpickett" The event occurs when the touch input changes position and can occur multiple times during a manipulation. The event can also occur after a finger is raised. For example, if the user drags a finger across a screen, the event occurs multiple times as the finger moves. When the user raises a finger from the screen, the event keeps occurring to simulate inertia. - The code applies the to the of the to move it as the user moves the touch input. It also checks whether the is outside the bounds of the when the event occurs during inertia. If so, the application calls the method to end the manipulation. + The code applies the to the of the to move it as the user moves the touch input. It also checks whether the is outside the bounds of the when the event occurs during inertia. If so, the application calls the method to end the manipulation. [!code-csharp[BasicManipulation#ManipulationDelta](../../../../samples/snippets/csharp/VS_Snippets_Wpf/basicmanipulation/csharp/mainwindow.xaml.cs#manipulationdelta)] [!code-vb[BasicManipulation#ManipulationDelta](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/basicmanipulation/visualbasic/mainwindow.xaml.vb#manipulationdelta)] @@ -87,6 +87,6 @@ manager: "wpickett" To cause inertia, quickly raise your fingers from the screen as you perform the previous manipulations. The will continue to move, resize, or rotate for a few seconds before it stops. ## See Also - - - + + + diff --git a/docs/framework/wpf/advanced/walkthrough-enabling-drag-and-drop-on-a-user-control.md b/docs/framework/wpf/advanced/walkthrough-enabling-drag-and-drop-on-a-user-control.md index 88bb2541227e7..c08742d4e19ed 100644 --- a/docs/framework/wpf/advanced/walkthrough-enabling-drag-and-drop-on-a-user-control.md +++ b/docs/framework/wpf/advanced/walkthrough-enabling-drag-and-drop-on-a-user-control.md @@ -119,7 +119,7 @@ This walkthrough demonstrates how to create a custom user control that can parti - Packages the Circle data into a . In this case, the Circle control packages three data items; a string representation of its Fill color, a double representation of its height, and a copy of itself. - - Calls the static method to initiate the drag-and-drop operation. You pass the following three parameters to the method: + - Calls the static method to initiate the drag-and-drop operation. You pass the following three parameters to the method: - `dragSource` – A reference to this control. diff --git a/docs/framework/wpf/advanced/walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md b/docs/framework/wpf/advanced/walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md index ba3a9c9ffacc0..31b02153bcb42 100644 --- a/docs/framework/wpf/advanced/walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md +++ b/docs/framework/wpf/advanced/walkthrough-hosting-a-3-d-wpf-composite-control-in-windows-forms.md @@ -49,7 +49,7 @@ This walkthrough demonstrates how you can create a [!INCLUDE[TLA2#tla_winclient] 3. Replace the generated code with the following code. - This code defines a that contains two child controls. The first child control is a control; the second is a control that displays a 3-D cone. + This code defines a that contains two child controls. The first child control is a control; the second is a control that displays a 3-D cone. [!code-xaml[HostingWpfUserControlInWf#1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/HostingWpfUserControlInWf/CSharp/HostingWpfUserControlInWf/ConeControl.xaml#1)] diff --git a/docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf-by-using-xaml.md b/docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf-by-using-xaml.md index ed32a17f97aeb..c1ededbd2e921 100644 --- a/docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf-by-using-xaml.md +++ b/docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf-by-using-xaml.md @@ -20,7 +20,7 @@ manager: "wpickett" # Walkthrough: Hosting a Windows Forms Control in WPF by Using XAML [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] provides many controls with a rich feature set. However, you may sometimes want to use [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls on your [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] pages. For example, you may have a substantial investment in existing [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls, or you may have a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control that provides unique functionality. - This walkthrough shows you how to host a Windows Forms control on a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] page by using [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)]. + This walkthrough shows you how to host a Windows Forms control on a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] page by using [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)]. For a complete code listing of the tasks shown in this walkthrough, see [Hosting a Windows Forms Control in WPF by Using XAML Sample](http://go.microsoft.com/fwlink/?LinkID=160000). diff --git a/docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md b/docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md index f10904761d9b7..106ecb7208fd7 100644 --- a/docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md +++ b/docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md @@ -20,7 +20,7 @@ manager: "wpickett" # Walkthrough: Hosting a Windows Forms Control in WPF [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] provides many controls with a rich feature set. However, you may sometimes want to use [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls on your [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] pages. For example, you may have a substantial investment in existing [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls, or you may have a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control that provides unique functionality. - This walkthrough shows you how to host a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control on a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] page by using code. + This walkthrough shows you how to host a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control on a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] page by using code. For a complete code listing of the tasks shown in this walkthrough, see [Hosting a Windows Forms Control in WPF Sample](http://go.microsoft.com/fwlink/?LinkID=160057). diff --git a/docs/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md b/docs/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md index c789dd1068a5b..a933b7c828eab 100644 --- a/docs/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md +++ b/docs/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md @@ -231,9 +231,9 @@ WPF composite control hosted in a Windows Forms application 2. Enlarge the form to accommodate the controls. -3. In the upper-right corner of the form, add a control to hold the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] composite control. +3. In the upper-right corner of the form, add a control to hold the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] composite control. -4. Add the following controls to the form. +4. Add the following controls to the form. |Name|Text| |----------|----------| @@ -245,7 +245,7 @@ WPF composite control hosted in a Windows Forms application |groupBox6|Font Weight| |groupBox7|Data from control| -5. Add the following controls to the controls. +5. Add the following controls to the controls. |GroupBox|Name|Text| |--------------|----------|----------| @@ -266,7 +266,7 @@ WPF composite control hosted in a Windows Forms application |groupBox6|radioWeightOriginal|Original| |groupBox6|radioWeightBold|Bold| -6. Add the following controls to the last . These controls display the data returned by the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] composite control. +6. Add the following controls to the last . These controls display the data returned by the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] composite control. |GroupBox|Name|Text| |--------------|----------|----------| @@ -291,7 +291,7 @@ WPF composite control hosted in a Windows Forms application 1. Create a new object. -2. Set the control's property to . +2. Set the control's property to . 3. Add the control to the control's collection. diff --git a/docs/framework/wpf/advanced/walkthrough-mapping-properties-using-the-elementhost-control.md b/docs/framework/wpf/advanced/walkthrough-mapping-properties-using-the-elementhost-control.md index c1e83c1f6e317..b1822282cf62c 100644 --- a/docs/framework/wpf/advanced/walkthrough-mapping-properties-using-the-elementhost-control.md +++ b/docs/framework/wpf/advanced/walkthrough-mapping-properties-using-the-elementhost-control.md @@ -141,8 +141,8 @@ This walkthrough shows you how to use the - + + [Windows Forms and WPF Property Mapping](../../../../docs/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md) [WPF Designer](http://msdn.microsoft.com/en-us/c6c65214-8411-4e16-b254-163ed4099c26) diff --git a/docs/framework/wpf/advanced/walkthrough-mapping-properties-using-the-windowsformshost-element.md b/docs/framework/wpf/advanced/walkthrough-mapping-properties-using-the-windowsformshost-element.md index 9378015026026..55fdcba734f7c 100644 --- a/docs/framework/wpf/advanced/walkthrough-mapping-properties-using-the-windowsformshost-element.md +++ b/docs/framework/wpf/advanced/walkthrough-mapping-properties-using-the-windowsformshost-element.md @@ -151,8 +151,8 @@ This walkthrough shows you how to use the mapping. When you click the check box, the layout reverses its left-right orientation. ## See Also - - + + [Windows Forms and WPF Property Mapping](../../../../docs/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md) [WPF Designer](http://msdn.microsoft.com/en-us/c6c65214-8411-4e16-b254-163ed4099c26) diff --git a/docs/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md b/docs/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md index 79c35aa562f9d..b7c3cdfff3245 100644 --- a/docs/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md +++ b/docs/framework/wpf/advanced/windows-forms-and-wpf-interoperability-input-architecture.md @@ -58,25 +58,25 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tl ### Acquiring Messages from the WPF Message Loop The class implements the message loop manager for [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)]. The class provides hooks to enable external clients to filter messages before [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] processes them. - The interoperation implementation handles the event, which enables [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls to process messages before [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] controls. + The interoperation implementation handles the event, which enables [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls to process messages before [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] controls. ### Surrogate Windows Forms Message Loop - By default, the class contains the primary message loop for [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] applications. During interoperation, the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] message loop does not process messages. Therefore, this logic must be reproduced. The handler for the event performs the following steps: + By default, the class contains the primary message loop for [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] applications. During interoperation, the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] message loop does not process messages. Therefore, this logic must be reproduced. The handler for the event performs the following steps: 1. Filters the message using the interface. -2. Calls the method. +2. Calls the method. 3. Translates and dispatches the message, if it is required. 4. Passes the message to the hosting control, if no other controls process the message. ### IKeyboardInputSink Implementation - The surrogate message loop handles keyboard management. Therefore, the method is the only member that requires an implementation in the class. + The surrogate message loop handles keyboard management. Therefore, the method is the only member that requires an implementation in the class. By default, the class returns `false` for its implementation. This prevents tabbing from a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control to a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control. - The implementation of the method performs the following steps: + The implementation of the method performs the following steps: 1. Finds the first or last [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control that is contained by the control and that can receive focus. The control choice depends on traversal information. @@ -87,7 +87,7 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tl ### WindowsFormsHost Registration When the window handle to a control is created, the control calls an internal static method that registers its presence for the message loop. - During registration, the control examines the message loop. If the message loop has not been started, the event handler is created. The message loop is considered to be running when the event handler is attached. + During registration, the control examines the message loop. If the message loop has not been started, the event handler is created. The message loop is considered to be running when the event handler is attached. When the window handle is destroyed, the control removes itself from registration. @@ -115,7 +115,7 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tl The [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] selection logic is mapped to the and methods to implement TAB and arrow key navigation. Overriding the method accomplishes this mapping. ### Command Keys and Dialog Box Keys - To give [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] the first opportunity to process command keys and dialog keys, [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] command preprocessing is connected to the method. Overriding the method connects the two technologies. + To give [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] the first opportunity to process command keys and dialog keys, [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] command preprocessing is connected to the method. Overriding the method connects the two technologies. With the method, the hosted elements can handle any key message, such as WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, or WM_SYSKEYUP, including command keys, such as TAB, ENTER, ESC, and arrow keys. If a key message is not handled, it is sent up the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] ancestor hierarchy for handling. @@ -124,7 +124,7 @@ Interoperation between the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tl Because the default implementation of the method returns `false`, WM_CHAR messages are processed using the following logic: -- The method is overridden to ensure that all WM_CHAR messages are forwarded to hosted elements. +- The method is overridden to ensure that all WM_CHAR messages are forwarded to hosted elements. - If the ALT key is pressed, the message is WM_SYSCHAR. [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] does not preprocess this message through the method. Therefore, the method is overridden to query the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] for a registered accelerator. If a registered accelerator is found, processes it. diff --git a/docs/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md b/docs/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md index 9261b1e7e94fd..976a876d35e3b 100644 --- a/docs/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md +++ b/docs/framework/wpf/advanced/windows-forms-and-wpf-property-mapping.md @@ -42,13 +42,13 @@ The [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md) |Windows Presentation Foundation hosting|Windows Forms|Interoperation behavior| |---------------------------------------------|-------------------|-----------------------------| -|

()|

()|The element sets the property of the hosted control and the property of the hosted control. Mapping is performed by using the following rules:

- If is a solid color, it is converted and used to set the property of the hosted control. The property is not set on the hosted control, because the hosted control can inherit the value of the property. **Note:** The hosted control does not support transparency. Any color assigned to must be fully opaque, with an alpha value of 0xFF.

- If is not a solid color, the control creates a bitmap from the property. The control assigns this bitmap to the property of the hosted control. This provides an effect which is similar to transparency. **Note:** You can override this behavior or you can remove the property mapping.| +|

()|

()|The element sets the property of the hosted control and the property of the hosted control. Mapping is performed by using the following rules:

- If is a solid color, it is converted and used to set the property of the hosted control. The property is not set on the hosted control, because the hosted control can inherit the value of the property. **Note:** The hosted control does not support transparency. Any color assigned to must be fully opaque, with an alpha value of 0xFF.

- If is not a solid color, the control creates a bitmap from the property. The control assigns this bitmap to the property of the hosted control. This provides an effect which is similar to transparency. **Note:** You can override this behavior or you can remove the property mapping.| |||If the default mapping has not been reassigned, control traverses its ancestor hierarchy until it finds an ancestor with its property set. This value is translated to the closest corresponding [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] cursor.

If the default mapping for the property has not been reassigned, the traversal stops on the first ancestor with set to `true`.| -|

()|

()| maps to .

maps to .

is not mapped.

maps to .| -|| on the hosted control's |The set of [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. For : is disabled. For or : is enabled.| -|| on the hosted control's |The set of [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. For , , , , , , , or : is enabled. For , , , , , or : is disabled.| -|







|

()|The set of [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. The hosted [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control resizes based on the font size.

Font size in [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] is expressed as one ninety-sixth of an inch, and in [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] as one seventy-second of an inch. The corresponding conversion is:

[!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] font size = [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] font size * 72.0 / 96.0.| -|

()|

()|The property mapping is performed by using the following rules:

- If is a , use for .
- If is a , use the color of the with the lowest offset value for .
- For any other type, leave unchanged. This means the default is used.| +|

()|

()| maps to .

maps to .

is not mapped.

maps to .| +|| on the hosted control's |The set of [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. For : is disabled. For or : is enabled.| +|| on the hosted control's |The set of [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. For , , , , , , , or : is enabled. For , , , , , or : is disabled.| +|







|

()|The set of [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] properties is translated into a corresponding . When one of these properties changes, a new is created. The hosted [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control resizes based on the font size.

Font size in [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] is expressed as one ninety-sixth of an inch, and in [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] as one seventy-second of an inch. The corresponding conversion is:

[!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] font size = [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] font size * 72.0 / 96.0.| +|

()|

()|The property mapping is performed by using the following rules:

- If is a , use for .
- If is a , use the color of the with the lowest offset value for .
- For any other type, leave unchanged. This means the default is used.| |||When is set, element sets the property on the hosted control.| |||All four values of the property on the hosted [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control are set to the same value.

- Values greater than are set to .
- Values less than are set to .| |||- maps to = `true`. The hosted [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control is visible. Explicitly setting the property on the hosted control to `false` is not recommended.
- maps to = `true` or `false`. The hosted [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control is not drawn, and its area is collapsed.
- : The hosted [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control occupies space in the layout, but is not visible. In this case, the property is set to `true`. Explicitly setting the property on the hosted control to `false` is not recommended.| @@ -127,17 +127,17 @@ The [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md) |Windows Forms hosting|Windows Presentation Foundation|Interoperation behavior| |---------------------------|-------------------------------------|-----------------------------| -|

()|

() on the hosted element|Setting this property forces a repaint with an . If the property is set to `false` (the default value), this is based on the appearance of the control, including its , , properties, and any attached paint handlers.

If the property is set to `true`, the is based on the appearance of the control's parent, including the parent's , , properties, and any attached paint handlers.| -|

()|

() on the hosted element|Setting this property causes the same behavior described for the mapping.| -||

() on the hosted element|Setting this property causes the same behavior described for the mapping.| -|

()|

()|The [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] standard cursor is translated to the corresponding [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] standard cursor. If the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] is not a standard cursor, the default is assigned.| +|

()|

() on the hosted element|Setting this property forces a repaint with an . If the property is set to `false` (the default value), this is based on the appearance of the control, including its , , properties, and any attached paint handlers.

If the property is set to `true`, the is based on the appearance of the control's parent, including the parent's , , properties, and any attached paint handlers.| +|

()|

() on the hosted element|Setting this property causes the same behavior described for the mapping.| +||

() on the hosted element|Setting this property causes the same behavior described for the mapping.| +|

()|

()|The [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] standard cursor is translated to the corresponding [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] standard cursor. If the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] is not a standard cursor, the default is assigned.| |||When is set, the control sets the property on the hosted element.| -|

()|







|The value is translated into a corresponding set of [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] font properties.| +|

()|







|The value is translated into a corresponding set of [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] font properties.| || on hosted element|If is `true`, is set to .

If is `false`, is set to .| || on hosted element|If is `true`, is set to .

If is `false`, is set to .| || on hosted element|Applies only when hosting a control.| || on hosted element|Applies only when hosting a control.| -|

()|

()| maps to .

maps to .| +|

()|

()| maps to .

maps to .| |||The control sets the property on the hosted element by using the following rules:

- = `true` maps to .
- = `false` maps to .| ## See Also diff --git a/docs/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md b/docs/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md index 3360dace05059..1f6f78cbb3f8a 100644 --- a/docs/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md +++ b/docs/framework/wpf/advanced/windows-forms-controls-and-equivalent-wpf-controls.md @@ -53,7 +53,7 @@ Many [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md |||| |||The control provides a read-only details view.| ||No equivalent control.|| -||| control styling can approximate the behavior and appearance of the class.| +||| control styling can approximate the behavior and appearance of the class.| |||| ||No equivalent control.|| || and two controls.|| @@ -88,7 +88,7 @@ Many [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md |||| |||| |||Scrolling is built into container controls.| -||, |The control can host HTML pages.

Starting in the [!INCLUDE[net_v35SP1_short](../../../../includes/net-v35sp1-short-md.md)], the control can host HTML pages and also backs the control.| +||, |The control can host HTML pages.

Starting in the [!INCLUDE[net_v35SP1_short](../../../../includes/net-v35sp1-short-md.md)], the control can host HTML pages and also backs the control.| ## See Also diff --git a/docs/framework/wpf/advanced/wpf-and-win32-interoperation.md b/docs/framework/wpf/advanced/wpf-and-win32-interoperation.md index 0dd18a9c856d0..75cb9bf36f778 100644 --- a/docs/framework/wpf/advanced/wpf-and-win32-interoperation.md +++ b/docs/framework/wpf/advanced/wpf-and-win32-interoperation.md @@ -128,7 +128,7 @@ This topic provides an overview of how to interoperate [!INCLUDE[TLA2#tla_wincli #### Notable Differences in Output Behavior -- , which is the base class, has quite a few properties that imply changes to the UI. These include properties such as , which changes the layout of elements within that element as a parent. However, most of these properties are not mapped to possible [!INCLUDE[TLA2#tla_win32](../../../../includes/tla2sharptla-win32-md.md)] equivalents, even if such equivalents might exist. Too many of these properties and their meanings are too rendering-technology specific for mappings to be practical. Therefore, setting properties such as on has no effect. +- , which is the base class, has quite a few properties that imply changes to the UI. These include properties such as , which changes the layout of elements within that element as a parent. However, most of these properties are not mapped to possible [!INCLUDE[TLA2#tla_win32](../../../../includes/tla2sharptla-win32-md.md)] equivalents, even if such equivalents might exist. Too many of these properties and their meanings are too rendering-technology specific for mappings to be practical. Therefore, setting properties such as on has no effect. - cannot be rotated, scaled, skewed, or otherwise affected by a Transform. diff --git a/docs/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md b/docs/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md index 6573acef001fc..0d8f4e0f187fb 100644 --- a/docs/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md +++ b/docs/framework/wpf/advanced/wpf-and-windows-forms-interoperation.md @@ -22,7 +22,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # WPF and Windows Forms Interoperation -[!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] and [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] present two different architectures for creating application interfaces. The namespace provides classes that enable common interoperation scenarios. The two key classes that implement interoperation capabilities are and . This topic describes which interoperation scenarios are supported and which scenarios are not supported. +[!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] and [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] present two different architectures for creating application interfaces. The namespace provides classes that enable common interoperation scenarios. The two key classes that implement interoperation capabilities are and . This topic describes which interoperation scenarios are supported and which scenarios are not supported. > [!NOTE] > Special consideration is given to the *hybrid control* scenario. A hybrid control has a control from one technology nested in a control from the other technology. This is also called a *nested interoperation*. A *multilevel hybrid control* has more than one level of hybrid control nesting. An example of a multilevel nested interoperation is a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control that contains a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control, which contains another [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control. Multilevel hybrid controls are not supported. @@ -77,7 +77,7 @@ manager: "wpickett" |Tabbing|Tab order for hosted [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls is the same as when those controls are hosted in a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)]-based application.

Tabbing from a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control to a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control with the TAB key and SHIFT+TAB keys works as usual.

[!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls that have a property value of `false` do not receive focus when the user tabs through controls.

- Each control has a value, which determines when that control will receive focus.
- [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls that are contained inside a container follow the order specified by the property. Tabbing from the last tab index puts focus on the next [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control, if one exists. If no other focusable [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control exists, tabbing returns to the first [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control in the tab order.
- values for controls inside the are relative to sibling [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls that are contained in the control.
- Tabbing honors control-specific behavior. For example, pressing the TAB key in a control that has a property value of `true` enters a tab in the text box instead of moving the focus.|Not applicable.| |Navigation with arrow keys|- Navigation with arrow keys in the control is the same as in an ordinary [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] container control: The UP ARROW and LEFT ARROW keys select the previous control, and the DOWN ARROW and RIGHT ARROW keys select the next control.
- The UP ARROW and LEFT ARROW keys from the first control that is contained in the control perform the same action as the SHIFT+TAB keyboard shortcut. If there is a focusable [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control, focus moves outside the control. This behavior differs from the standard behavior in that no wrapping to the last control occurs. If no other focusable [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control exists, focus returns to the last [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control in the tab order.
- The DOWN ARROW and RIGHT ARROW keys from the last control that is contained in the control perform the same action as the TAB key. If there is a focusable [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control, focus moves outside the control. This behavior differs from the standard behavior in that no wrapping to the first control occurs. If no other focusable [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control exists, focus returns to the first [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control in the tab order.|Not applicable.| |Accelerators|Accelerators work as usual, except where noted in the "Not supported" column.|Duplicate accelerators across technologies do not work like ordinary duplicate accelerators. When an accelerator is duplicated across technologies, with at least one on a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control and the other on a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control, the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control always receives the accelerator. Focus does not toggle between the controls when the duplicate accelerator is pressed.| -|Shortcut keys|Shortcut keys work as usual, except where noted in the "Not supported" column.|- [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] shortcut keys that are handled at the preprocessing stage always take precedence over [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] shortcut keys. For example, if you have a control with CTRL+S shortcut keys defined, and there is a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] command bound to CTRL+S, the control handler is always invoked first, regardless of focus.
- [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] shortcut keys that are handled by the event are processed last in [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)]. You can prevent this behavior by overriding the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control's method or handling the event. Return `true` from the method, or set the value of the property to `true` in your event handler.| +|Shortcut keys|Shortcut keys work as usual, except where noted in the "Not supported" column.|- [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] shortcut keys that are handled at the preprocessing stage always take precedence over [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] shortcut keys. For example, if you have a control with CTRL+S shortcut keys defined, and there is a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] command bound to CTRL+S, the control handler is always invoked first, regardless of focus.
- [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] shortcut keys that are handled by the event are processed last in [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)]. You can prevent this behavior by overriding the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control's method or handling the event. Return `true` from the method, or set the value of the property to `true` in your event handler.| |AcceptsReturn, AcceptsTab, and other control-specific behavior|Properties that change the default keyboard behavior work as usual, assuming that the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control overrides the method to return `true`.|[!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] controls that change default keyboard behavior by handling the event are processed last in the host [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] control. Because these controls are processed last, they can produce unexpected behavior.| |Enter and Leave Events|When focus is not going to the containing control, the Enter and Leave events are raised as usual when focus changes in a single control.|Enter and Leave events are not raised when the following focus changes occur:

- From inside to outside a control.
- From outside to inside a control.
- Outside a control.
- From a [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] control hosted in a control to an control hosted inside the same .| |Multithreading|All varieties of multithreading are supported.|Both the [!INCLUDE[TLA#tla_winforms](../../../../includes/tlasharptla-winforms-md.md)] and [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] technologies assume a single-threaded concurrency model. During debugging, calls to framework objects from other threads will raise an exception to enforce this requirement.| diff --git a/docs/framework/wpf/advanced/wpf-xaml-namescopes.md b/docs/framework/wpf/advanced/wpf-xaml-namescopes.md index c403734bc2899..340441f83007a 100644 --- a/docs/framework/wpf/advanced/wpf-xaml-namescopes.md +++ b/docs/framework/wpf/advanced/wpf-xaml-namescopes.md @@ -101,7 +101,7 @@ XAML namescopes are a concept that identifies objects that are defined in XAML. and implement through explicit interface definitions. The explicit implementations allow these XAML namescopes to behave conventionally when they are accessed through the interface, which is how XAML namescopes are communicated by [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] internal processes. But the explicit interface definitions are not part of the conventional API surface of and , because you seldom need to call the methods on and directly, and instead would use other API such as . - The following classes define their own XAML namescope, by using the helper class and connecting to its XAML namescope implementation through the attached property: + The following classes define their own XAML namescope, by using the helper class and connecting to its XAML namescope implementation through the attached property: - diff --git a/docs/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md b/docs/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md index b5b5b822e0590..321d6c107f677 100644 --- a/docs/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md +++ b/docs/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md @@ -125,13 +125,13 @@ End Namespace 1. Iterate through the , looking for an already-loaded assembly that matches all aspects of the name, starting from the most recently loaded assembly. -2. If the name is qualified, call on the qualified name. +2. If the name is qualified, call on the qualified name. 3. If the short name + public key token of a qualified name matches the assembly that the markup was loaded from, return that assembly. -4. Use the short name + public key token to call . +4. Use the short name + public key token to call . -5. If the name is unqualified, call . +5. If the name is unqualified, call . Loose XAML does not use Step 3; there is no loaded-from assembly. diff --git a/docs/framework/wpf/advanced/xaml-overview-wpf.md b/docs/framework/wpf/advanced/xaml-overview-wpf.md index d1bca95a7b66b..ea721ebf95f57 100644 --- a/docs/framework/wpf/advanced/xaml-overview-wpf.md +++ b/docs/framework/wpf/advanced/xaml-overview-wpf.md @@ -138,9 +138,9 @@ This topic describes the features of the XAML language and demonstrates how you Here, each is a child element of . This is a streamlined and intuitive markup that omits two tags for two different reasons. -- **Omitted StackPanel.Children property element:** derives from . defines as its XAML content property. +- **Omitted StackPanel.Children property element:** derives from . defines as its XAML content property. -- **Omitted UIElementCollection object element:** The property takes the type , which implements . The collection's element tag can be omitted, based on the XAML rules for processing collections such as . (In this case, actually cannot be instantiated because it does not expose a default constructor, and that is why the object element is shown commented out). +- **Omitted UIElementCollection object element:** The property takes the type , which implements . The collection's element tag can be omitted, based on the XAML rules for processing collections such as . (In this case, actually cannot be instantiated because it does not expose a default constructor, and that is why the object element is shown commented out). ```xaml @@ -219,11 +219,11 @@ This topic describes the features of the XAML language and demonstrates how you - [x:Class](../../../../docs/framework/xaml-services/x-class-directive.md): Specifies the [!INCLUDE[TLA2#tla_clr](../../../../includes/tla2sharptla-clr-md.md)] namespace and class name for the class that provides code-behind for a XAML page. You must have such a class to support code-behind per the WPF programming model, and therefore you almost always see `x:` mapped, even if there are no resources. -- [x:Name](../../../../docs/framework/xaml-services/x-name-directive.md): Specifies a run-time object name for the instance that exists in run-time code after an object element is processed. In general, you will frequently use a WPF-defined equivalent property for [x:Name](../../../../docs/framework/xaml-services/x-name-directive.md). Such properties map specifically to a CLR backing property and are thus more convenient for application programming, where you frequently use run time code to find the named elements from initialized XAML. The most common such property is . You might still use [x:Name](../../../../docs/framework/xaml-services/x-name-directive.md) when the equivalent WPF framework-level property is not supported in a particular type. This occurs in certain animation scenarios. +- [x:Name](../../../../docs/framework/xaml-services/x-name-directive.md): Specifies a run-time object name for the instance that exists in run-time code after an object element is processed. In general, you will frequently use a WPF-defined equivalent property for [x:Name](../../../../docs/framework/xaml-services/x-name-directive.md). Such properties map specifically to a CLR backing property and are thus more convenient for application programming, where you frequently use run time code to find the named elements from initialized XAML. The most common such property is . You might still use [x:Name](../../../../docs/framework/xaml-services/x-name-directive.md) when the equivalent WPF framework-level property is not supported in a particular type. This occurs in certain animation scenarios. - [x:Static](../../../../docs/framework/xaml-services/x-static-markup-extension.md): Enables a reference that returns a static value that is not otherwise a XAML-compatible property. -- [x:Type](../../../../docs/framework/xaml-services/x-type-markup-extension.md): Constructs a reference based on a type name. This is used to specify attributes that take , such as , although frequently the property has native string-to- conversion in such a way that the [x:Type](../../../../docs/framework/xaml-services/x-type-markup-extension.md) markup extension usage is optional. +- [x:Type](../../../../docs/framework/xaml-services/x-type-markup-extension.md): Constructs a reference based on a type name. This is used to specify attributes that take , such as , although frequently the property has native string-to- conversion in such a way that the [x:Type](../../../../docs/framework/xaml-services/x-type-markup-extension.md) markup extension usage is optional. There are additional programming constructs in the `x:` prefix/XAML namespace, which are not as common. For details, see [XAML Namespace (x:) Language Features](../../../../docs/framework/xaml-services/xaml-namespace-x-language-features.md). @@ -296,7 +296,7 @@ This topic describes the features of the XAML language and demonstrates how you The most common scenario for attached properties is to enable child elements to report a property value to their parent element. - The following example illustrates the attached property. The class defines the accessors for and therefore owns the attached property. The class also includes logic that iterates its child elements and specifically checks each element for a set value of . If a value is found, that value is used during layout to position the child elements. Use of the attached property and this positioning capability is in fact the motivating scenario for the class. + The following example illustrates the attached property. The class defines the accessors for and therefore owns the attached property. The class also includes logic that iterates its child elements and specifically checks each element for a set value of . If a value is found, that value is used during layout to position the child elements. Use of the attached property and this positioning capability is in fact the motivating scenario for the class. [!code-xaml[XAMLOvwSupport#DockAP](../../../../samples/snippets/csharp/VS_Snippets_Wpf/XAMLOvwSupport/CSharp/page8.xaml#dockap)] diff --git a/docs/framework/wpf/advanced/xaml-syntax-in-detail.md b/docs/framework/wpf/advanced/xaml-syntax-in-detail.md index 22a69185d6170..aac8e6fb60bcd 100644 --- a/docs/framework/wpf/advanced/xaml-syntax-in-detail.md +++ b/docs/framework/wpf/advanced/xaml-syntax-in-detail.md @@ -118,7 +118,7 @@ This topic defines the terms that are used to describe the elements of XAML synt For nonflag enumeration values, the native behavior is to process the string of an attribute value and resolve it to one of the enumeration values. You do not specify the enumeration in the format *Enumeration*.*Value*, as you do in code. Instead, you specify only *Value*, and *Enumeration* is inferred by the type of the property you are setting. If you specify an attribute in the *Enumeration*.*Value* form, it will not resolve correctly. - For flagwise enumerations, the behavior is based on the method. You can specify multiple values for a flagwise enumeration by separating each value with a comma. However, you cannot combine enumeration values that are not flagwise. For instance, you cannot use the comma syntax to attempt to create a that acts on multiple conditions of a nonflag enumeration: + For flagwise enumerations, the behavior is based on the method. You can specify multiple values for a flagwise enumeration by separating each value with a comma. However, you cannot combine enumeration values that are not flagwise. For instance, you cannot use the comma syntax to attempt to create a that acts on multiple conditions of a nonflag enumeration: ``` @@ -129,7 +129,7 @@ This topic defines the terms that are used to describe the elements of XAML synt ... ``` - Flagwise enumerations that support attributes that are settable in XAML are rare in WPF. However, one such enumeration is . You could, for instance, use the comma-delimited flagwise attribute syntax to modify the example provided in the Remarks for the class; `StyleSimulations = "BoldSimulation"` could become `StyleSimulations = "BoldSimulation,ItalicSimulation"`. is another property where more than one enumeration value can be specified. However, this property happens to be a special case, because the enumeration supports its own type converter. The type converter for modifiers uses a plus sign (+) as a delimiter rather than a comma (,). This conversion supports the more traditional syntax to represent key combinations in Microsoft Windows programming, such as "Ctrl+Alt". + Flagwise enumerations that support attributes that are settable in XAML are rare in WPF. However, one such enumeration is . You could, for instance, use the comma-delimited flagwise attribute syntax to modify the example provided in the Remarks for the class; `StyleSimulations = "BoldSimulation"` could become `StyleSimulations = "BoldSimulation,ItalicSimulation"`. is another property where more than one enumeration value can be specified. However, this property happens to be a special case, because the enumeration supports its own type converter. The type converter for modifiers uses a plus sign (+) as a delimiter rather than a comma (,). This conversion supports the more traditional syntax to represent key combinations in Microsoft Windows programming, such as "Ctrl+Alt". ### Properties and Event Member Name References When specifying an attribute, you can reference any property or event that exists as a member of the CLR type you instantiated for the containing object element. diff --git a/docs/framework/wpf/app-development/application-management-overview.md b/docs/framework/wpf/app-development/application-management-overview.md index 2e625ab6d2a62..e005b9fa25f73 100644 --- a/docs/framework/wpf/app-development/application-management-overview.md +++ b/docs/framework/wpf/app-development/application-management-overview.md @@ -42,16 +42,16 @@ All applications tend to share a common set of functionality that applies to app |Task|Approach| |----------|--------------| -|Get an object that represents the current application|Use the property.| +|Get an object that represents the current application|Use the property.| |Add a startup screen to an application|See [Add a Splash Screen to a WPF Application](../../../../docs/framework/wpf/app-development/how-to-add-a-splash-screen-to-a-wpf-application.md).| -|Start an application|Use the method.| -|Stop an application|Use the method of the object.| -|Get arguments from the command line|Handle the event and use the property. For an example, see the event.| -|Get and set the application exit code|Set the property in the event handler or call the method and pass in an integer.| +|Start an application|Use the method.| +|Stop an application|Use the method of the object.| +|Get arguments from the command line|Handle the event and use the property. For an example, see the event.| +|Get and set the application exit code|Set the property in the event handler or call the method and pass in an integer.| |Detect and respond to unhandled exceptions|Handle the event.| -|Get and set application-scoped resources|Use the property .| +|Get and set application-scoped resources|Use the property .| |Use an application-scope resource dictionary|See [Use an Application-Scope Resource Dictionary](../../../../docs/framework/wpf/app-development/how-to-use-an-application-scope-resource-dictionary.md).| -|Get and set application-scoped properties|Use the property .| +|Get and set application-scoped properties|Use the property .| |Get and save an application's state|See [Persist and Restore Application-Scope Properties Across Application Sessions](../../../../docs/framework/wpf/app-development/persist-and-restore-application-scope-properties.md).| |Manage non-code data files, including resource files, content files, and site-of-origin files.|See [WPF Application Resource, Content, and Data Files](../../../../docs/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md).| |Manage windows in standalone applications|See [WPF Windows Overview](../../../../docs/framework/wpf/app-development/wpf-windows-overview.md).| @@ -157,7 +157,7 @@ All applications tend to share a common set of functionality that applies to app [!code-vb[AppShowWindowHardSnippets#StartupEventCODEBEHIND](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/AppShowWindowHardSnippets/VisualBasic/Application.xaml.vb#startupeventcodebehind)] > [!NOTE] -> The first to be instantiated in a standalone application becomes the main application window by default. This object is referenced by the property. The value of the property can be changed programmatically if a different window than the first instantiated should be the main window. +> The first to be instantiated in a standalone application becomes the main application window by default. This object is referenced by the property. The value of the property can be changed programmatically if a different window than the first instantiated should be the main window. When an [!INCLUDE[TLA2#tla_xbap](../../../../includes/tla2sharptla-xbap-md.md)] first starts, it will most likely navigate to a . This is shown in the following code. @@ -208,7 +208,7 @@ All applications tend to share a common set of functionality that applies to app - A user switches from another application by selecting a in the application. - You can detect when an application becomes active by handling the event. + You can detect when an application becomes active by handling the event. Likewise, an application can become inactive in the following circumstances: @@ -216,7 +216,7 @@ All applications tend to share a common set of functionality that applies to app - When the application shuts down. - You can detect when an application becomes inactive by handling the event. + You can detect when an application becomes inactive by handling the event. The following code shows how to handle the and events to determine whether an application is active. @@ -225,10 +225,10 @@ All applications tend to share a common set of functionality that applies to app [!code-csharp[ApplicationActivationSnippets#DetectActivationStateCODEBEHIND](../../../../samples/snippets/csharp/VS_Snippets_Wpf/ApplicationActivationSnippets/CSharp/App.xaml.cs#detectactivationstatecodebehind)] [!code-vb[ApplicationActivationSnippets#DetectActivationStateCODEBEHIND](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationActivationSnippets/visualbasic/application.xaml.vb#detectactivationstatecodebehind)] - A can also be activated and deactivated. See and for more information. + A can also be activated and deactivated. See and for more information. > [!NOTE] -> Neither nor is raised for [!INCLUDE[TLA2#tla_xbap#plural](../../../../includes/tla2sharptla-xbapsharpplural-md.md)]. +> Neither nor is raised for [!INCLUDE[TLA2#tla_xbap#plural](../../../../includes/tla2sharptla-xbapsharpplural-md.md)]. ### Application Shutdown @@ -352,9 +352,9 @@ All applications tend to share a common set of functionality that applies to app [!code-csharp[ApplicationDispatcherUnhandledExceptionSnippets#HandleDispatcherUnhandledExceptionCODEBEHIND2](../../../../samples/snippets/csharp/VS_Snippets_Wpf/ApplicationDispatcherUnhandledExceptionSnippets/CSharp/App.xaml.cs#handledispatcherunhandledexceptioncodebehind2)] [!code-vb[ApplicationDispatcherUnhandledExceptionSnippets#HandleDispatcherUnhandledExceptionCODEBEHIND2](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationDispatcherUnhandledExceptionSnippets/visualbasic/application.xaml.vb#handledispatcherunhandledexceptioncodebehind2)] - The event handler is passed a parameter that contains contextual information regarding the unhandled exception, including the exception itself ( ). You can use this information to determine how to handle the exception. + The event handler is passed a parameter that contains contextual information regarding the unhandled exception, including the exception itself ( ). You can use this information to determine how to handle the exception. - When you handle , you should set the property to `true`; otherwise, [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] still considers the exception to be unhandled and reverts to the default behavior described earlier. If an unhandled exception is raised and either the event is not handled, or the event is handled and is set to `false`, the application shuts down immediately. Furthermore, no other events are raised. Consequently, you need to handle if your application has code that must run before the application shuts down. + When you handle , you should set the property to `true`; otherwise, [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] still considers the exception to be unhandled and reverts to the default behavior described earlier. If an unhandled exception is raised and either the event is not handled, or the event is handled and is set to `false`, the application shuts down immediately. Furthermore, no other events are raised. Consequently, you need to handle if your application has code that must run before the application shuts down. Although an application may shut down as a result of an unhandled exception, an application usually shuts down in response to a user request, as discussed in the next section. diff --git a/docs/framework/wpf/app-development/building-a-wpf-application-wpf.md b/docs/framework/wpf/app-development/building-a-wpf-application-wpf.md index e561b8ddb0713..123d6ca1fb4db 100644 --- a/docs/framework/wpf/app-development/building-a-wpf-application-wpf.md +++ b/docs/framework/wpf/app-development/building-a-wpf-application-wpf.md @@ -69,7 +69,7 @@ manager: "wpickett" In addition, a language-specific code file is generated for every [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] file. For example, for a Page1.xaml page in a [!INCLUDE[TLA2#tla_visualb](../../../../includes/tla2sharptla-visualb-md.md)] project, a Page1.g.vb is generated; for a Page1.xaml page in a [!INCLUDE[TLA2#tla_cshrp](../../../../includes/tla2sharptla-cshrp-md.md)] project, a Page1.g.cs is generated. The ".g" in the file name indicates the file is generated code that has a partial class declaration for the top-level element of the markup file (such as `Page` or `Window`). The class is declared with the `partial` modifier in [!INCLUDE[TLA2#tla_cshrp](../../../../includes/tla2sharptla-cshrp-md.md)] (`Extends` in [!INCLUDE[TLA2#tla_visualb](../../../../includes/tla2sharptla-visualb-md.md)]) to indicate there is another declaration for the class elsewhere, usually in the code-behind file Page1.xaml.cs. - The partial class extends from the appropriate base class (such as for a page) and implements the interface. The interface has methods to initialize a component and connect names and events on elements in its content. Consequently, the generated code file has a method implementation like the following: + The partial class extends from the appropriate base class (such as for a page) and implements the interface. The interface has methods to initialize a component and connect names and events on elements in its content. Consequently, the generated code file has a method implementation like the following: ```csharp public void InitializeComponent() { diff --git a/docs/framework/wpf/app-development/dialog-boxes-overview.md b/docs/framework/wpf/app-development/dialog-boxes-overview.md index 62b83c967137d..6a50d68dc183d 100644 --- a/docs/framework/wpf/app-development/dialog-boxes-overview.md +++ b/docs/framework/wpf/app-development/dialog-boxes-overview.md @@ -83,7 +83,7 @@ Standalone applications typically have a main window that both displays the main [!code-csharp[DialogBoxesOverviewSnippets#OpenFileDialogBoxCODEBEHIND](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#openfiledialogboxcodebehind)] [!code-vb[DialogBoxesOverviewSnippets#OpenFileDialogBoxCODEBEHIND](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#openfiledialogboxcodebehind)] - For more information on the open file dialog box, see . + For more information on the open file dialog box, see . > [!NOTE] > can be used to safely retrieve file names by applications running with partial trust (see [Security](../../../../docs/framework/wpf/security-wpf.md)). @@ -99,7 +99,7 @@ Standalone applications typically have a main window that both displays the main [!code-csharp[DialogBoxesOverviewSnippets#SaveFileDialogBoxCODEBEHIND](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#savefiledialogboxcodebehind)] [!code-vb[DialogBoxesOverviewSnippets#SaveFileDialogBoxCODEBEHIND](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#savefiledialogboxcodebehind)] - For more information on the save file dialog box, see . + For more information on the save file dialog box, see . ### Print Dialog Box @@ -112,7 +112,7 @@ Standalone applications typically have a main window that both displays the main [!code-csharp[DialogBoxesOverviewSnippets#PrintDialogBoxCODEBEHIND](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#printdialogboxcodebehind)] [!code-vb[DialogBoxesOverviewSnippets#PrintDialogBoxCODEBEHIND](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#printdialogboxcodebehind)] - For more information on the print dialog box, see . For detailed discussion of printing in [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)], see [Printing Overview](../../../../docs/framework/wpf/advanced/printing-overview.md). + For more information on the print dialog box, see . For detailed discussion of printing in [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)], see [Printing Overview](../../../../docs/framework/wpf/advanced/printing-overview.md). ## Custom Dialog Boxes @@ -178,7 +178,7 @@ Standalone applications typically have a main window that both displays the main [!code-csharp[DialogBoxSample#OpenMarginsDialogCODEBEHIND4](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MainWindow.xaml.cs#openmarginsdialogcodebehind4)] [!code-vb[DialogBoxSample#OpenMarginsDialogCODEBEHIND4](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MainWindow.xaml.vb#openmarginsdialogcodebehind4)] - Here, the code is passing default information (the current margins) to the dialog box. It is also setting the property with a reference to the window that is showing the dialog box. In general, you should always set the owner for a dialog box to provide window state-related behaviors that are common to all dialog boxes (see [WPF Windows Overview](../../../../docs/framework/wpf/app-development/wpf-windows-overview.md) for more information). + Here, the code is passing default information (the current margins) to the dialog box. It is also setting the property with a reference to the window that is showing the dialog box. In general, you should always set the owner for a dialog box to provide window state-related behaviors that are common to all dialog boxes (see [WPF Windows Overview](../../../../docs/framework/wpf/app-development/wpf-windows-overview.md) for more information). > [!NOTE] > You must provide an owner to support [!INCLUDE[TLA#tla_ui](../../../../includes/tlasharptla-ui-md.md)] automation for dialog boxes (see [UI Automation Overview](../../../../docs/framework/ui-automation/ui-automation-overview.md)). diff --git a/docs/framework/wpf/app-development/how-to-determine-if-a-page-is-browser-hosted.md b/docs/framework/wpf/app-development/how-to-determine-if-a-page-is-browser-hosted.md index e4f07c0dc8285..afae77f7c6461 100644 --- a/docs/framework/wpf/app-development/how-to-determine-if-a-page-is-browser-hosted.md +++ b/docs/framework/wpf/app-development/how-to-determine-if-a-page-is-browser-hosted.md @@ -24,7 +24,7 @@ This example demonstrates how to determine if a can be host agnostic and, consequently, can be loaded into several different types of hosts, including a , a , or a browser. This can happen when you have a library assembly that contains one or more pages, and which is referenced by multiple standalone and browsable ([!INCLUDE[TLA#tla_xbap](../../../../includes/tlasharptla-xbap-md.md)]) host applications. - The following example demonstrates how to use to determine if a is hosted in a browser. + The following example demonstrates how to use to determine if a is hosted in a browser. [!code-csharp[HOWTOBrowserInteropHelperSnippets#IsBrowserHostedCODE](../../../../samples/snippets/csharp/VS_Snippets_Wpf/HOWTOBrowserInteropHelperSnippets/CSharp/Page1.xaml.cs#isbrowserhostedcode)] [!code-vb[HOWTOBrowserInteropHelperSnippets#IsBrowserHostedCODE](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOBrowserInteropHelperSnippets/visualbasic/page1.xaml.vb#isbrowserhostedcode)] diff --git a/docs/framework/wpf/app-development/navigation-overview.md b/docs/framework/wpf/app-development/navigation-overview.md index 9dc6b8c5a3036..640f7c21240eb 100644 --- a/docs/framework/wpf/app-development/navigation-overview.md +++ b/docs/framework/wpf/app-development/navigation-overview.md @@ -207,7 +207,7 @@ manager: "wpickett" [!code-xaml[NavigationOverviewSnippets#PageThatNavigatesXAML3](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageThatNavigatesToFragment.xaml#pagethatnavigatesxaml3)] > [!NOTE] -> This section describes the default fragment navigation implementation in [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)]. [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] also allows you to implement your own fragment navigation scheme which, in part, requires handling the event. +> This section describes the default fragment navigation implementation in [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)]. [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] also allows you to implement your own fragment navigation scheme which, in part, requires handling the event. > [!IMPORTANT] > You can navigate to fragments in loose [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] pages (markup-only [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] files with `Page` as the root element) only if the pages can be browsed via [!INCLUDE[TLA2#tla_http](../../../../includes/tla2sharptla-http-md.md)]. @@ -218,7 +218,7 @@ manager: "wpickett" ### Navigation Service While allows a user to initiate navigation to a particular , the work of locating and downloading the page is performed by the class. Essentially, provides the ability to process a navigation request on behalf of client code, such as the . Additionally, implements higher-level support for tracking and influencing a navigation request. - When a is clicked, [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] calls to locate and download the at the specified pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)]. The downloaded is converted to a tree of objects whose root object is an instance of the downloaded . A reference to the root object is stored in the property. The pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] for the content that was navigated to is stored in the property, while the stores the pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] for the last page that was navigated to. + When a is clicked, [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] calls to locate and download the at the specified pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)]. The downloaded is converted to a tree of objects whose root object is an instance of the downloaded . A reference to the root object is stored in the property. The pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] for the content that was navigated to is stored in the property, while the stores the pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] for the last page that was navigated to. > [!NOTE] > It is possible for a [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] application to have more than one currently active . For more information, see [Navigation Hosts](#Navigation_Hosts) later in this topic. @@ -238,7 +238,7 @@ manager: "wpickett" In these situations, you need to write code to programmatically initiate navigation by calling the method of the object. That requires getting a reference to a . #### Getting a Reference to the NavigationService - For reasons that are covered in the [Navigation Hosts](#Navigation_Hosts) section, a [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] application can have more than one . This means that your code needs a way to find a , which is usually the that navigated to the current . You can get a reference to a by calling the `static` method. To get the that navigated to a particular , you pass a reference to the as the argument of the method. The following code shows how to get the for the current . + For reasons that are covered in the [Navigation Hosts](#Navigation_Hosts) section, a [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] application can have more than one . This means that your code needs a way to find a , which is usually the that navigated to the current . You can get a reference to a by calling the `static` method. To get the that navigated to a particular , you pass a reference to the as the argument of the method. The following code shows how to get the for the current . [!code-csharp[NavigationOverviewSnippets#GetNSCODEBEHIND1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/GetNSPage.xaml.cs#getnscodebehind1)] [!code-csharp[NavigationOverviewSnippets#GetNSCODEBEHIND2](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/GetNSPage.xaml.cs#getnscodebehind2)] @@ -268,10 +268,10 @@ manager: "wpickett" [!code-csharp[NavigationOverviewSnippets#NSNavigationPageCODEBEHIND](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSNavigationPage.xaml.cs#nsnavigationpagecodebehind)] [!code-vb[NavigationOverviewSnippets#NSNavigationPageCODEBEHIND](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/NSNavigationPage.xaml.vb#nsnavigationpagecodebehind)] - When the on this is clicked, navigation is initiated by instantiating the to navigate to using the non-default constructor and calling the method. accepts a reference to the object that the will navigate to, rather than a pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)]. + When the on this is clicked, navigation is initiated by instantiating the to navigate to using the non-default constructor and calling the method. accepts a reference to the object that the will navigate to, rather than a pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)]. #### Programmatic Navigation with a Pack URI - If you need to construct a pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] programmatically (when you can only determine the pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] at run time, for example), you can use the method. This is shown in the following example. + If you need to construct a pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] programmatically (when you can only determine the pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] at run time, for example), you can use the method. This is shown in the following example. [!code-xaml[NavigationOverviewSnippets#NSUriNavigationPageXAML](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSUriNavigationPage.xaml#nsurinavigationpagexaml)] @@ -279,7 +279,7 @@ manager: "wpickett" [!code-vb[NavigationOverviewSnippets#NSUriNavigationPageCODEBEHIND](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/NSUriNavigationPage.xaml.vb#nsurinavigationpagecodebehind)] #### Refreshing the Current Page - A is not downloaded if it has the same pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] as the pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] that is stored in the property. To force [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] to download the current page again, you can call the method, as shown in the following example. + A is not downloaded if it has the same pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] as the pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] that is stored in the property. To force [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] to download the current page again, you can call the method, as shown in the following example. [!code-xaml[NavigationOverviewSnippets#NSRefreshNavigationPageXAML1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSRefreshNavigationPage.xaml#nsrefreshnavigationpagexaml1)] @@ -316,23 +316,23 @@ manager: "wpickett" In general, a isn't concerned about these events. It is more likely that an application is concerned with them and, for that reason, these events are also raised by the class: -- +- -- +- -- +- -- +- -- +- -- +- -- +- Every time raises an event, the class raises the corresponding event. and offer the same events to detect navigation within their respective scopes. - In some cases, a might be interested in these events. For example, a might handle the event to determine whether or not to cancel navigation away from itself. This is shown in the following example. + In some cases, a might be interested in these events. For example, a might handle the event to determine whether or not to cancel navigation away from itself. This is shown in the following example. [!code-xaml[NavigationOverviewSnippets#CancelNavigationPageXAML](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/CancelNavigationPage.xaml#cancelnavigationpagexaml)] @@ -407,7 +407,7 @@ manager: "wpickett" ![Page lifetime](../../../../docs/framework/wpf/app-development/media/navigationoverviewfigure10.PNG "NavigationOverviewFigure10") - Although using the default journaling behavior can save on memory consumption, per-page rendering performance might be reduced; reinstantiating a can be time-intensive, particularly if it has a lot of content. If you need to retain a instance in the journal, you can draw on two techniques for doing so. First, you can programmatically navigate to a object by calling the method. + Although using the default journaling behavior can save on memory consumption, per-page rendering performance might be reduced; reinstantiating a can be time-intensive, particularly if it has a lot of content. If you need to retain a instance in the journal, you can draw on two techniques for doing so. First, you can programmatically navigate to a object by calling the method. Second, you can specify that [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] retain an instance of a in the journal by setting the property to `true` (the default is `false`). As shown in the following example, you can set declaratively in markup. @@ -481,11 +481,11 @@ manager: "wpickett" When a has controls other than those in the preceding list, or when state is stored in custom objects, you need to write code to cause the journal to remember state across navigations. - If you need to remember small pieces of state across navigations, you can use dependency properties (see ) that are configured with the metadata flag. + If you need to remember small pieces of state across navigations, you can use dependency properties (see ) that are configured with the metadata flag. If the state that your needs to remember across navigations comprises multiple pieces of data, you may find it less code intensive to encapsulate your state in a single class and implement the interface. - If you need to navigate through various states of a single , without navigating from the itself, you can use and . + If you need to navigate through various states of a single , without navigating from the itself, you can use and . ### Cookies @@ -635,7 +635,7 @@ manager: "wpickett" ![A journal in a Frame and in a NavigationWindow](../../../../docs/framework/wpf/app-development/media/naivgationoverviewfigure24.png "NaivgationOverviewFigure24") - This allows you to program navigation support directly against them. You may consider this if you need to provide a custom navigation [!INCLUDE[TLA2#tla_ui](../../../../includes/tla2sharptla-ui-md.md)] for a that is hosted in a . Furthermore, both types implement additional, navigation-related members, including `BackStack` ( , ) and `ForwardStack` ( , ), which allow you to enumerate the journal entries in the back stack and forward stack, respectively. + This allows you to program navigation support directly against them. You may consider this if you need to provide a custom navigation [!INCLUDE[TLA2#tla_ui](../../../../includes/tla2sharptla-ui-md.md)] for a that is hosted in a . Furthermore, both types implement additional, navigation-related members, including `BackStack` ( , ) and `ForwardStack` ( , ), which allow you to enumerate the journal entries in the back stack and forward stack, respectively. As mentioned earlier, more than one journal can exist within an application. The following figure provides an example of when this can happen. @@ -703,7 +703,7 @@ manager: "wpickett" [!code-csharp[NavigateToObjectSnippets#PersonClassCODE](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/Person.cs#personclasscode)] [!code-vb[NavigateToObjectSnippets#PersonClassCODE](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/NavigateToObjectSnippets/VisualBasic/Person.vb#personclasscode)] - To navigate to it, you call the method, as demonstrated by the following code. + To navigate to it, you call the method, as demonstrated by the following code. [!code-xaml[NavigateToObjectSnippets#PageThatNavsToObject1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/HomePage.xaml#pagethatnavstoobject1)] [!code-xaml[NavigateToObjectSnippets#PageThatNavsToObject2](../../../../samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/HomePage.xaml#pagethatnavstoobject2)] diff --git a/docs/framework/wpf/app-development/pack-uris-in-wpf.md b/docs/framework/wpf/app-development/pack-uris-in-wpf.md index fb3abb7173e6a..380823b11f18b 100644 --- a/docs/framework/wpf/app-development/pack-uris-in-wpf.md +++ b/docs/framework/wpf/app-development/pack-uris-in-wpf.md @@ -182,17 +182,17 @@ In [!INCLUDE[TLA#tla_wpf](../../../../includes/tlasharptla-wpf-md.m The types of [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] files that are commonly configured as [!INCLUDE[TLA2#tla_msbuild](../../../../includes/tla2sharptla-msbuild-md.md)]`Page` items have one of the following as their root element: -- +- -- +- -- +- -- +- -- +- -- +- ## Absolute vs. Relative Pack URIs @@ -265,17 +265,17 @@ In [!INCLUDE[TLA#tla_wpf](../../../../includes/tlasharptla-wpf-md.m ## Programming with Pack URIs Many [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] classes implement properties that can be set with pack [!INCLUDE[TLA2#tla_uri#plural](../../../../includes/tla2sharptla-urisharpplural-md.md)], including: -- +- -- +- -- +- -- +- -- +- -- +- These properties can be set from both markup and code. This section demonstrates the basic constructions for both and then shows examples of common scenarios. @@ -346,7 +346,7 @@ TextBox userProvidedUriTextBox = new TextBox(); Uri uri = new Uri(userProvidedUriTextBox.Text, UriKind.RelativeOrAbsolute); ``` - Table 3 illustrates the various relative pack [!INCLUDE[TLA2#tla_uri#plural](../../../../includes/tla2sharptla-urisharpplural-md.md)] that you can specify in code by using . + Table 3 illustrates the various relative pack [!INCLUDE[TLA2#tla_uri#plural](../../../../includes/tla2sharptla-urisharpplural-md.md)] that you can specify in code by using . Table 3: Absolute Pack URIs in Code @@ -362,7 +362,7 @@ Uri uri = new Uri(userProvidedUriTextBox.Text, UriKind.RelativeOrAbsolute); |Site of origin file|`Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);`| |Site of origin file in subfolder|`Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);`| - Table 4 illustrates the various relative pack [!INCLUDE[TLA2#tla_uri#plural](../../../../includes/tla2sharptla-urisharpplural-md.md)] that you can specify in code using . + Table 4 illustrates the various relative pack [!INCLUDE[TLA2#tla_uri#plural](../../../../includes/tla2sharptla-urisharpplural-md.md)] that you can specify in code using . Table 4: Relative Pack URIs in Code diff --git a/docs/framework/wpf/app-development/wpf-add-ins-overview.md b/docs/framework/wpf/app-development/wpf-add-ins-overview.md index 899ff968cc0a3..964f594c49fab 100644 --- a/docs/framework/wpf/app-development/wpf-add-ins-overview.md +++ b/docs/framework/wpf/app-development/wpf-add-ins-overview.md @@ -202,16 +202,16 @@ manager: "wpickett" ### Using the Pipeline and Add-In from the Application Base When the pipeline and add-in are configured for [!INCLUDE[TLA2#tla_clickonce](../../../../includes/tla2sharptla-clickonce-md.md)] deployment, they are downloaded to the same [!INCLUDE[TLA2#tla_clickonce](../../../../includes/tla2sharptla-clickonce-md.md)] cache folder as the [!INCLUDE[TLA2#tla_xbap](../../../../includes/tla2sharptla-xbap-md.md)]. To use the pipeline and add-in from the [!INCLUDE[TLA2#tla_xbap](../../../../includes/tla2sharptla-xbap-md.md)], the [!INCLUDE[TLA2#tla_xbap](../../../../includes/tla2sharptla-xbap-md.md)] code must get them from the application base. The various types and members of the [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] add-in model for using pipelines and add-ins provide special support for this scenario. Firstly, the path is identified by the enumeration value. You use this value with overloads of the pertinent add-in members for using pipelines that include the following: -- +- -- +- -- +- -- +- ### Accessing the Host's Site of Origin - To ensure that an add-in can reference files from the site of origin, the add-in must be loaded with security isolation that is equivalent to the host application. This security level is identified by the enumeration value, and passed to the method when an add-in is activated. + To ensure that an add-in can reference files from the site of origin, the add-in must be loaded with security isolation that is equivalent to the host application. This security level is identified by the enumeration value, and passed to the method when an add-in is activated. ## WPF Add-In Architecture diff --git a/docs/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md b/docs/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md index c729882f641c9..5168665c9b837 100644 --- a/docs/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md +++ b/docs/framework/wpf/app-development/wpf-application-resource-content-and-data-files.md @@ -97,7 +97,7 @@ manager: "wpickett" [!code-xaml[WPFAssemblyResourcesSnippets#LoadPageResourceFileFromXAML](../../../../samples/snippets/csharp/VS_Snippets_Wpf/WPFAssemblyResourcesSnippets/CSharp/ResourcesSample/ApplicationGetResourceStreamSnippetWindow.xaml#loadpageresourcefilefromxaml)] ### Application Code Files as Resource Files - A special set of [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] application code files can be referenced using pack [!INCLUDE[TLA2#tla_uri#plural](../../../../includes/tla2sharptla-urisharpplural-md.md)], including windows, pages, flow documents, and resource dictionaries. For example, you can set the property with a pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] that references the window or page that you would like to load when an application starts. + A special set of [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] application code files can be referenced using pack [!INCLUDE[TLA2#tla_uri#plural](../../../../includes/tla2sharptla-urisharpplural-md.md)], including windows, pages, flow documents, and resource dictionaries. For example, you can set the property with a pack [!INCLUDE[TLA2#tla_uri](../../../../includes/tla2sharptla-uri-md.md)] that references the window or page that you would like to load when an application starts. [!code-xaml[WPFAssemblyResourcesSnippets#SetApplicationStartupURI](../../../../samples/snippets/csharp/VS_Snippets_Wpf/WPFAssemblyResourcesSnippets/CSharp/ResourcesSample/App.xaml#setapplicationstartupuri)] diff --git a/docs/framework/wpf/app-development/wpf-windows-overview.md b/docs/framework/wpf/app-development/wpf-windows-overview.md index f3e8c4d19679a..9b7a7c1abd468 100644 --- a/docs/framework/wpf/app-development/wpf-windows-overview.md +++ b/docs/framework/wpf/app-development/wpf-windows-overview.md @@ -146,7 +146,7 @@ Users interact with [!INCLUDE[TLA#tla_wpf](../../../../includes/tla In this example, the `MarkupAndCodeBehindWindow` is instantiated when the application starts, which occurs when the event is raised. - When a window is instantiated, a reference to it is automatically added to a list of windows that is managed by the object (see ). Additionally, the first window to be instantiated is, by default, set by as the main application window (see ). + When a window is instantiated, a reference to it is automatically added to a list of windows that is managed by the object (see ). Additionally, the first window to be instantiated is, by default, set by as the main application window (see ). The window is finally opened by calling the method; the result is shown in the following figure. @@ -227,7 +227,7 @@ Users interact with [!INCLUDE[TLA#tla_wpf](../../../../includes/tla If a background task completes, a window may want to notify the user more urgently by calling method. If the user is interacting with another application activated when is called, the window's taskbar button flashes. If a user is interacting with the current application, calling will bring the window to the foreground. > [!NOTE] -> You can handle application-scope activation using the and events. +> You can handle application-scope activation using the and events. ### Closing a Window @@ -359,23 +359,23 @@ Users interact with [!INCLUDE[TLA#tla_wpf](../../../../includes/tla **For Height Properties:** -1. > +1. > -2. > +2. > -3. / > +3. / > -4. +4. **For Width Properties:** -1. > +1. > -2. > +2. > -3. / > +3. / > -4. +4. The order of precedence can also determine the size of a window when it is maximized, which is managed with the property. diff --git a/docs/framework/wpf/controls/button-styles-and-templates.md b/docs/framework/wpf/controls/button-styles-and-templates.md index 9b501b9c4c74e..94f9003b8f906 100644 --- a/docs/framework/wpf/controls/button-styles-and-templates.md +++ b/docs/framework/wpf/controls/button-styles-and-templates.md @@ -39,9 +39,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Button ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/calendar-styles-and-templates.md b/docs/framework/wpf/controls/calendar-styles-and-templates.md index f7d93074a92a4..c6fa9070b6745 100644 --- a/docs/framework/wpf/controls/calendar-styles-and-templates.md +++ b/docs/framework/wpf/controls/calendar-styles-and-templates.md @@ -38,9 +38,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## CalendarItem Parts The following table lists the named parts for the control. @@ -63,12 +63,12 @@ This topic describes the styles and templates for the property is `false`.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## CalendarDayButton Parts The control does not have any named parts. @@ -90,13 +90,13 @@ This topic describes the styles and templates for the .| -|Today|DayStates|The button represents .| +|RegularDay|DayStates|The button does not represent .| +|Today|DayStates|The button represents .| |NormalDay|BlackoutDayStates|The button represents a day that can be selected.| |BlackoutDay|BlackoutDayStates|The button represents a day that cannot be selected.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## CalendarButton Parts The control does not have any named parts. @@ -118,9 +118,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Calendar ControlTemplate Example The following example shows how to define a for the control and associated types. diff --git a/docs/framework/wpf/controls/checkbox-styles-and-templates.md b/docs/framework/wpf/controls/checkbox-styles-and-templates.md index 6fda6db278110..25160e4f08db9 100644 --- a/docs/framework/wpf/controls/checkbox-styles-and-templates.md +++ b/docs/framework/wpf/controls/checkbox-styles-and-templates.md @@ -42,9 +42,9 @@ This topic describes the styles and templates for the is `true`.| |Unchecked|CheckStates| is `false`.| |Indeterminate|CheckStates| is `true`, and is `null`.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## CheckBox ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/combobox-styles-and-templates.md b/docs/framework/wpf/controls/combobox-styles-and-templates.md index 48a5c7460c070..567186866615f 100644 --- a/docs/framework/wpf/controls/combobox-styles-and-templates.md +++ b/docs/framework/wpf/controls/combobox-styles-and-templates.md @@ -46,9 +46,9 @@ This topic describes the styles and templates for the has focus.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| |Editable|EditStates|The property is `true`.| |Uneditable|EditStates|The property is `false`.| @@ -68,9 +68,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ComboBox ControlTemplate Example The following example shows how to define a for the control and associated types. diff --git a/docs/framework/wpf/controls/contextmenu-styles-and-templates.md b/docs/framework/wpf/controls/contextmenu-styles-and-templates.md index ed5094d59ba78..fc57bad86d80f 100644 --- a/docs/framework/wpf/controls/contextmenu-styles-and-templates.md +++ b/docs/framework/wpf/controls/contextmenu-styles-and-templates.md @@ -35,9 +35,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ContextMenu ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/control-authoring-overview.md b/docs/framework/wpf/controls/control-authoring-overview.md index 19c7cd3f8a119..c7c0e81f85d09 100644 --- a/docs/framework/wpf/controls/control-authoring-overview.md +++ b/docs/framework/wpf/controls/control-authoring-overview.md @@ -105,7 +105,7 @@ The extensibility of the [!INCLUDE[TLA#tla_winclient](../../../../includes/tlash - Define a identifier named `ValueProperty` as a `public` `static` `readonly` field. -- Register the property name with the property system, by calling , to specify the following: +- Register the property name with the property system, by calling , to specify the following: - The name of the property. @@ -139,7 +139,7 @@ The extensibility of the [!INCLUDE[TLA#tla_winclient](../../../../includes/tlash - Define a identifier named `ValueChangedEvent` as a `public` `static` `readonly` field. -- Register the routed event by calling the method. The example specifies the following information when it calls : +- Register the routed event by calling the method. The example specifies the following information when it calls : - The name of the event is `ValueChanged`. diff --git a/docs/framework/wpf/controls/creating-a-control-that-has-a-customizable-appearance.md b/docs/framework/wpf/controls/creating-a-control-that-has-a-customizable-appearance.md index 5e03c48049840..005c6f3073332 100644 --- a/docs/framework/wpf/controls/creating-a-control-that-has-a-customizable-appearance.md +++ b/docs/framework/wpf/controls/creating-a-control-that-has-a-customizable-appearance.md @@ -84,7 +84,7 @@ A custom NumericUpDown control A visual behavior of the `NumericUpDown` control is that the value is in a red font if it is negative. If you change the of the in code when the `Value` is negative, the `NumericUpDown` will always show a red negative value. You specify the visual behavior of the control in the by adding objects to the . The following example shows the objects for the `Positive` and `Negative` states. `Positive` and `Negative` are mutually exclusive (the control is always in exactly one of the two), so the example puts the objects into a single . When the control goes into the `Negative` state, the of the turns red. When the control is in the `Positive` state, the returns to it original value. Defining objects in a is further discussed in [Customizing the Appearance of an Existing Control by Creating a ControlTemplate](../../../../docs/framework/wpf/controls/customizing-the-appearance-of-an-existing-control.md). > [!NOTE] -> Be sure to set the attached property on the root of the . +> Be sure to set the attached property on the root of the . [!code-xaml[VSMCustomControl#ValueStates](../../../../samples/snippets/csharp/VS_Snippets_Wpf/vsmcustomcontrol/csharp/window1.xaml#valuestates)] @@ -122,7 +122,7 @@ A custom NumericUpDown control By following the practices that are shown in the previous examples, you ensure that your control will continue to run when the is missing a . ### Use the VisualStateManager to Manage States - The keeps track of the states of a control and performs the logic necessary to transition between states. When you add objects to the , you add them to a and add the to the attached property so that the has access to them. + The keeps track of the states of a control and performs the logic necessary to transition between states. When you add objects to the , you add them to a and add the to the attached property so that the has access to them. The following example repeats the previous example that shows the objects that corresponds to the `Positive` and `Negative` states of the control. The in the `Negative` turns the of the red. When the `NumericUpDown` control is in the `Negative` state, the storyboard in the `Negative` state begins. Then the in the `Negative` state stops when the control returns to the `Positive` state. The `Positive` does not need to contain a because when the for the `Negative` stops, the returns to its original color. diff --git a/docs/framework/wpf/controls/customizing-the-appearance-of-an-existing-control.md b/docs/framework/wpf/controls/customizing-the-appearance-of-an-existing-control.md index 26e6190c77bdc..3253a3ea7292a 100644 --- a/docs/framework/wpf/controls/customizing-the-appearance-of-an-existing-control.md +++ b/docs/framework/wpf/controls/customizing-the-appearance-of-an-existing-control.md @@ -83,9 +83,9 @@ A CheckBox that uses a custom control template [!code-xaml[VSMButtonTemplate#TemplateBinding](../../../../samples/snippets/csharp/VS_Snippets_Wpf/vsmbuttontemplate/csharp/buttonstages.xaml#templatebinding)] - In this example, the has its property template bound to . Because is template bound, you can create multiple buttons that use the same and set the to different values on each button. If was not template bound to a property of an element in the , setting the of a button would have no impact on the button's appearance. + In this example, the has its property template bound to . Because is template bound, you can create multiple buttons that use the same and set the to different values on each button. If was not template bound to a property of an element in the , setting the of a button would have no impact on the button's appearance. - Note that the names of the two properties do not need to be identical. In the preceding example, the property of the is template bound to the property of the . This enables the content of the button to be positioned horizontally. does not have a property named `HorizontalContentAlignment`, but can be bound to . When you template bind a property, be sure that the target and source properties are the same type. + Note that the names of the two properties do not need to be identical. In the preceding example, the property of the is template bound to the property of the . This enables the content of the button to be positioned horizontally. does not have a property named `HorizontalContentAlignment`, but can be bound to . When you template bind a property, be sure that the target and source properties are the same type. The class defines several properties that must be used by the control template to have an effect on the control when they are set. How the uses the property depends on the property. The must use the property in one of the following ways: @@ -126,7 +126,7 @@ Two buttons with different background colors ## Changing the Appearance of a Control Depending on Its State The difference between a button with its default appearance and the button in the preceding example is that the default button subtly changes when it is in different states. For example, the default button's appearance changes when the button is pressed, or when the mouse pointer is over the button. Although the does not change the functionality of a control, it does change the control's visual behavior. A visual behavior describes the control appearance when it is in a certain state. To understand the difference between the functionality and visual behavior of a control, consider the button example. The button's functionality is to raise the event when it is clicked, but the button's visual behavior is to change its appearance when it is pointed to or pressed. - You use objects to specify the appearance of a control when it is in a certain state. A contains a that changes the appearance of the elements that are in the . You do not have to write any code to make this occur because the control's logic changes state by using the . When the control enters the state that is specified by the property, the begins. When the control exits the state, the stops. + You use objects to specify the appearance of a control when it is in a certain state. A contains a that changes the appearance of the elements that are in the . You do not have to write any code to make this occur because the control's logic changes state by using the . When the control enters the state that is specified by the property, the begins. When the control exits the state, the stops. The following example shows the that changes the appearance of a when the mouse pointer is over it. The changes the button's border color by changing the color of the `BorderBrush`. If you refer to the example at the beginning of this topic, you will recall that `BorderBrush` is the name of the that is assigned to the of the . @@ -145,10 +145,10 @@ Two buttons with different background colors The defines two state groups: the `CommonStates` group contains the `Normal`, `MouseOver`, `Pressed`, and `Disabled` states. The `FocusStates` group contains the `Focused` and `Unfocused` states. States in the same state group are mutually exclusive. The control is always in exactly one state per group. For example, a can have focus even when the mouse pointer is not over it, so a in the `Focused` state can be in the `MouseOver`, `Pressed`, or `Normal` state. - You add objects to objects. You add objects to the attached property. The following example defines the objects for the `Normal`, `MouseOver`, and `Pressed` states, which are all in the `CommonStates` group. The of each matches the name in the preceding table. The `Disabled` state and the states in the `FocusStates` group are omitted to keep the example short, but they are included in the entire example at the end of this topic. + You add objects to objects. You add objects to the attached property. The following example defines the objects for the `Normal`, `MouseOver`, and `Pressed` states, which are all in the `CommonStates` group. The of each matches the name in the preceding table. The `Disabled` state and the states in the `FocusStates` group are omitted to keep the example short, but they are included in the entire example at the end of this topic. > [!NOTE] -> Be sure to set the attached property on the root of the . +> Be sure to set the attached property on the root of the . [!code-xaml[VSMButtonTemplate#VisualStates](../../../../samples/snippets/csharp/VS_Snippets_Wpf/vsmbuttontemplate/csharp/buttonstages.xaml#visualstates)] diff --git a/docs/framework/wpf/controls/datepicker-styles-and-templates.md b/docs/framework/wpf/controls/datepicker-styles-and-templates.md index 302ea333dfb72..89375665e0304 100644 --- a/docs/framework/wpf/controls/datepicker-styles-and-templates.md +++ b/docs/framework/wpf/controls/datepicker-styles-and-templates.md @@ -42,9 +42,9 @@ This topic describes the styles and templates for the is disabled.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## DatePickerTextBox Parts The following table lists the named parts for the control. @@ -67,9 +67,9 @@ This topic describes the styles and templates for the is in the state when the user has not entered text or selected a date.| |Unwatermarked|WatermarkStates|The user has entered text into the or selected a date in the .| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## DatePicker ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/datepicker.md b/docs/framework/wpf/controls/datepicker.md index 05609879abf2c..ef52dceac80d6 100644 --- a/docs/framework/wpf/controls/datepicker.md +++ b/docs/framework/wpf/controls/datepicker.md @@ -26,7 +26,7 @@ The control allows the user to select ![DatePicker control](../../../../docs/framework/wpf/controls/media/ndp-datepicker.png "NDP_DatePicker") DatePicker Control - Many of a control's properties are for managing its built-in , and function identically to the equivalent property in . In particular, the , , , , , , and properties function identically to their counterparts. For more information, see . + Many of a control's properties are for managing its built-in , and function identically to the equivalent property in . In particular, the , , , , , , and properties function identically to their counterparts. For more information, see . Users can type a date directly into a text field, which sets the property. If the cannot convert the entered string to a valid date, the event will be raised. By default, this causes an exception, but an event handler for can set the property to `false` and prevent an exception from being raised. diff --git a/docs/framework/wpf/controls/default-keyboard-and-mouse-behavior-in-the-datagrid-control.md b/docs/framework/wpf/controls/default-keyboard-and-mouse-behavior-in-the-datagrid-control.md index ce836bdf81ee7..3ccd0f28e9e03 100644 --- a/docs/framework/wpf/controls/default-keyboard-and-mouse-behavior-in-the-datagrid-control.md +++ b/docs/framework/wpf/controls/default-keyboard-and-mouse-behavior-in-the-datagrid-control.md @@ -23,7 +23,7 @@ manager: "wpickett" # Default Keyboard and Mouse Behavior in the DataGrid Control This topic describes how users can interact with the control by using the keyboard and mouse. - Typical interactions with the include navigation, selection, and editing. Selection behavior is affected by the and properties. The default values that cause the behavior described in this topic are and . Changing these values might cause behavior that is different from that described. When a cell is in edit mode, the editing control might override the standard keyboard behavior of the . + Typical interactions with the include navigation, selection, and editing. Selection behavior is affected by the and properties. The default values that cause the behavior described in this topic are and . Changing these values might cause behavior that is different from that described. When a cell is in edit mode, the editing control might override the standard keyboard behavior of the . ## Default Keyboard Behavior The following table lists the default keyboard behavior for the . @@ -48,7 +48,7 @@ This topic describes how users can interact with the property is `false` and the property is `false` for the current column, puts the current cell into cell edit mode.| +|F2|If the property is `false` and the property is `false` for the current column, puts the current cell into cell edit mode.| |ENTER|Commits any changes to the current cell and row and moves the focus to the cell directly below the current cell. If the focus is in the last row, commits any changes without moving the focus.| |ESC|If the control is in edit mode, cancels the edit and reverts any changes that were made in the control. If the underlying data source implements , pressing ESC a second time cancels edit mode for the entire row.| |BACKSPACE|Deletes the character before the cursor when editing a cell.| @@ -84,10 +84,10 @@ This topic describes how users can interact with the property is `true` and the property is `true` for the current column, moves the column so that it can be dropped into a new position.| -|Drag a column header separator|If the property is `true` and the property is `true` for the current column, resizes the column.| -|Double-click a column header separator|If the property is `true` and the property is `true` for the current column, auto-sizes the column using the sizing mode.| -|Click a column header cell|If the property is `true` and the property is `true` for the current column, sorts the column.

Clicking the header of a column that is already sorted will reverse the sort direction of that column.

Pressing the SHIFT key while clicking multiple column headers will sort by multiple columns in the order clicked.| +|Drag a column header cell|If the property is `true` and the property is `true` for the current column, moves the column so that it can be dropped into a new position.| +|Drag a column header separator|If the property is `true` and the property is `true` for the current column, resizes the column.| +|Double-click a column header separator|If the property is `true` and the property is `true` for the current column, auto-sizes the column using the sizing mode.| +|Click a column header cell|If the property is `true` and the property is `true` for the current column, sorts the column.

Clicking the header of a column that is already sorted will reverse the sort direction of that column.

Pressing the SHIFT key while clicking multiple column headers will sort by multiple columns in the order clicked.| |CTRL+click a row|If is set to , modifies a non-contiguous multi-row selection.

If the row is already selected, deselects the row.| |SHIFT+click a row|If is set to , modifies a contiguous multi-row selection.| |Click a row group header|Expands or collapses the group.| diff --git a/docs/framework/wpf/controls/documentviewer-styles-and-templates.md b/docs/framework/wpf/controls/documentviewer-styles-and-templates.md index bc134dcd5ac7b..41d8c034b639f 100644 --- a/docs/framework/wpf/controls/documentviewer-styles-and-templates.md +++ b/docs/framework/wpf/controls/documentviewer-styles-and-templates.md @@ -38,9 +38,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## DocumentViewer ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/expander-styles-and-templates.md b/docs/framework/wpf/controls/expander-styles-and-templates.md index ed0b8ce69e2db..2865f9e251aff 100644 --- a/docs/framework/wpf/controls/expander-styles-and-templates.md +++ b/docs/framework/wpf/controls/expander-styles-and-templates.md @@ -44,9 +44,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Expander ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/frame-styles-and-templates.md b/docs/framework/wpf/controls/frame-styles-and-templates.md index 6bf1400630060..8ace6e4d7d3de 100644 --- a/docs/framework/wpf/controls/frame-styles-and-templates.md +++ b/docs/framework/wpf/controls/frame-styles-and-templates.md @@ -37,9 +37,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Frame ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/groupbox-styles-and-templates.md b/docs/framework/wpf/controls/groupbox-styles-and-templates.md index 64ead38a98b53..7a7c886e02a7e 100644 --- a/docs/framework/wpf/controls/groupbox-styles-and-templates.md +++ b/docs/framework/wpf/controls/groupbox-styles-and-templates.md @@ -35,9 +35,9 @@ manager: "wpickett" |VisualState Name|VisualStateGroup Name|Description| |-|-|-| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## GroupBox ControlTemplate Example diff --git a/docs/framework/wpf/controls/guidelines-for-designing-stylable-controls.md b/docs/framework/wpf/controls/guidelines-for-designing-stylable-controls.md index e806641467f8b..d7fa5bb920dbd 100644 --- a/docs/framework/wpf/controls/guidelines-for-designing-stylable-controls.md +++ b/docs/framework/wpf/controls/guidelines-for-designing-stylable-controls.md @@ -87,7 +87,7 @@ This document summarizes a set of best practices to consider when designing a co - **Use best practices for expressing control state and behavior in a style.** The following is an ordered list of best practices for expressing control state changes and behavior in a style. You should use the first item on the list that enables your scenario. - 1. Property binding. Example: binding between and . + 1. Property binding. Example: binding between and . 2. Triggered property changes or property animations. Example: the hover state of a . diff --git a/docs/framework/wpf/controls/how-to-bind-a-treeview-to-data-that-has-an-indeterminable-depth.md b/docs/framework/wpf/controls/how-to-bind-a-treeview-to-data-that-has-an-indeterminable-depth.md index a0dac52364991..8878b3fc95763 100644 --- a/docs/framework/wpf/controls/how-to-bind-a-treeview-to-data-that-has-an-indeterminable-depth.md +++ b/docs/framework/wpf/controls/how-to-bind-a-treeview-to-data-that-has-an-indeterminable-depth.md @@ -22,9 +22,9 @@ There might be times when you want to bind a property and if the generates an for each child item, then the child uses the same as the parent. For example, if you set the property on a data-bound , each that is generated uses the that was assigned to the property of the . + When you set the property and if the generates an for each child item, then the child uses the same as the parent. For example, if you set the property on a data-bound , each that is generated uses the that was assigned to the property of the . - The enables you to specify the for a , or any , on the data template. When you set the property, that value is used when the is applied. By using a , you can recursively set the for each in the . + The enables you to specify the for a , or any , on the data template. When you set the property, that value is used when the is applied. By using a , you can recursively set the for each in the . ## Example The following example demonstrates how to bind a to hierarchical data and use a to specify the for each . The binds to XML data that represents the employees in a company. Each `Employee` element can contain other `Employee` elements to indicate who reports to whom. Because the data is recursive, the can be applied to each level. diff --git a/docs/framework/wpf/controls/how-to-create-a-complex-grid.md b/docs/framework/wpf/controls/how-to-create-a-complex-grid.md index 33defd66b3b89..c5e3faa5d3467 100644 --- a/docs/framework/wpf/controls/how-to-create-a-complex-grid.md +++ b/docs/framework/wpf/controls/how-to-create-a-complex-grid.md @@ -23,7 +23,7 @@ manager: "wpickett" This example shows how to use a to create layout that looks like a monthly calendar. ## Example - The following example defines eight rows and eight columns by using the and classes. It uses the and attached properties, together with elements, which fill the backgrounds of various columns and rows. This design is possible because more than one element can exist in each cell in a , a principle difference between and . + The following example defines eight rows and eight columns by using the and classes. It uses the and attached properties, together with elements, which fill the backgrounds of various columns and rows. This design is possible because more than one element can exist in each cell in a , a principle difference between and . The example uses vertical gradients to the columns and rows in order to improve the visual presentation and readability of the calendar. Styled elements represent the dates and days of the week. elements are absolutely positioned within their cells by using the property and alignment properties that are defined within the style for the application. diff --git a/docs/framework/wpf/controls/how-to-group-sort-and-filter-data-in-the-datagrid-control.md b/docs/framework/wpf/controls/how-to-group-sort-and-filter-data-in-the-datagrid-control.md index a667cc0617cbc..f7a4a278d3f10 100644 --- a/docs/framework/wpf/controls/how-to-group-sort-and-filter-data-in-the-datagrid-control.md +++ b/docs/framework/wpf/controls/how-to-group-sort-and-filter-data-in-the-datagrid-control.md @@ -70,7 +70,7 @@ Grouped Data in a DataGrid 2. In code, pass the name of the property to group by to the constructor. -2. Add the to the collection. +2. Add the to the collection. 3. Add additional instances of to the collection to add more levels of grouping. @@ -107,7 +107,7 @@ Grouped Data in a DataGrid 2. In code, pass the name of the property to sort by and the to the constructor. -2. Add the to the collection. +2. Add the to the collection. 3. Add additional instances of to the collection to sort by additional properties. @@ -117,11 +117,11 @@ Grouped Data in a DataGrid [!code-vb[DataGrid_GroupSortFilter#211](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/DataGrid_GroupSortFilter/VB/MainWindow.xaml.vb#211)] ## Filtering items in a DataGrid - To filter items in a using a , you provide the filtering logic in the handler for the event. + To filter items in a using a , you provide the filtering logic in the handler for the event. #### To filter items in a DataGrid -1. Add a handler for the event. +1. Add a handler for the event. 2. In the event handler, define the filtering logic. @@ -132,7 +132,7 @@ Grouped Data in a DataGrid [!code-csharp[DataGrid_GroupSortFilter#113](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DataGrid_GroupSortFilter/CS/MainWindow.xaml.cs#113)] [!code-vb[DataGrid_GroupSortFilter#113](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/DataGrid_GroupSortFilter/VB/MainWindow.xaml.vb#113)] - Alternatively, you can filter items in a by creating a method that provides the filtering logic and setting the property to apply the filter. To see an example of this method, see [Filter Data in a View](../../../../docs/framework/wpf/data/how-to-filter-data-in-a-view.md). + Alternatively, you can filter items in a by creating a method that provides the filtering logic and setting the property to apply the filter. To see an example of this method, see [Filter Data in a View](../../../../docs/framework/wpf/data/how-to-filter-data-in-a-view.md). ## Example The following example demonstrates grouping, sorting, and filtering `Task` data in a and displaying the grouped, sorted, and filtered `Task` data in a . The is used as the for the . Grouping, sorting, and filtering are performed on the and are displayed in the UI. diff --git a/docs/framework/wpf/controls/how-to-implement-validation-with-the-datagrid-control.md b/docs/framework/wpf/controls/how-to-implement-validation-with-the-datagrid-control.md index 4bf956c806a8c..9bc08b1f93dd4 100644 --- a/docs/framework/wpf/controls/how-to-implement-validation-with-the-datagrid-control.md +++ b/docs/framework/wpf/controls/how-to-implement-validation-with-the-datagrid-control.md @@ -35,7 +35,7 @@ The control enables you to perform valid ### To customize cell validation feedback -- Set the column's property to a style appropriate for the column's editing control. Because the editing controls are created at run time, you cannot use the attached property like you would with simple controls. +- Set the column's property to a style appropriate for the column's editing control. Because the editing controls are created at run time, you cannot use the attached property like you would with simple controls. The following example updates the previous example by adding an error style shared by the three columns with validation rules. When a user enters an invalid value, the style changes the cell background color and adds a ToolTip. Note the use of a trigger to determine whether there is a validation error. This is required because there is currently no dedicated error template for cells. @@ -52,7 +52,7 @@ The control enables you to perform valid [!code-csharp[DataGrid_Validation#CourseValidationRule](../../../../samples/snippets/csharp/VS_Snippets_Wpf/datagrid_validation/cs/mainwindow.xaml.cs#coursevalidationrule)] [!code-vb[DataGrid_Validation#CourseValidationRule](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/datagrid_validation/vb/mainwindow.xaml.vb#coursevalidationrule)] -2. Add the validation rule to the collection. The property provides direct access to the property of a instance that groups all the bindings used by the control. +2. Add the validation rule to the collection. The property provides direct access to the property of a instance that groups all the bindings used by the control. The following example sets the property in XAML. The property is set to so that the validation occurs only after the bound data object is updated. @@ -62,7 +62,7 @@ The control enables you to perform valid ### To customize row validation feedback -- Set the property. This property enables you to customize row validation feedback for individual controls. You can also affect multiple controls by using an implicit row style to set the property. +- Set the property. This property enables you to customize row validation feedback for individual controls. You can also affect multiple controls by using an implicit row style to set the property. The following example replaces the default row validation feedback with a more visible indicator. When a user enters an invalid value, a red circle with a white exclamation mark appears in the row header. This occurs for both row and cell validation errors. The associated error message is displayed in a ToolTip. diff --git a/docs/framework/wpf/controls/how-to-improve-the-performance-of-a-treeview.md b/docs/framework/wpf/controls/how-to-improve-the-performance-of-a-treeview.md index 5c61a967c04a6..b5f2dfada5804 100644 --- a/docs/framework/wpf/controls/how-to-improve-the-performance-of-a-treeview.md +++ b/docs/framework/wpf/controls/how-to-improve-the-performance-of-a-treeview.md @@ -18,12 +18,12 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Improve the Performance of a TreeView -If a contains many items, the amount of time it takes to load may cause a significant delay in the user interface. You can improve the load time by setting the `VirtualizingStackPanel.IsVirtualizing` attached property to `true`. The UI might also be slow to react when a user scrolls the by using the mouse wheel or dragging the thumb of a scrollbar. You can improve the performance of the when the user scrolls by setting the `VirtualizingStackPanel.VirtualizationMode` attached property to . +If a contains many items, the amount of time it takes to load may cause a significant delay in the user interface. You can improve the load time by setting the `VirtualizingStackPanel.IsVirtualizing` attached property to `true`. The UI might also be slow to react when a user scrolls the by using the mouse wheel or dragging the thumb of a scrollbar. You can improve the performance of the when the user scrolls by setting the `VirtualizingStackPanel.VirtualizationMode` attached property to . ## Example ## Description -The following example creates a that sets the `VirtualizingStackPanel.IsVirtualizing` attached property to true and the `VirtualizingStackPanel.VirtualizationMode` attached property to to optimize its performance. +The following example creates a that sets the `VirtualizingStackPanel.IsVirtualizing` attached property to true and the `VirtualizingStackPanel.VirtualizationMode` attached property to to optimize its performance. ## Code [!code-xaml[RecycleItemContainerShippets#VirtualizingTreeView](../../../../samples/snippets/csharp/VS_Snippets_Wpf/RecycleItemContainerShippets/CSharp/Window1.xaml#virtualizingtreeview)] diff --git a/docs/framework/wpf/controls/how-to-improve-the-scrolling-performance-of-a-listbox.md b/docs/framework/wpf/controls/how-to-improve-the-scrolling-performance-of-a-listbox.md index 5708d6bcca6a7..8a8cdd82aee24 100644 --- a/docs/framework/wpf/controls/how-to-improve-the-scrolling-performance-of-a-listbox.md +++ b/docs/framework/wpf/controls/how-to-improve-the-scrolling-performance-of-a-listbox.md @@ -19,12 +19,12 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Improve the Scrolling Performance of a ListBox -If a contains many items, the user interface response can be slow when a user scrolls the by using the mouse wheel or dragging the thumb of a scrollbar. You can improve the performance of the when the user scrolls by setting the `VirtualizingStackPanel.VirtualizationMode` attached property to . +If a contains many items, the user interface response can be slow when a user scrolls the by using the mouse wheel or dragging the thumb of a scrollbar. You can improve the performance of the when the user scrolls by setting the `VirtualizingStackPanel.VirtualizationMode` attached property to . ## Example ## Description -The following example creates a and sets the `VirtualizingStackPanel.VirtualizationMode` attached property to to improve performance during scrolling. +The following example creates a and sets the `VirtualizingStackPanel.VirtualizationMode` attached property to to improve performance during scrolling. ## Code [!code-xaml[RecycleItemContainerShippets#VirtualizationMode](../../../../samples/snippets/csharp/VS_Snippets_Wpf/RecycleItemContainerShippets/CSharp/Window1.xaml#virtualizationmode)] diff --git a/docs/framework/wpf/controls/how-to-position-a-tooltip.md b/docs/framework/wpf/controls/how-to-position-a-tooltip.md index c0796513f746a..54925cce06519 100644 --- a/docs/framework/wpf/controls/how-to-position-a-tooltip.md +++ b/docs/framework/wpf/controls/how-to-position-a-tooltip.md @@ -26,13 +26,13 @@ This example shows how to specify the position of a tooltip on the screen. ### Corresponding tooltip properties according to class -| class properties| class properties| +| class properties| class properties| |--------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| -||| -||| -||| -||| -||| +||| +||| +||| +||| +||| If you define the contents of a tooltip by using a object, you can use the properties of either class; however, the properties take precedence. Use the properties for tooltips that are not defined as objects. diff --git a/docs/framework/wpf/controls/label-styles-and-templates.md b/docs/framework/wpf/controls/label-styles-and-templates.md index da83b9adc69c0..f9379b92b1ba5 100644 --- a/docs/framework/wpf/controls/label-styles-and-templates.md +++ b/docs/framework/wpf/controls/label-styles-and-templates.md @@ -33,9 +33,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Label ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/label.md b/docs/framework/wpf/controls/label.md index ec6ea2a8d5786..82d969c3b0228 100644 --- a/docs/framework/wpf/controls/label.md +++ b/docs/framework/wpf/controls/label.md @@ -23,7 +23,7 @@ manager: "wpickett" # Label controls usually provide information in the [!INCLUDE[TLA#tla_ui](../../../../includes/tlasharptla-ui-md.md)]. Historically, a has contained only text, but because the that ships with [!INCLUDE[TLA#tla_winclient](../../../../includes/tlasharptla-winclient-md.md)] is a , it can contain either text or a . - A provides both functional and visual support for access keys. It is frequently used to enable quick keyboard access to controls such as a . To assign a to a , set the property to the control that should get focus when the user presses the access key. + A provides both functional and visual support for access keys. It is frequently used to enable quick keyboard access to controls such as a . To assign a to a , set the property to the control that should get focus when the user presses the access key. The following image shows a "Themes" that targets a . When the user presses , the receives focus. For more information, see [How to: Set the Target Property of a Label](http://msdn.microsoft.com/en-us/b24c6977-ebcb-4855-a9bb-3fd4435af8f8). diff --git a/docs/framework/wpf/controls/listbox-styles-and-templates.md b/docs/framework/wpf/controls/listbox-styles-and-templates.md index b8deaf9b6c93e..1f1a3384262e6 100644 --- a/docs/framework/wpf/controls/listbox-styles-and-templates.md +++ b/docs/framework/wpf/controls/listbox-styles-and-templates.md @@ -55,9 +55,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ListBox ControlTemplate Example The following example shows how to define a for the and controls. diff --git a/docs/framework/wpf/controls/listview-styles-and-templates.md b/docs/framework/wpf/controls/listview-styles-and-templates.md index 28ef9aba58724..c65201feab76d 100644 --- a/docs/framework/wpf/controls/listview-styles-and-templates.md +++ b/docs/framework/wpf/controls/listview-styles-and-templates.md @@ -35,9 +35,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ListViewItem Parts The control does not have any named parts. @@ -55,9 +55,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ListView ControlTemplate Examples The following example shows how to define a for the control and its associated types. diff --git a/docs/framework/wpf/controls/menu-styles-and-templates.md b/docs/framework/wpf/controls/menu-styles-and-templates.md index 417d139c72d7a..a0d7292d9ffba 100644 --- a/docs/framework/wpf/controls/menu-styles-and-templates.md +++ b/docs/framework/wpf/controls/menu-styles-and-templates.md @@ -35,9 +35,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## MenuItem Parts The following table lists the named parts for the control. @@ -53,9 +53,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Menu and MenuItem ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/navigationwindow-styles-and-templates.md b/docs/framework/wpf/controls/navigationwindow-styles-and-templates.md index acb888ba9e71f..2d142d28751e4 100644 --- a/docs/framework/wpf/controls/navigationwindow-styles-and-templates.md +++ b/docs/framework/wpf/controls/navigationwindow-styles-and-templates.md @@ -37,9 +37,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## NavigationWindow ControlTemplate Example Although this example contains all of the elements that are defined in the of a by default, the specific values should be thought of as examples. diff --git a/docs/framework/wpf/controls/panels-overview.md b/docs/framework/wpf/controls/panels-overview.md index 6760b2a90e5b5..704d07fe262db 100644 --- a/docs/framework/wpf/controls/panels-overview.md +++ b/docs/framework/wpf/controls/panels-overview.md @@ -49,7 +49,7 @@ manager: "wpickett" exposes additional properties that are of critical importance in understanding and using layout. The property is used to fill the area between the boundaries of a derived panel element with a . represents the child collection of elements that the is comprised of. represents the content of the collection plus those members generated by data binding. Both consist of a of child elements hosted within the parent . - Panel also exposes a attached property that can be used to achieve layered order in a derived . Members of a panel's collection with a higher value appear in front of those with a lower value. This is particularly useful for panels such as and which allow children to share the same coordinate space. + Panel also exposes a attached property that can be used to achieve layered order in a derived . Members of a panel's collection with a higher value appear in front of those with a lower value. This is particularly useful for panels such as and which allow children to share the same coordinate space. also defines the method, which can be used to override the default presentation behavior of a . @@ -98,7 +98,7 @@ manager: "wpickett" ### Canvas The element enables positioning of content according to absolute *x-* and *y-*coordinates. Elements can be drawn in a unique location; or, if elements occupy the same coordinates, the order in which they appear in markup determines the order in which the elements are drawn. - provides the most flexible layout support of any . Height and Width properties are used to define the area of the canvas, and elements inside are assigned absolute coordinates relative to the area of the parent . Four attached properties, , , and , allow fine control of object placement within a , allowing the developer to position and arrange elements precisely on the screen. + provides the most flexible layout support of any . Height and Width properties are used to define the area of the canvas, and elements inside are assigned absolute coordinates relative to the area of the parent . Four attached properties, , , and , allow fine control of object placement within a , allowing the developer to position and arrange elements precisely on the screen. #### ClipToBounds Within a Canvas can position child elements at any position on the screen, even at coordinates that are outside of its own defined and . Furthermore, is not affected by the size of its children. As a result, it is possible for a child element to overdraw other elements outside the bounding rectangle of the parent . The default behavior of a is to allow children to be drawn outside the bounds of the parent . If this behavior is undesirable, the property can be set to `true`. This causes to clip to its own size. is the only layout element that allows children to be drawn outside its bounds. @@ -118,7 +118,7 @@ manager: "wpickett" ### DockPanel - The element uses the attached property as set in child content elements to position content along the edges of a container. When is set to or , it positions child elements above or below each other. When is set to or , it positions child elements to the left or right of each other. The property determines the position of the final element added as a child of a . + The element uses the attached property as set in child content elements to position content along the edges of a container. When is set to or , it positions child elements above or below each other. When is set to or , it positions child elements to the left or right of each other. The property determines the position of the final element added as a child of a . You can use to position a group of related controls, such as a set of buttons. Alternately, you can use it to create a "paned" [!INCLUDE[TLA2#tla_ui](../../../../includes/tla2sharptla-ui-md.md)], similar to that found in [!INCLUDE[TLA#tla_outlook](../../../../includes/tlasharptla-outlook-md.md)]. @@ -194,7 +194,7 @@ manager: "wpickett" The element is automatically set as the items host for controls such as the . When hosting a data bound collection, content is automatically virtualized, as long as the content is within the bounds of a . This greatly improves performance when hosting many child items. - The following markup demonstrates how to use a as an items host. The attached property must be set to `true` (default) for virtualization to occur. + The following markup demonstrates how to use a as an items host. The attached property must be set to `true` (default) for virtualization to occur. [!code-xaml[VirtualizingStackPanel_Intro#1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/VirtualizingStackPanel_Intro/CS/default.xaml#1)] diff --git a/docs/framework/wpf/controls/passwordbox-syles-and-templates.md b/docs/framework/wpf/controls/passwordbox-syles-and-templates.md index 09a669ef442e1..2356ec18b1cfe 100644 --- a/docs/framework/wpf/controls/passwordbox-syles-and-templates.md +++ b/docs/framework/wpf/controls/passwordbox-syles-and-templates.md @@ -42,9 +42,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## PasswordBox ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/popup-placement-behavior.md b/docs/framework/wpf/controls/popup-placement-behavior.md index 08a7e53fdc9fc..5647f9d1b3f1e 100644 --- a/docs/framework/wpf/controls/popup-placement-behavior.md +++ b/docs/framework/wpf/controls/popup-placement-behavior.md @@ -58,7 +58,7 @@ Image with four Popups ### Target Object The *target object* is the element that the is associated with. If the property is set, it specifies the target object. If is not set, and the has a parent, the parent is the target object. If there is no value and no parent, there is no target object, and the is positioned relative to the screen. - The following example creates a that is the child of a . The example does not set the property on the . The default value for is , so the appears below the . + The following example creates a that is the child of a . The example does not set the property on the . The default value for is , so the appears below the . [!code-xaml[PopupPositionSnippet#1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/PopupPositionSnippet/CS/Window1.xaml#1)] diff --git a/docs/framework/wpf/controls/progressbar-styles-and-templates.md b/docs/framework/wpf/controls/progressbar-styles-and-templates.md index 9bcddaf4b6f22..e02d26e944478 100644 --- a/docs/framework/wpf/controls/progressbar-styles-and-templates.md +++ b/docs/framework/wpf/controls/progressbar-styles-and-templates.md @@ -41,9 +41,9 @@ This topic describes the styles and templates for the reports progress based on the property.| |Indeterminate|CommonStates| reports generic progress with a repeating pattern.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ProgressBar ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/radiobutton-styles-and-templates.md b/docs/framework/wpf/controls/radiobutton-styles-and-templates.md index ade74e78877bc..9b28a6d882ad0 100644 --- a/docs/framework/wpf/controls/radiobutton-styles-and-templates.md +++ b/docs/framework/wpf/controls/radiobutton-styles-and-templates.md @@ -42,9 +42,9 @@ This topic describes the styles and templates for the is `true`.| |Unchecked|CheckStates| is `false`.| |Indeterminate|CheckStates| is `true`, and is `null`.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## RadioButton ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/repeatbutton-syles-and-templates.md b/docs/framework/wpf/controls/repeatbutton-syles-and-templates.md index ab2a3f46e37a7..8cd21b23c0639 100644 --- a/docs/framework/wpf/controls/repeatbutton-syles-and-templates.md +++ b/docs/framework/wpf/controls/repeatbutton-syles-and-templates.md @@ -39,9 +39,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## RepeatButton ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/scrollbar-styles-and-templates.md b/docs/framework/wpf/controls/scrollbar-styles-and-templates.md index f7b7a8e7dbd78..866824183db3c 100644 --- a/docs/framework/wpf/controls/scrollbar-styles-and-templates.md +++ b/docs/framework/wpf/controls/scrollbar-styles-and-templates.md @@ -40,9 +40,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ScrollBar ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/scrollviewer-styles-and-templates.md b/docs/framework/wpf/controls/scrollviewer-styles-and-templates.md index 76687146886fc..347106e9e2b6d 100644 --- a/docs/framework/wpf/controls/scrollviewer-styles-and-templates.md +++ b/docs/framework/wpf/controls/scrollviewer-styles-and-templates.md @@ -39,9 +39,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ScrollViewer ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/sizing-options-in-the-datagrid-control.md b/docs/framework/wpf/controls/sizing-options-in-the-datagrid-control.md index be342a82603b3..6ac003241e2b1 100644 --- a/docs/framework/wpf/controls/sizing-options-in-the-datagrid-control.md +++ b/docs/framework/wpf/controls/sizing-options-in-the-datagrid-control.md @@ -25,7 +25,7 @@ Various options are available to control how the and properties of the are set to ("`Auto`" in XAML), and the will adjust to the size of its contents. + By default, the and properties of the are set to ("`Auto`" in XAML), and the will adjust to the size of its contents. When placed inside a container that does not restrict the size of its children, such as a or , the will stretch beyond the visible bounds of the container and scrollbars will not be shown. This condition has both usability and performance implications. @@ -50,10 +50,10 @@ Various options are available to control how the row's property is set to ("`Auto`" in XAML), and the row height will expand to the size of its contents. The height of all rows in the can be specified by setting the property. Users can change the row height by dragging the row header dividers. + By default, a row's property is set to ("`Auto`" in XAML), and the row height will expand to the size of its contents. The height of all rows in the can be specified by setting the property. Users can change the row height by dragging the row header dividers. ### DataGrid Row Headers - To display row headers, the property must be set to or . By default, row headers are displayed and they automatically size to fit their content. The row headers can be given a specific width by setting the property. + To display row headers, the property must be set to or . By default, row headers are displayed and they automatically size to fit their content. The row headers can be given a specific width by setting the property. ## Sizing Columns and Column Headers @@ -72,24 +72,24 @@ Various options are available to control how the class can be used to convert data between numeric or string values and values. - By default, the property is set to , and the property is set to . When the sizing mode is set to or , columns will grow to the width of their widest visible content. When scrolling, these sizing modes will cause columns to expand if content that is larger than the current column size is scrolled into view. The column will not shrink after the content is scrolled out of view. + By default, the property is set to , and the property is set to . When the sizing mode is set to or , columns will grow to the width of their widest visible content. When scrolling, these sizing modes will cause columns to expand if content that is larger than the current column size is scrolled into view. The column will not shrink after the content is scrolled out of view. Columns in the can also be set to automatically size only within specified boundaries, or columns can be set to a specific size. The following table shows the properties that can be set to control column sizes. |Property|Description| |--------------|-----------------| -||Sets the upper bound for all columns in the .| -||Sets the upper bound for an individual column. Overrides .| -||Sets the lower bound for all columns in the .| -||Sets the lower bound for an individual column. Overrides .| -||Sets a specific width for all columns in the .| -||Sets a specific width for an individual column. Overrides .| +||Sets the upper bound for all columns in the .| +||Sets the upper bound for an individual column. Overrides .| +||Sets the lower bound for all columns in the .| +||Sets the lower bound for an individual column. Overrides .| +||Sets a specific width for all columns in the .| +||Sets a specific width for an individual column. Overrides .| ### DataGrid Column Headers - By default, column headers are displayed. To hide column headers, the property must be set to or . By default, when column headers are displayed, they automatically size to fit their content. The column headers can be given a specific height by setting the property. + By default, column headers are displayed. To hide column headers, the property must be set to or . By default, when column headers are displayed, they automatically size to fit their content. The column headers can be given a specific height by setting the property. ### Resizing with the Mouse - Users can resize rows and columns by dragging the row or column header dividers. The also supports automatic resizing of rows and columns by double-clicking the row or column header divider. To prevent a user from resizing particular columns, set the property to `false` for the individual columns. To prevent users from resizing all columns, set the property to `false`. To prevent users from resizing all rows, set the property to `false`. + Users can resize rows and columns by dragging the row or column header dividers. The also supports automatic resizing of rows and columns by double-clicking the row or column header divider. To prevent a user from resizing particular columns, set the property to `false` for the individual columns. To prevent users from resizing all columns, set the property to `false`. To prevent users from resizing all rows, set the property to `false`. ## See Also diff --git a/docs/framework/wpf/controls/slider-styles-and-templates.md b/docs/framework/wpf/controls/slider-styles-and-templates.md index f32a4e504adc2..7ac9b0aef4bb5 100644 --- a/docs/framework/wpf/controls/slider-styles-and-templates.md +++ b/docs/framework/wpf/controls/slider-styles-and-templates.md @@ -43,9 +43,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Slider ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/statusbar-styles-and-templates.md b/docs/framework/wpf/controls/statusbar-styles-and-templates.md index 188fd60d743aa..ab3fe827e06f4 100644 --- a/docs/framework/wpf/controls/statusbar-styles-and-templates.md +++ b/docs/framework/wpf/controls/statusbar-styles-and-templates.md @@ -33,9 +33,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## StatusBarItem Parts The control does not have any named parts. @@ -45,9 +45,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## StatusBar ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/styling-and-templating.md b/docs/framework/wpf/controls/styling-and-templating.md index 1ed70024c9643..74e322f20d5ec 100644 --- a/docs/framework/wpf/controls/styling-and-templating.md +++ b/docs/framework/wpf/controls/styling-and-templating.md @@ -107,7 +107,7 @@ manager: "wpickett" ### Bindings, Dynamic Resources, and Event Handlers - Note that you can use the `Setter.Value` property to specify a [Binding Markup Extension](../../../../docs/framework/wpf/advanced/binding-markup-extension.md) or a [DynamicResource Markup Extension](../../../../docs/framework/wpf/advanced/dynamicresource-markup-extension.md). For more information, see the examples provided for the property. + Note that you can use the `Setter.Value` property to specify a [Binding Markup Extension](../../../../docs/framework/wpf/advanced/binding-markup-extension.md) or a [DynamicResource Markup Extension](../../../../docs/framework/wpf/advanced/dynamicresource-markup-extension.md). For more information, see the examples provided for the property. So far, this overview only discusses the use of setters to set property value. You can also specify event handlers in a style. For more information, see . diff --git a/docs/framework/wpf/controls/tabcontrol-styles-and-templates.md b/docs/framework/wpf/controls/tabcontrol-styles-and-templates.md index 42090bfd5b32c..b38fe42f2ed5c 100644 --- a/docs/framework/wpf/controls/tabcontrol-styles-and-templates.md +++ b/docs/framework/wpf/controls/tabcontrol-styles-and-templates.md @@ -41,9 +41,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## TabItem Parts The control does not have any named parts. @@ -60,9 +60,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## TabControl ControlTemplate Example The following example shows how to define a for the and controls. diff --git a/docs/framework/wpf/controls/textbox-styles-and-templates.md b/docs/framework/wpf/controls/textbox-styles-and-templates.md index 29e613ea64790..65a1ba9f24558 100644 --- a/docs/framework/wpf/controls/textbox-styles-and-templates.md +++ b/docs/framework/wpf/controls/textbox-styles-and-templates.md @@ -43,9 +43,9 @@ This topic describes the styles and templates for the .| |Focused|FocusStates|The control has focus.| |Unfocused|FocusStates|The control does not have focus.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## TextBox ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/thumb-syles-and-templates.md b/docs/framework/wpf/controls/thumb-syles-and-templates.md index b4c857a630711..947e5b348ee63 100644 --- a/docs/framework/wpf/controls/thumb-syles-and-templates.md +++ b/docs/framework/wpf/controls/thumb-syles-and-templates.md @@ -39,9 +39,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Thumb ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/togglebutton-syles-and-templates.md b/docs/framework/wpf/controls/togglebutton-syles-and-templates.md index 5ddecfee2408e..c2b3412317cc0 100644 --- a/docs/framework/wpf/controls/togglebutton-syles-and-templates.md +++ b/docs/framework/wpf/controls/togglebutton-syles-and-templates.md @@ -42,9 +42,9 @@ This topic describes the styles and templates for the is `true`.| |Unchecked|CheckStates| is `false`.| |Indeterminate|CheckStates| is `true`, and is `null`.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| > [!NOTE] > If the Indeterminate visual state does not exist in your control template, then the Unchecked visual state will be used as default visual state. diff --git a/docs/framework/wpf/controls/toolbar-overview.md b/docs/framework/wpf/controls/toolbar-overview.md index 09ded26e0e256..ebd2e8abff678 100644 --- a/docs/framework/wpf/controls/toolbar-overview.md +++ b/docs/framework/wpf/controls/toolbar-overview.md @@ -39,7 +39,7 @@ manager: "wpickett" ![ToolBar with overflow](../../../../docs/framework/wpf/controls/media/toolbarwithoverflowitem.png "ToolbarWithOverflowItem") Toolbar with Overflow Items - You can specify when an item on a toolbar is placed on the overflow panel by setting the attached property to , , or . The following example specifies that the last four buttons on the toolbar should always be on the overflow panel. + You can specify when an item on a toolbar is placed on the overflow panel by setting the attached property to , , or . The following example specifies that the last four buttons on the toolbar should always be on the overflow panel. [!code-xaml[ToolBarExample#3](../../../../samples/snippets/csharp/VS_Snippets_Wpf/ToolBarExample/CS/Pane1.xaml#3)] diff --git a/docs/framework/wpf/controls/toolbar-styles-and-templates.md b/docs/framework/wpf/controls/toolbar-styles-and-templates.md index 3b46f8e0833a5..0cab98d160c77 100644 --- a/docs/framework/wpf/controls/toolbar-styles-and-templates.md +++ b/docs/framework/wpf/controls/toolbar-styles-and-templates.md @@ -40,9 +40,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ToolBar ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/tooltip-overview.md b/docs/framework/wpf/controls/tooltip-overview.md index d2c015b372ff6..f35cc3ff6eb97 100644 --- a/docs/framework/wpf/controls/tooltip-overview.md +++ b/docs/framework/wpf/controls/tooltip-overview.md @@ -29,9 +29,9 @@ A tooltip is a small pop-up window that appears when a user pauses the mouse poi The content of a tooltip can contain one or more lines of text, images, shapes, or other visual content. You define a tooltip for a control by setting one of the following properties to the tooltip content. -- +- -- +- Which property you use depends on whether the control that defines the tooltip inherits from the or class. @@ -41,7 +41,7 @@ A tooltip is a small pop-up window that appears when a user pauses the mouse poi [!code-xaml[GroupBoxSnippet#ToolTipString](../../../../samples/snippets/csharp/VS_Snippets_Wpf/GroupBoxSnippet/CS/Window1.xaml#tooltipstring)] - You can also define a tooltip as a object. The following example uses [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] to specify a object as the tooltip of a element. Note that the example specifies the by setting the property. + You can also define a tooltip as a object. The following example uses [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] to specify a object as the tooltip of a element. Note that the example specifies the by setting the property. [!code-xaml[ToolTipSimple#ToolTip](../../../../samples/snippets/csharp/VS_Snippets_Wpf/ToolTipSimple/CSharp/Pane1.xaml#tooltip)] diff --git a/docs/framework/wpf/controls/tooltip-styles-and-templates.md b/docs/framework/wpf/controls/tooltip-styles-and-templates.md index 97ec1b1d3eece..db766d9dcf866 100644 --- a/docs/framework/wpf/controls/tooltip-styles-and-templates.md +++ b/docs/framework/wpf/controls/tooltip-styles-and-templates.md @@ -35,9 +35,9 @@ This topic describes the styles and templates for the is visible.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## ToolTip ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/treeview-styles-and-templates.md b/docs/framework/wpf/controls/treeview-styles-and-templates.md index 7dfa138101986..1202c18dc1b6a 100644 --- a/docs/framework/wpf/controls/treeview-styles-and-templates.md +++ b/docs/framework/wpf/controls/treeview-styles-and-templates.md @@ -35,9 +35,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## TreeViewItem Parts The following table lists the named parts for the control. @@ -63,9 +63,9 @@ This topic describes the styles and templates for the is selected.| |SelectedInactive|SelectionStates|The is selected but not active.| |Unselected|SelectionStates|The is not selected.| -|Valid|ValidationStates|The control uses the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## TreeView ControlTemplate Example The following example shows how to define a for the control and its associated types. diff --git a/docs/framework/wpf/controls/ui-automation-of-a-wpf-custom-control.md b/docs/framework/wpf/controls/ui-automation-of-a-wpf-custom-control.md index 08bd1a9228d44..4a5166d1fd703 100644 --- a/docs/framework/wpf/controls/ui-automation-of-a-wpf-custom-control.md +++ b/docs/framework/wpf/controls/ui-automation-of-a-wpf-custom-control.md @@ -43,7 +43,7 @@ manager: "wpickett" ## Peer Navigation - After locating an automation peer, in-process code can navigate the peer tree by calling the object's and methods. Navigation among [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] elements within a control is supported by the peer's implementation of the method. The UI Automation system calls this method to build up a tree of subelements contained within a control; for example, list items in a list box. The default method traverses the visual tree of elements to build the tree of automation peers. Custom controls override this method to expose children elements to automation clients, returning the automation peers of elements that convey information or allow user interaction. + After locating an automation peer, in-process code can navigate the peer tree by calling the object's and methods. Navigation among [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] elements within a control is supported by the peer's implementation of the method. The UI Automation system calls this method to build up a tree of subelements contained within a control; for example, list items in a list box. The default method traverses the visual tree of elements to build the tree of automation peers. Custom controls override this method to expose children elements to automation clients, returning the automation peers of elements that convey information or allow user interaction. ## Customizations in a Derived Peer @@ -55,7 +55,7 @@ manager: "wpickett" Override the method for your custom control so that it returns your provider object, which must derive directly or indirectly from . ### Override GetPattern - Automation peers simplify some implementation aspects of server-side [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] providers, but custom control automation peers must still handle pattern interfaces. Like non-WPF providers, peers support control patterns by providing implementations of interfaces in the namespace, such as . The control pattern interfaces can be implemented by the peer itself or by another object. The peer's implementation of returns the object that supports the specified pattern. [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] code calls the method and specifies a enumeration value. Your override of should return the object that implements the specified pattern. If your control does not have a custom implementation of a pattern, you can call the base type's implementation of to retrieve either its implementation or null if the pattern is not supported for this control type. For example, a custom NumericUpDown control can be set to a value within a range, so its [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] peer would implement the interface. The following example shows how the peer's method is overridden to respond to a value. + Automation peers simplify some implementation aspects of server-side [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] providers, but custom control automation peers must still handle pattern interfaces. Like non-WPF providers, peers support control patterns by providing implementations of interfaces in the namespace, such as . The control pattern interfaces can be implemented by the peer itself or by another object. The peer's implementation of returns the object that supports the specified pattern. [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] code calls the method and specifies a enumeration value. Your override of should return the object that implements the specified pattern. If your control does not have a custom implementation of a pattern, you can call the base type's implementation of to retrieve either its implementation or null if the pattern is not supported for this control type. For example, a custom NumericUpDown control can be set to a value within a range, so its [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] peer would implement the interface. The following example shows how the peer's method is overridden to respond to a value. [!code-csharp[CustomControlNumericUpDown#GetPattern](../../../../samples/snippets/csharp/VS_Snippets_Wpf/CustomControlNumericUpDown/CSharp/CustomControlLibrary/NumericUpDown.cs#getpattern)] [!code-vb[CustomControlNumericUpDown#GetPattern](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/CustomControlNumericUpDown/visualbasic/customcontrollibrary/numericupdown.vb#getpattern)] @@ -112,9 +112,9 @@ End Class [!code-csharp[CustomControlNumericUpDown#CoreOverrides](../../../../samples/snippets/csharp/VS_Snippets_Wpf/CustomControlNumericUpDown/CSharp/CustomControlLibrary/NumericUpDown.cs#coreoverrides)] [!code-vb[CustomControlNumericUpDown#CoreOverrides](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/CustomControlNumericUpDown/visualbasic/customcontrollibrary/numericupdown.vb#coreoverrides)] - Your implementation of describes your control by returning a value. Although you can return , you should return one of the more specific control types if it accurately describes your control. A return value of requires extra work for the provider to implement [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)], and [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] client products are unable to anticipate the control structure, keyboard interaction, and possible control patterns. + Your implementation of describes your control by returning a value. Although you can return , you should return one of the more specific control types if it accurately describes your control. A return value of requires extra work for the provider to implement [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)], and [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] client products are unable to anticipate the control structure, keyboard interaction, and possible control patterns. - Implement the and methods to indicate whether your control contains data content or fulfills an interactive role in the user interface (or both). By default, both methods return `true`. These settings improve the usability of automation tools such as screen readers, which may use these methods to filter the automation tree. If your method transfers pattern handling to a subelement peer, the subelement peer's method can return false to hide the subelement peer from the automation tree. For example, scrolling in a is handled by a , and the automation peer for is returned by the method of the that is associated with the .Therefore, the method of the returns `false`, so that the does not appear in the automation tree. + Implement the and methods to indicate whether your control contains data content or fulfills an interactive role in the user interface (or both). By default, both methods return `true`. These settings improve the usability of automation tools such as screen readers, which may use these methods to filter the automation tree. If your method transfers pattern handling to a subelement peer, the subelement peer's method can return false to hide the subelement peer from the automation tree. For example, scrolling in a is handled by a , and the automation peer for is returned by the method of the that is associated with the .Therefore, the method of the returns `false`, so that the does not appear in the automation tree. Your automation peer should provide appropriate default values for your control. Note that XAML that references your control can override your peer implementations of core methods by including attributes. For example, the following XAML creates a button that has two customized [!INCLUDE[TLA2#tla_uiautomation](../../../../includes/tla2sharptla-uiautomation-md.md)] properties. diff --git a/docs/framework/wpf/controls/window-styles-and-templates.md b/docs/framework/wpf/controls/window-styles-and-templates.md index fd62949609184..24a231700b751 100644 --- a/docs/framework/wpf/controls/window-styles-and-templates.md +++ b/docs/framework/wpf/controls/window-styles-and-templates.md @@ -33,9 +33,9 @@ This topic describes the styles and templates for the class and the attached property is `false`.| -|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| -|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| +|Valid|ValidationStates|The control uses the class and the attached property is `false`.| +|InvalidFocused|ValidationStates|The attached property is `true` has the control has focus.| +|InvalidUnfocused|ValidationStates|The attached property is `true` has the control does not have focus.| ## Window ControlTemplate Example The following example shows how to define a for the control. diff --git a/docs/framework/wpf/controls/wpf-content-model.md b/docs/framework/wpf/controls/wpf-content-model.md index 938d1e9987703..e19ea8e111bc1 100644 --- a/docs/framework/wpf/controls/wpf-content-model.md +++ b/docs/framework/wpf/controls/wpf-content-model.md @@ -33,7 +33,7 @@ manager: "wpickett" ## Classes That Contain Arbitrary Content - Some controls can contain an object of any type, such as a string, a object, or a that is a container for additional items. For example, a can contain an image and some text; or a can contain the value of . + Some controls can contain an object of any type, such as a string, a object, or a that is a container for additional items. For example, a can contain an image and some text; or a can contain the value of . [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] has four classes that can contain arbitrary content. The following table lists the classes, which inherit from . diff --git a/docs/framework/wpf/data/binding-declarations-overview.md b/docs/framework/wpf/data/binding-declarations-overview.md index db5a575d6d3e0..77aa38024b909 100644 --- a/docs/framework/wpf/data/binding-declarations-overview.md +++ b/docs/framework/wpf/data/binding-declarations-overview.md @@ -41,7 +41,7 @@ This topic discusses the different ways you can declare a binding. ### Markup Extension Usage is a markup extension. When you use the binding extension to declare a binding, the declaration consists of a series of clauses following the `Binding` keyword and separated by commas (,). The clauses in the binding declaration can be in any order and there are many possible combinations. The clauses are *Name*=*Value* pairs where *Name* is the name of the property and *Value* is the value you are setting for the property. - When creating binding declaration strings in markup, they must be attached to the specific dependency property of a target object. The following example shows how to bind the property using the binding extension, specifying the and properties. + When creating binding declaration strings in markup, they must be attached to the specific dependency property of a target object. The following example shows how to bind the property using the binding extension, specifying the and properties. [!code-xaml[SimpleBinding#BDO1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/SimpleBinding/CSharp/Page1.xaml#bdo1)] @@ -72,7 +72,7 @@ This topic discusses the different ways you can declare a binding. [!code-csharp[BindConversion#end1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/BindConversion/CSharp/Window1.xaml.cs#end1)] [!code-vb[BindConversion#end1](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/BindConversion/visualbasic/window1.xaml.vb#end1)] - If the object you are binding is a or a you can call the `SetBinding` method on your object directly instead of using . For an example, see [Create a Binding in Code](../../../../docs/framework/wpf/data/how-to-create-a-binding-in-code.md). + If the object you are binding is a or a you can call the `SetBinding` method on your object directly instead of using . For an example, see [Create a Binding in Code](../../../../docs/framework/wpf/data/how-to-create-a-binding-in-code.md). ## Binding Path Syntax @@ -82,7 +82,7 @@ This topic discusses the different ways you can declare a binding. - Subproperties of a property can be specified by a similar syntax as in [!INCLUDE[TLA#tla_cshrp](../../../../includes/tlasharptla-cshrp-md.md)]. For instance, the clause `Path=ShoppingCart.Order` sets the binding to the subproperty `Order` of the object or property `ShoppingCart`. -- To bind to an attached property, place parentheses around the attached property. For example, to bind to the attached property , the syntax is `Path=(DockPanel.Dock)`. +- To bind to an attached property, place parentheses around the attached property. For example, to bind to the attached property , the syntax is `Path=(DockPanel.Dock)`. - Indexers of a property can be specified within square brackets following the property name where the indexer is applied. For instance, the clause `Path=ShoppingCart[0]` sets the binding to the index that corresponds to how your property's internal indexing handles the literal string "0". Nested indexers are also supported. @@ -126,9 +126,9 @@ This topic discusses the different ways you can declare a binding. - As long as the binding already has a data context (for instance, the inherited data context coming from a parent element), and whatever item or collection being returned by that context is appropriate for binding without requiring further path modification, a binding declaration can have no clauses at all: `{Binding}` This is often the way a binding is specified for data styling, where the binding acts upon a collection. For more information, see the "Entire Objects Used as a Binding Source" section in the [Binding Sources Overview](../../../../docs/framework/wpf/data/binding-sources-overview.md). -- The default varies between one-way and two-way depending on the dependency property that is being bound. You can always declare the binding mode explicitly to ensure that your binding has the desired behavior. In general, user-editable control properties, such as and , default to two-way bindings, whereas most other properties default to one-way bindings. +- The default varies between one-way and two-way depending on the dependency property that is being bound. You can always declare the binding mode explicitly to ensure that your binding has the desired behavior. In general, user-editable control properties, such as and , default to two-way bindings, whereas most other properties default to one-way bindings. -- The default value varies between and depending on the bound dependency property as well. The default value for most dependency properties is , while the property has a default value of . +- The default value varies between and depending on the bound dependency property as well. The default value for most dependency properties is , while the property has a default value of . ## See Also [Data Binding Overview](../../../../docs/framework/wpf/data/data-binding-overview.md) diff --git a/docs/framework/wpf/data/data-binding-overview.md b/docs/framework/wpf/data/data-binding-overview.md index 234d558f0983b..2b74f5f9a325e 100644 --- a/docs/framework/wpf/data/data-binding-overview.md +++ b/docs/framework/wpf/data/data-binding-overview.md @@ -116,7 +116,7 @@ manager: "wpickett" |UpdateSourceTrigger value|When the Source Value Gets Updated|Example Scenario for TextBox| |-------------------------------|----------------------------------------|----------------------------------| -|LostFocus (default for )|When the TextBox control loses focus|A that is associated with validation logic (see Data Validation section)| +|LostFocus (default for )|When the TextBox control loses focus|A that is associated with validation logic (see Data Validation section)| |PropertyChanged|As you type into the | controls in a chat room window| |Explicit|When the application calls | controls in an editable form (updates the source values only when the user clicks the submit button)| @@ -361,7 +361,7 @@ manager: "wpickett" Most applications that take user input need to have validation logic to ensure that the user has entered the expected information. The validation checks can be based on type, range, format, or other application-specific requirements. This section discusses how data validation works in the [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)]. ### Associating Validation Rules with a Binding - The [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] data binding model allows you to associate with your object. For example, the following example binds a to a property named `StartPrice` and adds a object to the property. + The [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] data binding model allows you to associate with your object. For example, the following example binds a to a property named `StartPrice` and adds a object to the property. [!code-xaml[DataBindingLab#DefaultValidation](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DataBindingLab/CSharp/AddProductWindow.xaml#defaultvalidation)] @@ -384,13 +384,13 @@ manager: "wpickett" ### Providing Visual Feedback - If the user enters an invalid value, you may want to provide some feedback about the error on the application [!INCLUDE[TLA2#tla_ui](../../../../includes/tla2sharptla-ui-md.md)]. One way to provide such feedback is to set the attached property to a custom . As shown in the previous subsection, the *StartDateEntryForm* uses an called *validationTemplate*. The following example shows the definition of *validationTemplate*: + If the user enters an invalid value, you may want to provide some feedback about the error on the application [!INCLUDE[TLA2#tla_ui](../../../../includes/tla2sharptla-ui-md.md)]. One way to provide such feedback is to set the attached property to a custom . As shown in the previous subsection, the *StartDateEntryForm* uses an called *validationTemplate*. The following example shows the definition of *validationTemplate*: [!code-xaml[DataBindingLab#1](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DataBindingLab/CSharp/AddProductWindow.xaml#1)] The element specifies where the control being adorned should be placed. - In addition, you may also use a to display the error message. Both the *StartDateEntryForm* and the *StartPriceEntryForm*es use the style *textStyleTextBox*, which creates a that displays the error message. The following example shows the definition of *textStyleTextBox*. The attached property is `true` when one or more of the bindings on the properties of the bound element are in error. + In addition, you may also use a to display the error message. Both the *StartDateEntryForm* and the *StartPriceEntryForm*es use the style *textStyleTextBox*, which creates a that displays the error message. The following example shows the definition of *textStyleTextBox*. The attached property is `true` when one or more of the bindings on the properties of the bound element are in error. [!code-xaml[DataBindingLab#14](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DataBindingLab/CSharp/DataBindingLabApp.xaml#14)] @@ -421,16 +421,16 @@ manager: "wpickett" 6. The binding engine checks if there are any custom objects defined whose is set to for that , in which case it calls the method on each that has set to until one of them runs into an error or until all of them pass. - If a does not pass at any time throughout this process, the binding engine creates a object and adds it to the collection of the bound element. Before the binding engine runs the objects at any given step, it removes any that was added to the attached property of the bound element during that step. For example, if a whose is set to failed, the next time the validation process occurs, the binding engine removes that immediately before it calls any that has set to . + If a does not pass at any time throughout this process, the binding engine creates a object and adds it to the collection of the bound element. Before the binding engine runs the objects at any given step, it removes any that was added to the attached property of the bound element during that step. For example, if a whose is set to failed, the next time the validation process occurs, the binding engine removes that immediately before it calls any that has set to . - When is not empty, the attached property of the element is set to `true`. Also, if the property of the is set to `true`, then the binding engine raises the attached event on the element. + When is not empty, the attached property of the element is set to `true`. Also, if the property of the is set to `true`, then the binding engine raises the attached event on the element. - Also note that a valid value transfer in either direction (target to source or source to target) clears the attached property. + Also note that a valid value transfer in either direction (target to source or source to target) clears the attached property. - If the binding either has an associated with it, or had the property is set to `true` and an exception is thrown when the binding engine sets the source, the binding engine checks to see if there is a . You have the option to use the callback to provide a custom handler for handling exceptions. If an is not specified on the , the binding engine creates a with the exception and adds it to the collection of the bound element. + If the binding either has an associated with it, or had the property is set to `true` and an exception is thrown when the binding engine sets the source, the binding engine checks to see if there is a . You have the option to use the callback to provide a custom handler for handling exceptions. If an is not specified on the , the binding engine creates a with the exception and adds it to the collection of the bound element. ## Debugging Mechanism - You can set the attached property on a binding-related object to receive information about the status of a specific binding. + You can set the attached property on a binding-related object to receive information about the status of a specific binding. ## See Also diff --git a/docs/framework/wpf/data/how-to-create-a-binding-in-code.md b/docs/framework/wpf/data/how-to-create-a-binding-in-code.md index a45dda92236c5..fab758999d2d6 100644 --- a/docs/framework/wpf/data/how-to-create-a-binding-in-code.md +++ b/docs/framework/wpf/data/how-to-create-a-binding-in-code.md @@ -36,7 +36,7 @@ This example shows how to create and set a in For the complete code sample, see [Code-only Binding Sample](http://msdn.microsoft.com/en-us/764aaf0b-2216-4941-9548-9c98da18d1a6). - Instead of calling , you can use the static method of the class. The following example, calls instead of to bind `myText` to `myDataProperty`. + Instead of calling , you can use the static method of the class. The following example, calls instead of to bind `myText` to `myDataProperty`. [!code-csharp[CodeOnlyBinding#BOSetBinding](../../../../samples/snippets/csharp/VS_Snippets_Wpf/CodeOnlyBinding/CSharp/binding.cs#bosetbinding)] [!code-vb[CodeOnlyBinding#BOSetBinding](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/CodeOnlyBinding/VisualBasic/App.vb#bosetbinding)] diff --git a/docs/framework/wpf/data/how-to-implement-prioritybinding.md b/docs/framework/wpf/data/how-to-implement-prioritybinding.md index 3fa1289a6394a..b5ee9b74cd79a 100644 --- a/docs/framework/wpf/data/how-to-implement-prioritybinding.md +++ b/docs/framework/wpf/data/how-to-implement-prioritybinding.md @@ -50,6 +50,6 @@ manager: "wpickett" See for information about what is considered a successful return value from a binding. ## See Also - + [Data Binding Overview](../../../../docs/framework/wpf/data/data-binding-overview.md) [How-to Topics](../../../../docs/framework/wpf/data/data-binding-how-to-topics.md) diff --git a/docs/framework/wpf/data/how-to-specify-the-binding-source.md b/docs/framework/wpf/data/how-to-specify-the-binding-source.md index 496afc040ee88..114e5256c56e9 100644 --- a/docs/framework/wpf/data/how-to-specify-the-binding-source.md +++ b/docs/framework/wpf/data/how-to-specify-the-binding-source.md @@ -47,8 +47,8 @@ In data binding, the binding source object refers to the object you obtain your ||You specify a string that represents the element you want to bind to. This is useful when you want to bind to the property of another element on your application. For example, if you want to use a to control the height of another control in your application, or if you want to bind the of your control to the property of your control. For more information, see .| ## See Also - - + + [Property Value Inheritance](../../../../docs/framework/wpf/advanced/property-value-inheritance.md) [Data Binding Overview](../../../../docs/framework/wpf/data/data-binding-overview.md) [Binding Declarations Overview](../../../../docs/framework/wpf/data/binding-declarations-overview.md) diff --git a/docs/framework/wpf/getting-started/walkthrough-my-first-wpf-desktop-application.md b/docs/framework/wpf/getting-started/walkthrough-my-first-wpf-desktop-application.md index 4376abf661c35..ec0b7c6683cbe 100644 --- a/docs/framework/wpf/getting-started/walkthrough-my-first-wpf-desktop-application.md +++ b/docs/framework/wpf/getting-started/walkthrough-my-first-wpf-desktop-application.md @@ -223,7 +223,7 @@ For more information about installing the latest version of Visual Studio, see [ - (to click to view the expense report for the person that is selected in the list). - Each control is placed in a row of the by setting the attached property. For more information about attached properties, see [Attached Properties Overview](../../../../docs/framework/wpf/advanced/attached-properties-overview.md). + Each control is placed in a row of the by setting the attached property. For more information about attached properties, see [Attached Properties Overview](../../../../docs/framework/wpf/advanced/attached-properties-overview.md). 1. Open ExpenseItHome.xaml. @@ -250,7 +250,7 @@ For more information about installing the latest version of Visual Studio, see [ [!code-xaml[ExpenseIt#11b](../../../../samples/snippets/csharp/VS_Snippets_Wpf/ExpenseIt/CSharp/ExpenseIt5/ExpenseItHome.xaml#11b)] -4. Move the controls to the second column by setting to 1. Move each control down a row, by increasing the by 1. +4. Move the controls to the second column by setting to 1. Move each control down a row, by increasing the by 1. [!code-xaml[ExpenseIt#12](../../../../samples/snippets/csharp/VS_Snippets_Wpf/ExpenseIt/CSharp/ExpenseIt5/ExpenseItHome.xaml#12)] @@ -312,7 +312,7 @@ For more information about installing the latest version of Visual Studio, see [ 1. Open Application.xaml or App.xaml. -2. Add the following XAML between the tags: +2. Add the following XAML between the tags: [!code-xaml[ExpenseIt#18](../../../../samples/snippets/csharp/VS_Snippets_Wpf/ExpenseIt/CSharp/ExpenseIt7/App.xaml#18)] @@ -330,7 +330,7 @@ For more information about installing the latest version of Visual Studio, see [ - `buttonStyle`: To format the on ExpenseItHome.xaml. - Notice that the styles are resources and children of the property element. In this location, the styles are applied to all the elements in an application. For an example of using resources in a [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] application, see [Use Application Resources](../../../../docs/framework/wpf/advanced/how-to-use-application-resources.md). + Notice that the styles are resources and children of the property element. In this location, the styles are applied to all the elements in an application. For an example of using resources in a [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] application, see [Use Application Resources](../../../../docs/framework/wpf/advanced/how-to-use-application-resources.md). 3. Open ExpenseItHome.xaml. diff --git a/docs/framework/wpf/getting-started/whats-new.md b/docs/framework/wpf/getting-started/whats-new.md index a21041a64da02..f0cdabfae0029 100644 --- a/docs/framework/wpf/getting-started/whats-new.md +++ b/docs/framework/wpf/getting-started/whats-new.md @@ -64,7 +64,7 @@ manager: "wpickett" 1. You can specify whether a , such as the , displays partial items by using the attached property. If is set to , the will only display items that are completely visible. If is set to , the can display partially visible items. -2. You can specify the size of the cache before and after the viewport when the is virtualizing by using the attached property. The cache is the amount of space above or below the viewport in which items are not virtualized. Using a cache to avoid generating UI elements as they’re scrolled into view can improve performance. The cache is populated at a lower priority so that the application does not become unresponsive during the operation. The property determines the unit of measurement that is used by . +2. You can specify the size of the cache before and after the viewport when the is virtualizing by using the attached property. The cache is the amount of space above or below the viewport in which items are not virtualized. Using a cache to avoid generating UI elements as they’re scrolled into view can improve performance. The cache is populated at a lower priority so that the application does not become unresponsive during the operation. The property determines the unit of measurement that is used by . ## Binding to static properties @@ -104,16 +104,16 @@ manager: "wpickett" |To find this value of the binding|Use this API| |---------------------------------------|------------------| -|The target object|| -|The target property|| -|The source object|| -|The source property|| -|Whether the belongs to a || +|The target object|| +|The target property|| +|The source object|| +|The source property|| +|Whether the belongs to a || |The owner of a || ## Checking for a valid DataContext object - There are cases where the of an item container in an becomes disconnected. An item container is the UI element that displays an item in an . When an is data bound to a collection, an item container is generated for each item. In some cases, item containers are removed from the visual tree. Two typical cases where an item container is removed are when an item is removed from the underlying collection and when virtualization is enabled on the . In these cases, the property of the item container will be set to the sentinel object that is returned by the static property. You should check whether the is equal to the object before accessing the of an item container. + There are cases where the of an item container in an becomes disconnected. An item container is the UI element that displays an item in an . When an is data bound to a collection, an item container is generated for each item. In some cases, item containers are removed from the visual tree. Two typical cases where an item container is removed are when an item is removed from the underlying collection and when virtualization is enabled on the . In these cases, the property of the item container will be set to the sentinel object that is returned by the static property. You should check whether the is equal to the object before accessing the of an item container. ## Repositioning data as the data's values change (Live shaping) @@ -125,7 +125,7 @@ manager: "wpickett" ## New methods for the Dispatcher class - The Dispatcher class defines new methods for synchronous and asynchronous operations. The synchronous method defines overloads that take an or parameter. The new asynchronous method, , also takes an or as the callback parameter and returns a or . The and classes define a property. When you call , you can use the `await` keyword with either the or the associated . If you need to wait synchronously for the that is returned by a or , call the extension method. Calling will result in a deadlock if the operation is queued on a calling thread. For more information about using a to perform asynchronous operations, see [Task Parallelism (Task Parallel Library)](../../../../docs/standard/parallel-programming/task-based-asynchronous-programming.md). + The Dispatcher class defines new methods for synchronous and asynchronous operations. The synchronous method defines overloads that take an or parameter. The new asynchronous method, , also takes an or as the callback parameter and returns a or . The and classes define a property. When you call , you can use the `await` keyword with either the or the associated . If you need to wait synchronously for the that is returned by a or , call the extension method. Calling will result in a deadlock if the operation is queued on a calling thread. For more information about using a to perform asynchronous operations, see [Task Parallelism (Task Parallel Library)](../../../../docs/standard/parallel-programming/task-based-asynchronous-programming.md). ## Markup Extensions for Events diff --git a/docs/framework/wpf/getting-started/wpf-walkthroughs.md b/docs/framework/wpf/getting-started/wpf-walkthroughs.md index 230fd5b48c089..d83033f838aaf 100644 --- a/docs/framework/wpf/getting-started/wpf-walkthroughs.md +++ b/docs/framework/wpf/getting-started/wpf-walkthroughs.md @@ -46,7 +46,7 @@ Walkthroughs give step-by-step instructions for common scenarios. This makes the |Title|Description| |-----------|-----------------| -|[Walkthrough: Hosting a Windows Forms Control in WPF](../../../../docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md)|Demonstrates how to host a Windows Forms control in a WPF application.| +|[Walkthrough: Hosting a Windows Forms Control in WPF](../../../../docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-control-in-wpf.md)|Demonstrates how to host a Windows Forms control in a WPF application.| |[Walkthrough: Hosting a Windows Forms Composite Control in WPF](../../../../docs/framework/wpf/advanced/walkthrough-hosting-a-windows-forms-composite-control-in-wpf.md)|Demonstrates how to host a [!INCLUDE[TLA2#tla_winforms](../../../../includes/tla2sharptla-winforms-md.md)] data-entry composite control in a [!INCLUDE[TLA2#tla_winclient](../../../../includes/tla2sharptla-winclient-md.md)] application.| |[Walkthrough: Hosting a WPF Composite Control in Windows Forms](../../../../docs/framework/wpf/advanced/walkthrough-hosting-a-wpf-composite-control-in-windows-forms.md)|Demonstrates how to host a WPF data-entry composite control in a Windows Forms application.| |[Walkthrough: Arranging Windows Forms Controls in WPF](../../../../docs/framework/wpf/advanced/walkthrough-arranging-windows-forms-controls-in-wpf.md)|Demonstrates how to use WPF layout features to arrange Windows Forms controls in a hybrid application.| diff --git a/docs/framework/wpf/graphics-multimedia/animation-and-timing-system-overview.md b/docs/framework/wpf/graphics-multimedia/animation-and-timing-system-overview.md index 1381268c7d7e2..1959d009a4ba3 100644 --- a/docs/framework/wpf/graphics-multimedia/animation-and-timing-system-overview.md +++ b/docs/framework/wpf/graphics-multimedia/animation-and-timing-system-overview.md @@ -31,7 +31,7 @@ This topic describes how the timing system uses the animation, is a special type of object that maintains timing-related run-time state for the . It provides three bits of information that are essential to the animation and timing system: , , and . A determines its current time, progress, and state by using the timing behaviors described by its : , , , and so on. - In most cases, a is created automatically for your timeline. When you animate by using a or the method, clocks are automatically created for your timelines and animations and applied to their targeted properties. You can also create a explicitly by using the method of your . The method creates a clock of the appropriate type for the on which it is called. If the contains child timelines, it creates objects for them as well. The resulting objects are arranged in trees that match the structure of the objects tree from which they are created. + In most cases, a is created automatically for your timeline. When you animate by using a or the method, clocks are automatically created for your timelines and animations and applied to their targeted properties. You can also create a explicitly by using the method of your . The method creates a clock of the appropriate type for the on which it is called. If the contains child timelines, it creates objects for them as well. The resulting objects are arranged in trees that match the structure of the objects tree from which they are created. There are different types of clocks for different types of timelines. The following table shows the types that correspond to some of the different types. diff --git a/docs/framework/wpf/graphics-multimedia/animation-overview.md b/docs/framework/wpf/graphics-multimedia/animation-overview.md index 8a35f48e8912e..f410bf9d53efe 100644 --- a/docs/framework/wpf/graphics-multimedia/animation-overview.md +++ b/docs/framework/wpf/graphics-multimedia/animation-overview.md @@ -122,7 +122,7 @@ manager: "wpickett" [!code-csharp[animation_ovws2#RectangleOpacityFadeExampleCode_101](../../../../samples/snippets/csharp/VS_Snippets_Wpf/animation_ovws2/CSharp/MainWindow.xaml.cs#rectangleopacityfadeexamplecode_101)] [!code-vb[animation_ovws2#RectangleOpacityFadeExampleCode_101](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/animation_ovws2/VisualBasic/MainWindow.xaml.vb#rectangleopacityfadeexamplecode_101)] -2. The has to know where to apply the animation. Use the attached property to specify the object to animate. The following shows how to set the target name of the to `MyRectangle` in XAML. +2. The has to know where to apply the animation. Use the attached property to specify the object to animate. The following shows how to set the target name of the to `MyRectangle` in XAML. [!code-xaml[animation_ovws2#RectangleOpacityFadeExampleXaml_6](../../../../samples/snippets/csharp/VS_Snippets_Wpf/animation_ovws2/CSharp/Window1.xaml#rectangleopacityfadeexamplexaml_6)] diff --git a/docs/framework/wpf/graphics-multimedia/drawing-objects-overview.md b/docs/framework/wpf/graphics-multimedia/drawing-objects-overview.md index 980ae735ce3af..db0537ef3a9be 100644 --- a/docs/framework/wpf/graphics-multimedia/drawing-objects-overview.md +++ b/docs/framework/wpf/graphics-multimedia/drawing-objects-overview.md @@ -195,7 +195,7 @@ Order of DrawingGroup operations ## Display a Drawing as an Image - To display a with an control, use a as the control's and set the object's property to the drawing you want to display. + To display a with an control, use a as the control's and set the object's property to the drawing you want to display. The following example uses a and an control to display a . This example produces the following output. @@ -227,9 +227,9 @@ A GeometryDrawing used with a DrawingBrush ## DrawingContext Objects The class enables you to populate a or a with visual content. Many such lower-level graphics objects use a because it describes graphical content very efficiently. - Although the draw methods appear similar to the draw methods of the type, they are actually very different. is used with a retained mode graphics system, while the type is used with an immediate mode graphics system. When you use a object's draw commands, you are actually storing a set of rendering instructions (although the exact storage mechanism depends on the type of object that supplies the ) that will later be used by the graphics system; you are not drawing to the screen in real-time. For more information about how the [!INCLUDE[TLA#tla_wpf](../../../../includes/tlasharptla-wpf-md.md)] graphics system works, see the [WPF Graphics Rendering Overview](../../../../docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md). + Although the draw methods appear similar to the draw methods of the type, they are actually very different. is used with a retained mode graphics system, while the type is used with an immediate mode graphics system. When you use a object's draw commands, you are actually storing a set of rendering instructions (although the exact storage mechanism depends on the type of object that supplies the ) that will later be used by the graphics system; you are not drawing to the screen in real-time. For more information about how the [!INCLUDE[TLA#tla_wpf](../../../../includes/tlasharptla-wpf-md.md)] graphics system works, see the [WPF Graphics Rendering Overview](../../../../docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md). - You never directly instantiate a ; you can, however, acquire a drawing context from certain methods, such as and . + You never directly instantiate a ; you can, however, acquire a drawing context from certain methods, such as and . ## Enumerate the Contents of a Visual diff --git a/docs/framework/wpf/graphics-multimedia/how-to-add-an-animation-output-value-to-an-animation-starting-value.md b/docs/framework/wpf/graphics-multimedia/how-to-add-an-animation-output-value-to-an-animation-starting-value.md index cba99354db17c..054a6a286d839 100644 --- a/docs/framework/wpf/graphics-multimedia/how-to-add-an-animation-output-value-to-an-animation-starting-value.md +++ b/docs/framework/wpf/graphics-multimedia/how-to-add-an-animation-output-value-to-an-animation-starting-value.md @@ -24,7 +24,7 @@ This example shows how to add an animation output value to an animation starting ## Example The property specifies whether you want the output value of an animation added to the starting value (base value) of an animated property. You can use the property with most basic animations and most key frame animations. For more information, see [Animation Overview](../../../../docs/framework/wpf/graphics-multimedia/animation-overview.md) and [Key-Frame Animations Overview](../../../../docs/framework/wpf/graphics-multimedia/key-frame-animations-overview.md). - The following example shows the effect of using the property with and using the property with . + The following example shows the effect of using the property with and using the property with . [!code-xaml[timingbehaviors_snip#IsAdditiveWholePage](../../../../samples/snippets/csharp/VS_Snippets_Wpf/timingbehaviors_snip/CSharp/IsAdditiveExample.xaml#isadditivewholepage)] diff --git a/docs/framework/wpf/graphics-multimedia/how-to-animate-a-point-by-using-key-frames.md b/docs/framework/wpf/graphics-multimedia/how-to-animate-a-point-by-using-key-frames.md index 6fd47be93e60d..e87621b1224bc 100644 --- a/docs/framework/wpf/graphics-multimedia/how-to-animate-a-point-by-using-key-frames.md +++ b/docs/framework/wpf/graphics-multimedia/how-to-animate-a-point-by-using-key-frames.md @@ -41,7 +41,7 @@ This example shows how to use the - + [Key-Frame Animations Overview](../../../../docs/framework/wpf/graphics-multimedia/key-frame-animations-overview.md) [Key-Frame How-to Topics](../../../../docs/framework/wpf/graphics-multimedia/key-frame-animation-how-to-topics.md) diff --git a/docs/framework/wpf/graphics-multimedia/how-to-draw-an-image-using-imagedrawing.md b/docs/framework/wpf/graphics-multimedia/how-to-draw-an-image-using-imagedrawing.md index ab1b343a3c27b..ba1be1420ee51 100644 --- a/docs/framework/wpf/graphics-multimedia/how-to-draw-an-image-using-imagedrawing.md +++ b/docs/framework/wpf/graphics-multimedia/how-to-draw-an-image-using-imagedrawing.md @@ -22,7 +22,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Draw an Image Using ImageDrawing -This example shows how to use an to draw an image. An enables you display an with a , , or . To draw an image, you create an and set its and properties. The property specifies the image to draw, and the property specifies the position and size of each image. +This example shows how to use an to draw an image. An enables you display an with a , , or . To draw an image, you create an and set its and properties. The property specifies the image to draw, and the property specifies the position and size of each image. ## Example The following example creates a composite drawing using four objects. This example produces the following image: diff --git a/docs/framework/wpf/graphics-multimedia/how-to-paint-an-area-with-a-linear-gradient.md b/docs/framework/wpf/graphics-multimedia/how-to-paint-an-area-with-a-linear-gradient.md index 41a2968d30ab3..2ba679b3bf65e 100644 --- a/docs/framework/wpf/graphics-multimedia/how-to-paint-an-area-with-a-linear-gradient.md +++ b/docs/framework/wpf/graphics-multimedia/how-to-paint-an-area-with-a-linear-gradient.md @@ -52,6 +52,6 @@ This example shows how to use the [!NOTE] -> The examples in this topic use the default coordinate system for setting start points and end points. The default coordinate system is relative to a bounding box: 0 indicates 0 percent of the bounding box, and 1 indicates 100 percent of the bounding box. You can change this coordinate system by setting the property to the value . An absolute coordinate system is not relative to a bounding box. Values are interpreted directly in local space. +> The examples in this topic use the default coordinate system for setting start points and end points. The default coordinate system is relative to a bounding box: 0 indicates 0 percent of the bounding box, and 1 indicates 100 percent of the bounding box. You can change this coordinate system by setting the property to the value . An absolute coordinate system is not relative to a bounding box. Values are interpreted directly in local space. For additional examples, see [Brushes Sample](http://go.microsoft.com/fwlink/?LinkID=159973). For more information about gradients and other types of brushes, see [Painting with Solid Colors and Gradients Overview](../../../../docs/framework/wpf/graphics-multimedia/painting-with-solid-colors-and-gradients-overview.md). diff --git a/docs/framework/wpf/graphics-multimedia/how-to-set-a-property-after-animating-it-with-a-storyboard.md b/docs/framework/wpf/graphics-multimedia/how-to-set-a-property-after-animating-it-with-a-storyboard.md index 3f91b2dc9b17d..dafe7bdf749ef 100644 --- a/docs/framework/wpf/graphics-multimedia/how-to-set-a-property-after-animating-it-with-a-storyboard.md +++ b/docs/framework/wpf/graphics-multimedia/how-to-set-a-property-after-animating-it-with-a-storyboard.md @@ -48,7 +48,7 @@ In some cases, it might appear that you can't change the value of a property aft [!code-vb[timingbehaviors_snip#GraphicsMMButton2Handler](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/timingbehaviors_snip/visualbasic/animatethensetpropertyexample.xaml.vb#graphicsmmbutton2handler)] ## Remove the entire storyboard - By using a trigger or the method, you tell the storyboard animations to stop affecting their target properties. The difference between this approach and setting the property is that you can remove the storyboard at anytime, while the property only has an effect when the animation reaches the end of its active period. + By using a trigger or the method, you tell the storyboard animations to stop affecting their target properties. The difference between this approach and setting the property is that you can remove the storyboard at anytime, while the property only has an effect when the animation reaches the end of its active period. [!code-xaml[timingbehaviors_snip#GraphicsMMButton3Declaration](../../../../samples/snippets/csharp/VS_Snippets_Wpf/timingbehaviors_snip/CSharp/AnimateThenSetPropertyExample.xaml#graphicsmmbutton3declaration)] @@ -67,7 +67,7 @@ In some cases, it might appear that you can't change the value of a property aft ## See Also - + [Animation Overview](../../../../docs/framework/wpf/graphics-multimedia/animation-overview.md) [Property Animation Techniques Overview](../../../../docs/framework/wpf/graphics-multimedia/property-animation-techniques-overview.md) diff --git a/docs/framework/wpf/graphics-multimedia/how-to-use-a-drawing-as-an-image-source.md b/docs/framework/wpf/graphics-multimedia/how-to-use-a-drawing-as-an-image-source.md index bcba600b555c7..84daff2c014eb 100644 --- a/docs/framework/wpf/graphics-multimedia/how-to-use-a-drawing-as-an-image-source.md +++ b/docs/framework/wpf/graphics-multimedia/how-to-use-a-drawing-as-an-image-source.md @@ -20,7 +20,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # How to: Use a Drawing as an Image Source -This example shows how to use a as the for an control. To display a with an control, use a as the control's and set the object's property to the drawing you want to display. +This example shows how to use a as the for an control. To display a with an control, use a as the control's and set the object's property to the drawing you want to display. ## Example The following example uses a and an control to display a . This example produces the following output: diff --git a/docs/framework/wpf/graphics-multimedia/imaging-overview.md b/docs/framework/wpf/graphics-multimedia/imaging-overview.md index e04dd0462ff55..a24ac955a1758 100644 --- a/docs/framework/wpf/graphics-multimedia/imaging-overview.md +++ b/docs/framework/wpf/graphics-multimedia/imaging-overview.md @@ -54,7 +54,7 @@ This topic provides an introduction to the [!INCLUDE[TLA#tla_wic](../../../../in - The managed component utilizes the unmanaged infrastructure to provide seamless integration of images with other [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] features such as [!INCLUDE[TLA#tla_ui](../../../../includes/tlasharptla-ui-md.md)], animation, and graphics. The managed component also benefits from the [!INCLUDE[TLA#tla_wpf](../../../../includes/tlasharptla-wpf-md.md)] imaging codec extensibility model which enables automatic recognition of new image formats in [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] applications. - The majority of the managed [!INCLUDE[TLA2#tla_wic](../../../../includes/tla2sharptla-wic-md.md)] [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] reside in the namespace, though several important types, such as and reside in the namespace and resides in the namespace. + The majority of the managed [!INCLUDE[TLA2#tla_wic](../../../../includes/tla2sharptla-wic-md.md)] [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] reside in the namespace, though several important types, such as and reside in the namespace and resides in the namespace. This topic provides additional information about the managed component. For more information on the unmanaged [!INCLUDE[TLA2#tla_api](../../../../includes/tla2sharptla-api-md.md)] see the [Unmanaged WPF Imaging Component](https://msdn.microsoft.com/library/ee719902.aspx) documentation. diff --git a/docs/framework/wpf/graphics-multimedia/opacity-masks-overview.md b/docs/framework/wpf/graphics-multimedia/opacity-masks-overview.md index c536562811c3b..1e685bd90af8c 100644 --- a/docs/framework/wpf/graphics-multimedia/opacity-masks-overview.md +++ b/docs/framework/wpf/graphics-multimedia/opacity-masks-overview.md @@ -75,7 +75,7 @@ DrawingBrush opacity masking example ## Specifying Gradient Stops for an Opacity Mask In the previous example, the system-defined color is used as the starting color of the gradient. Because all of the colors in the class, except , are fully opaque, they can be used to simply define a starting color for a gradient opacity mask. - For additional control over alpha values when defining an opacity mask, you can specify the alpha channel of colors using [!INCLUDE[TLA#tla_argb](../../../../includes/tlasharptla-argb-md.md)] hexadecimal notation in markup or using the method. + For additional control over alpha values when defining an opacity mask, you can specify the alpha channel of colors using [!INCLUDE[TLA#tla_argb](../../../../includes/tlasharptla-argb-md.md)] hexadecimal notation in markup or using the method. ### Specifying Color Opacity in "XAML" diff --git a/docs/framework/wpf/graphics-multimedia/painting-with-solid-colors-and-gradients-overview.md b/docs/framework/wpf/graphics-multimedia/painting-with-solid-colors-and-gradients-overview.md index 05de29931282d..63b2bbf7e6391 100644 --- a/docs/framework/wpf/graphics-multimedia/painting-with-solid-colors-and-gradients-overview.md +++ b/docs/framework/wpf/graphics-multimedia/painting-with-solid-colors-and-gradients-overview.md @@ -150,7 +150,7 @@ RadialGradientBrushes with different GradientOrigin, Center, RadiusX, and Radius ## Specifying Transparent or Partially-Transparent Gradient Stops - Because gradient stops do not provide an opacity property, you must specify the alpha channel of colors using [!INCLUDE[TLA#tla_argb](../../../../includes/tlasharptla-argb-md.md)] hexadecimal notation in markup or use the method to create gradient stops that are transparent or partially transparent. The following sections explain how to create partially transparent gradient stops in [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] and code. + Because gradient stops do not provide an opacity property, you must specify the alpha channel of colors using [!INCLUDE[TLA#tla_argb](../../../../includes/tlasharptla-argb-md.md)] hexadecimal notation in markup or use the method to create gradient stops that are transparent or partially transparent. The following sections explain how to create partially transparent gradient stops in [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] and code. ### Specifying Color Opacity in "XAML" diff --git a/docs/framework/wpf/graphics-multimedia/path-markup-syntax.md b/docs/framework/wpf/graphics-multimedia/path-markup-syntax.md index b3a8f7a74d329..f3f44d0584fbb 100644 --- a/docs/framework/wpf/graphics-multimedia/path-markup-syntax.md +++ b/docs/framework/wpf/graphics-multimedia/path-markup-syntax.md @@ -65,7 +65,7 @@ Paths are discussed in [Shapes and Basic Drawing in WPF Overview](. |Term|Description| |----------|-----------------| -|*fillRule*|

Specifies whether the uses the or .

- `F0` specifies the fill rule.
- `F1` specifies the fill rule.

If you omit this command, the subpath uses the default behavior, which is . If you specify this command, you must place it first.| +|*fillRule*|

Specifies whether the uses the or .

- `F0` specifies the fill rule.
- `F1` specifies the fill rule.

If you omit this command, the subpath uses the default behavior, which is . If you specify this command, you must place it first.| |*figureDescription*|A figure composed of a move command, draw commands, and an optional close command.

`moveCommand` `drawCommands` `[` `closeCommand` `]`| |*moveCommand*|A move command that specifies the start point of the figure. See the [Move Command](#themovecommand) section.| |*drawCommands*|One or more drawing commands that describe the figure's contents. See the [Draw Commands](#drawcommands) section.| @@ -81,7 +81,7 @@ Paths are discussed in [Shapes and Basic Drawing in WPF Overview](. |Term|Description| |----------|-----------------| -|*startPoint*|

The start point of a new figure.| +|*startPoint*|

The start point of a new figure.| An uppercase `M` indicates that `startPoint` is an absolute value; a lowercase `m` indicates that `startPoint` is an offset to the previous point, or (0,0) if none exists. If you list multiple points after the move command, a line is drawn to those points though you specified the line command. @@ -100,7 +100,7 @@ Paths are discussed in [Shapes and Basic Drawing in WPF Overview](. |Term|Description| |----------|-----------------| -|*endPoint*|

The end point of the line.| +|*endPoint*|

The end point of the line.| An uppercase `L` indicates that `endPoint` is an absolute value; a lowercase `l` indicates that `endPoint` is an offset to the previous point, or (0,0) if none exists. @@ -114,7 +114,7 @@ An uppercase `L` indicates that `endPoint` is |Term|Description| |----------|-----------------| -|*x*|

The x-coordinate of the end point of the line.| +|*x*|

The x-coordinate of the end point of the line.| An uppercase `H` indicates that `x` is an absolute value; a lowercase `h` indicates that `x` is an offset to the previous point, or (0,0) if none exists. @@ -128,7 +128,7 @@ An uppercase `H` indicates that `x` is an abso |Term|Description| |----------|-----------------| -|*y*|

The y-coordinate of the end point of the line.| +|*y*|

The y-coordinate of the end point of the line.| An uppercase `V` indicates that `y` is an absolute value; a lowercase `v` indicates that `y` is an offset to the previous point, or (0,0) if none exists. @@ -141,9 +141,9 @@ An uppercase `V` indicates that `y` is an abso |Term|Description| |----------|-----------------| -|`controlPoint`1|

The first control point of the curve, which determines the starting tangent of the curve.| -|`controlPoint`2|

The second control point of the curve, which determines the ending tangent of the curve.| -|`endPoint`|

The point to which the curve is drawn.| +|`controlPoint`1|

The first control point of the curve, which determines the starting tangent of the curve.| +|`controlPoint`2|

The second control point of the curve, which determines the ending tangent of the curve.| +|`endPoint`|

The point to which the curve is drawn.| ### Quadratic Bezier Curve Command Creates a quadratic Bezier curve between the current point and the specified end point by using the specified control point ( `controlPoint`). `q 100,200 300,200` is an example of a valid quadratic Bezier curve command. @@ -154,8 +154,8 @@ An uppercase `V` indicates that `y` is an abso |Term|Description| |----------|-----------------| -|`controlPoint`|

The control point of the curve, which determines the starting and ending tangents of the curve.| -|`endPoint`|

The point to which the curve is drawn.| +|`controlPoint`|

The control point of the curve, which determines the starting and ending tangents of the curve.| +|`endPoint`|

The point to which the curve is drawn.| ### Smooth cubic Bezier curve Command Creates a cubic Bezier curve between the current point and the specified end point. The first control point is assumed to be the reflection of the second control point of the previous command relative to the current point. If there is no previous command or if the previous command was not a cubic Bezier curve command or a smooth cubic Bezier curve command, assume the first control point is coincident with the current point. The second control point, the control point for the end of the curve, is specified by `controlPoint`2. For example, `S 100,200 200,300` is a valid smooth cubic Bezier curve command. @@ -166,8 +166,8 @@ An uppercase `V` indicates that `y` is an abso |Term|Description| |----------|-----------------| -|`controlPoint`2|

The control point of the curve, which determines the ending tangent of the curve.| -|`endPoint`|

The point to which the curve is drawn.| +|`controlPoint`2|

The control point of the curve, which determines the ending tangent of the curve.| +|`endPoint`|

The point to which the curve is drawn.| ### Smooth quadratic Bezier curve Command Creates a quadratic Bezier curve between the current point and the specified end point. The control point is assumed to be the reflection of the control point of the previous command relative to the current point. If there is no previous command or if the previous command was not a quadratic Bezier curve command or a smooth quadratic Bezier curve command, the control point is coincident with the current point. @@ -178,8 +178,8 @@ An uppercase `V` indicates that `y` is an abso |Term|Description| |----------|-----------------| -|`controlPoint`|

The control point of the curve, which determines the starting and tangent of the curve.| -|`endPoint`|

The point to which the curve is drawn.| +|`controlPoint`|

The control point of the curve, which determines the starting and tangent of the curve.| +|`endPoint`|

The point to which the curve is drawn.| ### Elliptical Arc Command Creates an elliptical arc between the current point and the specified end point. @@ -190,11 +190,11 @@ An uppercase `V` indicates that `y` is an abso |Term|Description| |----------|-----------------| -|`size`|

The x- and y-radius of the arc.| -|`rotationAngle`|

The rotation of the ellipse, in degrees.| +|`size`|

The x- and y-radius of the arc.| +|`rotationAngle`|

The rotation of the ellipse, in degrees.| |`isLargeArcFlag`|Set to 1 if the angle of the arc should be 180 degrees or greater; otherwise, set to 0.| |`sweepDirectionFlag`|Set to 1 if the arc is drawn in a positive-angle direction; otherwise, set to 0.| -|`endPoint`|

The point to which the arc is drawn.| +|`endPoint`|

The point to which the arc is drawn.| ## The Close Command @@ -214,21 +214,21 @@ An uppercase `V` indicates that `y` is an abso |Term|Description| |----------|-----------------| -|`x`|

The x-coordinate of the point.| -|`y`|

The y-coordinate of the point.| +|`x`|

The x-coordinate of the point.| +|`y`|

The y-coordinate of the point.| ## Special Values Instead of a standard numerical value, you can also use the following special values. These values are case-sensitive. Infinity - Represents . + Represents . -Infinity - Represents . + Represents . NaN - Represents . + Represents . You may also use scientific notation. For example, `+1.e17` is a valid value. diff --git a/docs/framework/wpf/graphics-multimedia/storyboards-overview.md b/docs/framework/wpf/graphics-multimedia/storyboards-overview.md index 8064d1588b394..f3f3c4927b828 100644 --- a/docs/framework/wpf/graphics-multimedia/storyboards-overview.md +++ b/docs/framework/wpf/graphics-multimedia/storyboards-overview.md @@ -56,7 +56,7 @@ This topic shows how to use ## How to Apply Animations with a Storyboard - To use a to organize and apply animations, you add the animations as child timelines of the . The class provides the and attached properties. You set these properties on an animation to specify its target object and property. + To use a to organize and apply animations, you add the animations as child timelines of the . The class provides the and attached properties. You set these properties on an animation to specify its target object and property. To apply animations to their targets, you begin the using a trigger action or a method. In [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)], you use a object with an , , or . In code, you can also use the method. @@ -79,7 +79,7 @@ This topic shows how to use ## Targeting Framework Elements, Framework Content Elements, and Freezables - The previous section mentioned that, for an animation to find its target, it must know the target's name and the property to animate. Specifying the property to animate is straight forward: simply set with the name of the property to animate. You specify the name of the object whose property you want to animate by setting the property on the animation. + The previous section mentioned that, for an animation to find its target, it must know the target's name and the property to animate. Specifying the property to animate is straight forward: simply set with the name of the property to animate. You specify the name of the object whose property you want to animate by setting the property on the animation. For the property to work, the targeted object must have a name. Assigning a name to a or a in [!INCLUDE[TLA2#tla_xaml](../../../../includes/tla2sharptla-xaml-md.md)] is different than assigning a name to a object. diff --git a/docs/framework/wpf/graphics-multimedia/wpf-brushes-overview.md b/docs/framework/wpf/graphics-multimedia/wpf-brushes-overview.md index a44a8382ab57c..97ac31097125e 100644 --- a/docs/framework/wpf/graphics-multimedia/wpf-brushes-overview.md +++ b/docs/framework/wpf/graphics-multimedia/wpf-brushes-overview.md @@ -149,7 +149,7 @@ A Rectangle painted using a VisualBrush If the brush contains colors that are partially transparent, the opacity value of the color is combined through multiplication with the opacity value of the brush. For example, if a brush has an opacity value of 0.5 and a color used in the brush also has an opacity value of 0.5, the output color has an opacity value of 0.25. > [!NOTE] -> It's more efficient to change the opacity value of a brush than it is to change the opacity of an entire element using its property. +> It's more efficient to change the opacity value of a brush than it is to change the opacity of an entire element using its property. You can rotate, scale, skew, and translate a brush's content by using its or properties. For more information, see [Brush Transformation Overview](../../../../docs/framework/wpf/graphics-multimedia/brush-transformation-overview.md). diff --git a/docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md b/docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md index b0c819bbc823b..6396f3578105d 100644 --- a/docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md +++ b/docs/framework/wpf/graphics-multimedia/wpf-graphics-rendering-overview.md @@ -88,7 +88,7 @@ Order of DrawingGroup operations For more information, see [Drawing Objects Overview](../../../../docs/framework/wpf/graphics-multimedia/drawing-objects-overview.md). #### Drawing Content at the Visual Layer - You never directly instantiate a ; you can, however, acquire a drawing context from certain methods, such as and . The following example retrieves a from a and uses it to draw a rectangle. + You never directly instantiate a ; you can, however, acquire a drawing context from certain methods, such as and . The following example retrieves a from a and uses it to draw a rectangle. [!code-csharp[drawingvisualsample#101](../../../../samples/snippets/csharp/VS_Snippets_Wpf/DrawingVisualSample/CSharp/Window1.xaml.cs#101)] [!code-vb[drawingvisualsample#101](../../../../samples/snippets/visualbasic/VS_Snippets_Wpf/DrawingVisualSample/visualbasic/window1.xaml.vb#101)] diff --git a/docs/framework/wpf/security-wpf.md b/docs/framework/wpf/security-wpf.md index ef9af8039a7df..f96361279081e 100644 --- a/docs/framework/wpf/security-wpf.md +++ b/docs/framework/wpf/security-wpf.md @@ -77,7 +77,7 @@ manager: "wpickett" - **User Navigation**. The user navigates by clicking a element. -- **Programmatic Navigation**. The application navigates without involving the user, for example, by setting the property. +- **Programmatic Navigation**. The application navigates without involving the user, for example, by setting the property. ### Browser Navigation Security diff --git a/docs/framework/wpf/wpf-partial-trust-security.md b/docs/framework/wpf/wpf-partial-trust-security.md index 8ac6e55cbd35d..6a85281e823f8 100644 --- a/docs/framework/wpf/wpf-partial-trust-security.md +++ b/docs/framework/wpf/wpf-partial-trust-security.md @@ -57,17 +57,17 @@ manager: "wpickett" - [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] (see [XAML Overview (WPF)](../../../docs/framework/wpf/advanced/xaml-overview-wpf.md)). -- Popups (see ). +- Popups (see ). - Drag and Drop (see [Drag and Drop Overview](../../../docs/framework/wpf/advanced/drag-and-drop-overview.md)). -- Clipboard (see ). +- Clipboard (see ). -- Imaging (see ). +- Imaging (see ). -- Serialization (see , ). +- Serialization (see , ). -- Open File Dialog Box (see ). +- Open File Dialog Box (see ). The following table outlines the [!INCLUDE[TLA2#tla_wpf](../../../includes/tla2sharptla-wpf-md.md)] features that are not safe to run within the limits of the Internet zone permission set. @@ -120,7 +120,7 @@ manager: "wpickett" ### Browser Host Detection - Using [!INCLUDE[TLA2#tla_cas](../../../includes/tla2sharptla-cas-md.md)] to check for permissions is a suitable technique when you need to check on a per-permission basis. Although, this technique depends on catching exceptions as a part of normal processing, which is not recommended in general and can have performance issues. Instead, if your [!INCLUDE[TLA#tla_xbap](../../../includes/tlasharptla-xbap-md.md)] only runs within the Internet zone sandbox, you can use the property, which returns true for [!INCLUDE[TLA#tla_xbap#plural](../../../includes/tlasharptla-xbapsharpplural-md.md)]. + Using [!INCLUDE[TLA2#tla_cas](../../../includes/tla2sharptla-cas-md.md)] to check for permissions is a suitable technique when you need to check on a per-permission basis. Although, this technique depends on catching exceptions as a part of normal processing, which is not recommended in general and can have performance issues. Instead, if your [!INCLUDE[TLA#tla_xbap](../../../includes/tlasharptla-xbap-md.md)] only runs within the Internet zone sandbox, you can use the property, which returns true for [!INCLUDE[TLA#tla_xbap#plural](../../../includes/tlasharptla-xbapsharpplural-md.md)]. > [!NOTE] > only distinguishes whether an application is running in a browser, not which set of permissions an application is running with. diff --git a/docs/framework/xaml-services/built-in-types-for-common-xaml-language-primitives.md b/docs/framework/xaml-services/built-in-types-for-common-xaml-language-primitives.md index b66ad91ff5edb..8dfeb7d041808 100644 --- a/docs/framework/xaml-services/built-in-types-for-common-xaml-language-primitives.md +++ b/docs/framework/xaml-services/built-in-types-for-common-xaml-language-primitives.md @@ -139,4 +139,4 @@ xmlns:sys="clr-namespace:System;assembly=mscorlib"> ## WPF Support In WPF, you can use XAML 2009 features but only for XAML that is not markup-compiled. Markup-compiled XAML for WPF and the BAML form of XAML do not currently support the XAML 2009 keywords and features. - A scenario where you can use XAML 2009 features together with WPF is if you author loose XAML and you then load that XAML into a WPF runtime and object graph with . The WPF and its can process XAML 2009 language keywords and features into a valid object graph representation. + A scenario where you can use XAML 2009 features together with WPF is if you author loose XAML and you then load that XAML into a WPF runtime and object graph with . The WPF and its can process XAML 2009 language keywords and features into a valid object graph representation. diff --git a/docs/framework/xaml-services/default-xaml-schema-context-and-wpf-xaml-schema-context.md b/docs/framework/xaml-services/default-xaml-schema-context-and-wpf-xaml-schema-context.md index 667f6ded436dd..bce3567e64e9e 100644 --- a/docs/framework/xaml-services/default-xaml-schema-context-and-wpf-xaml-schema-context.md +++ b/docs/framework/xaml-services/default-xaml-schema-context-and-wpf-xaml-schema-context.md @@ -39,9 +39,9 @@ A XAML schema context is a conceptual entity that qualifies how a XAML productio **XamlType and XamlMember extension:** WPF extends property concepts with dependency properties, and event concepts with routed events. To give these concepts greater visibility for XAML processing operations, WPF extends and , and adds internal properties that report dependency property and routed event characteristics. ### Accessing the WPF XAML Schema Context - If you are using XAML techniques that are based on the WPF or , the WPF XAML schema context is already in use on those XAML reader and XAML writer implementations. + If you are using XAML techniques that are based on the WPF or , the WPF XAML schema context is already in use on those XAML reader and XAML writer implementations. - If you are using other XAML reader or XAML writer implementations that do not initialize with the WPF XAML schema context, you may be able to get a working WPF XAML schema context from . You can then use this value as initialization for other API that use a . For example, you could call for initialization and pass the WPF XAML schema context. Or you could use the WPF XAML schema context for XAML type system operations. This might include construction initialization of a or , or calling . + If you are using other XAML reader or XAML writer implementations that do not initialize with the WPF XAML schema context, you may be able to get a working WPF XAML schema context from . You can then use this value as initialization for other API that use a . For example, you could call for initialization and pass the WPF XAML schema context. Or you could use the WPF XAML schema context for XAML type system operations. This might include construction initialization of a or , or calling . Note that if you access certain aspects of WPF XAML from a pure XAML node stream perspectives, some of the WPF framework capabilities may not have acted yet. For example, WPF templates for controls are not yet applied. Thus if you access a property that at run time might be populated with a full visual tree, you might only see a property value that references a template. The service context provided for WPF markup extensions might also not be accurate if provided from a non-runtime situation, and can result in exceptions when attempting to write an object graph. @@ -56,20 +56,20 @@ A XAML schema context is a conceptual entity that qualifies how a XAML productio 2. Otherwise, one of the following techniques based on CLR API are used to load an assembly: - - If the name is qualified in the mapping, call on the qualified name. + - If the name is qualified in the mapping, call on the qualified name. - - If the previous step fails, use the short name (and public key token if present) to call . + - If the previous step fails, use the short name (and public key token if present) to call . - - If the name is unqualified in the mapping, call . + - If the name is unqualified in the mapping, call . #### XamlBuildTask `XamlBuildTask` is used for [!INCLUDE[vsindigo](../../../includes/vsindigo-md.md)] and [!INCLUDE[TLA#tla_workflow](../../../includes/tlasharptla-workflow-md.md)]. Note that assembly references through `XamlBuildTask` are always fully qualified. -1. Call on the qualified name. +1. Call on the qualified name. -2. If the previous step fails, use the short name (and public key token if present) to call . +2. If the previous step fails, use the short name (and public key token if present) to call . #### BAML (PresentationBuildTask) There are two aspects to assembly-loading for BAML: loading the initial assembly that contains the BAML as a component, and loading the type-backing assemblies for any types referenced by the BAML production. @@ -79,7 +79,7 @@ A XAML schema context is a conceptual entity that qualifies how a XAML productio 1. The WPF XAML schema context iterates through the of the WPF application, looking for an already-loaded assembly that matches all aspects of the name, starting from the most recently loaded assembly. If a match is found, that assembly is used for resolution. -2. If the previous step fails, use the short name (and public key token if present) to call . +2. If the previous step fails, use the short name (and public key token if present) to call . ##### Assembly references by BAML types: Assembly references for types used in the BAML production are always fully qualified, as an output of the build task. @@ -88,11 +88,11 @@ A XAML schema context is a conceptual entity that qualifies how a XAML productio 2. Otherwise, one of the following techniques is used to load an assembly: - - Call on the qualified name. + - Call on the qualified name. - If a short name + public key token combination match the assembly that the BAML was loaded from, use that assembly. - - Use short name + public key token to call . + - Use short name + public key token to call . ## See Also [Understanding XAML Node Stream Structures and Concepts](../../../docs/framework/xaml-services/understanding-xaml-node-stream-structures-and-concepts.md) diff --git a/docs/framework/xaml-services/defining-custom-types-for-use-with-net-framework-xaml-services.md b/docs/framework/xaml-services/defining-custom-types-for-use-with-net-framework-xaml-services.md index 2c8d21c628cb6..e10d7c044e9c5 100644 --- a/docs/framework/xaml-services/defining-custom-types-for-use-with-net-framework-xaml-services.md +++ b/docs/framework/xaml-services/defining-custom-types-for-use-with-net-framework-xaml-services.md @@ -116,7 +116,7 @@ When you define custom types that are business objects or are types that do not For an application that loads XAML under partial trust, you can control the access level characteristics by using the API. Also, deferral mechanisms (such as the WPF template system) must be able to propagate any access level permissions and preserve them for the eventual run time evaluations; this is handled internally by passing the information. ### WPF Implementation - WPF XAML uses a partial-trust access model where if BAML is loaded under partial trust, access is restricted to for the assembly that is the BAML source. For deferral, WPF uses as a mechanism for passing the access level information. + WPF XAML uses a partial-trust access model where if BAML is loaded under partial trust, access is restricted to for the assembly that is the BAML source. For deferral, WPF uses as a mechanism for passing the access level information. In WPF XAML terminology, an *internal type* is a type that is defined by the same assembly that also includes the referencing XAML. Such a type can be mapped through a XAML namespace that deliberately omits the assembly= portion of a mapping, for example, `xmlns:local="clr-namespace:WPFApplication1"`. If BAML references an internal type and that type has `internal` access level, this generates a `GeneratedInternalTypeHelper` class for the assembly. If you want to avoid `GeneratedInternalTypeHelper`, you either must use `public` access level, or must factor the relevant class into a separate assembly and make that assembly dependent. diff --git a/docs/framework/xaml-services/generics-in-xaml.md b/docs/framework/xaml-services/generics-in-xaml.md index 7f8459f565577..f5afcbc9d1c9b 100644 --- a/docs/framework/xaml-services/generics-in-xaml.md +++ b/docs/framework/xaml-services/generics-in-xaml.md @@ -25,7 +25,7 @@ The .NET Framework XAML Services as implemented in System.Xaml provides support Because `x:TypeArguments` takes a string, and has type converter backing, it is typically declared in XAML usage as an attribute. - In the XAML node stream, the information declared by `x:TypeArguments` can be obtained from at a `StartObject` position in the node stream. The return value of is a list of values. Determination of whether a XAML type represents a generic type can be made by calling . + In the XAML node stream, the information declared by `x:TypeArguments` can be obtained from at a `StartObject` position in the node stream. The return value of is a list of values. Determination of whether a XAML type represents a generic type can be made by calling . ## Rules and Syntax Conventions for Generics in XAML In XAML, a generic type must always be represented as a constrained generic; an unconstrained generic is never present in the XAML type system or a XAML node stream and cannot be represented in XAML markup. A generic can be referenced within XAML attribute syntax, for cases where it is a nested type constraint of a generic being referenced by `x:TypeArguments`, or for cases where `x:Type` supplies a CLR type reference for a generic type. This is supported through the class defined by .NET Framework XAML Services. diff --git a/docs/framework/xaml-services/markup-extensions-for-xaml-overview.md b/docs/framework/xaml-services/markup-extensions-for-xaml-overview.md index 4b99cfaf65fd8..6368ec8af431f 100644 --- a/docs/framework/xaml-services/markup-extensions-for-xaml-overview.md +++ b/docs/framework/xaml-services/markup-extensions-for-xaml-overview.md @@ -21,7 +21,7 @@ manager: "wpickett" # Markup Extensions for XAML Overview Markup extensions are a XAML technique for obtaining a value that is neither a primitive nor a specific XAML type. For attribute usage, markup extensions use the known character sequence of an opening curly brace `{` to enter the markup extension scope, and a closing curly brace `}` to exit. When using .NET Framework XAML Services, you can use some of the predefined XAML language markup extensions from the System.Xaml assembly. You can also subclass from the class, defined in System.Xaml, and define your own markup extensions. Or you can use markup extensions defined by a particular framework if you are already referencing that framework . - When a markup extension usage is accessed, the XAML object writer can provide services to a custom class through a service connection point in the override. The services can be used to obtain context about the usage, specific capabilities of the object writer, XAML schema context, and so on. + When a markup extension usage is accessed, the XAML object writer can provide services to a custom class through a service connection point in the override. The services can be used to obtain context about the usage, specific capabilities of the object writer, XAML schema context, and so on. ## XAML-Defined Markup Extensions diff --git a/docs/framework/xaml-services/service-contexts-available-to-type-converters-and-markup-extensions.md b/docs/framework/xaml-services/service-contexts-available-to-type-converters-and-markup-extensions.md index a4cdf2a91d690..f5abc84c21490 100644 --- a/docs/framework/xaml-services/service-contexts-available-to-type-converters-and-markup-extensions.md +++ b/docs/framework/xaml-services/service-contexts-available-to-type-converters-and-markup-extensions.md @@ -22,7 +22,7 @@ Authors of the types that support type converter and markup extension usages mus ## Obtaining Services - As an implementer of a value converter, you often need access to some type of context in which the value converter is applied. This context might include information such as the active XAML schema context, access to the type mapping system that the XAML schema context and XAML object writer provide, and so on. The services available for a markup extension or type converter implementation are communicated through the context parameters that are part of the signature of each virtual method. In every case, you have implemented in the context, and can call to request a service. + As an implementer of a value converter, you often need access to some type of context in which the value converter is applied. This context might include information such as the active XAML schema context, access to the type mapping system that the XAML schema context and XAML object writer provide, and so on. The services available for a markup extension or type converter implementation are communicated through the context parameters that are part of the signature of each virtual method. In every case, you have implemented in the context, and can call to request a service. ## Services for a Markup Extension @@ -81,7 +81,7 @@ public override object ConvertFrom(ITypeDescriptorContext typeDescriptorContext, ### IServiceProvider **Reference documentation**: - **Relevant to:** Basic operation of a service-based infrastructure in the .NET Framework so that you can call . + **Relevant to:** Basic operation of a service-based infrastructure in the .NET Framework so that you can call . ### ITypeDescriptorContext **Reference documentation**: @@ -102,7 +102,7 @@ public override object ConvertFrom(ITypeDescriptorContext typeDescriptorContext, **Service API:** - Can influence the XAML-to-CLR type mapping that is necessary when the XAML writer constructs a CLR object in an object graph. processes a potentially prefix-qualified string that corresponds to a XAML type name (), and returns a CLR . Resolving types is typically heavily dependent on XAML schema context. Only the XAML schema context is aware of considerations such as which assemblies are loaded, and which of these assemblies can or should be accessed for type resolution. + Can influence the XAML-to-CLR type mapping that is necessary when the XAML writer constructs a CLR object in an object graph. processes a potentially prefix-qualified string that corresponds to a XAML type name (), and returns a CLR . Resolving types is typically heavily dependent on XAML schema context. Only the XAML schema context is aware of considerations such as which assemblies are loaded, and which of these assemblies can or should be accessed for type resolution. ### IUriContext **Reference documentation**: diff --git a/docs/framework/xaml-services/type-converters-and-markup-extensions-for-xaml.md b/docs/framework/xaml-services/type-converters-and-markup-extensions-for-xaml.md index be2f19d2a6370..29964d439cec3 100644 --- a/docs/framework/xaml-services/type-converters-and-markup-extensions-for-xaml.md +++ b/docs/framework/xaml-services/type-converters-and-markup-extensions-for-xaml.md @@ -57,7 +57,7 @@ Type converters and markup extensions are two techniques that XAML type systems ## Value Serializers A is a specialized type converter that is optimized for converting an object to a string. A for XAML might not implement the `ConvertFrom` method at all. A implementation obtains services in a manner that is like a implementation. The virtual methods provide an input `context` parameter. The `context` parameter is of type , which inherits from the interface and has a method. - In the XAML type system and for XAML writer implementations that use XAML node loop processing for serialization, a value converter that is associated with a type or member is reported by its own property. The meaning to XAML writers that perform serialization is that if a and exist, the type converter should be used for the load path and the value serializer should be used for the save path. If exists but is `null`, the type converter is also used for the save path. + In the XAML type system and for XAML writer implementations that use XAML node loop processing for serialization, a value converter that is associated with a type or member is reported by its own property. The meaning to XAML writers that perform serialization is that if a and exist, the type converter should be used for the load path and the value serializer should be used for the save path. If exists but is `null`, the type converter is also used for the save path. ## Other Value Converters diff --git a/docs/framework/xaml-services/type-converters-for-xaml-overview.md b/docs/framework/xaml-services/type-converters-for-xaml-overview.md index 3dcccf01703ea..d760ba174edb3 100644 --- a/docs/framework/xaml-services/type-converters-for-xaml-overview.md +++ b/docs/framework/xaml-services/type-converters-for-xaml-overview.md @@ -111,7 +111,7 @@ Type converters supply logic for an object writer that converts from a string in ## Type Converters in the XAML Node Stream - If you are working with a XAML node stream, the action or end result of a type converter is not yet executed. In a load path, the attribute string that eventually needs to be type-converted in order to load remains as a text value within a start member and end member. The type converter that is eventually needed for this operation can be determined by using the property. However, obtaining a valid value from relies on having a XAML schema context, which can access such information through the underlying member, or the type of the object value that the member uses. Invoking the type conversion behavior also requires the XAML schema context because that requires type-mapping and creating a converter instance. + If you are working with a XAML node stream, the action or end result of a type converter is not yet executed. In a load path, the attribute string that eventually needs to be type-converted in order to load remains as a text value within a start member and end member. The type converter that is eventually needed for this operation can be determined by using the property. However, obtaining a valid value from relies on having a XAML schema context, which can access such information through the underlying member, or the type of the object value that the member uses. Invoking the type conversion behavior also requires the XAML schema context because that requires type-mapping and creating a converter instance. ## See Also diff --git a/docs/framework/xaml-services/types-migrated-from-wpf-to-system-xaml.md b/docs/framework/xaml-services/types-migrated-from-wpf-to-system-xaml.md index c7e61d3ed6329..4134095680a37 100644 --- a/docs/framework/xaml-services/types-migrated-from-wpf-to-system-xaml.md +++ b/docs/framework/xaml-services/types-migrated-from-wpf-to-system-xaml.md @@ -127,7 +127,7 @@ In [!INCLUDE[net_v35_long](../../../includes/net-v35-long-md.md)] and [!INCLUDE[ `XamlParseException` - The WPF implementation is found in the namespace, and PresentationFramework assembly. The System.Xaml implementation is found in the namespace. If you are using WPF types or are deriving from WPF types, you should typically use the WPF implementations of and instead of the System.Xaml implementations. For more information, see Remarks in and . + The WPF implementation is found in the namespace, and PresentationFramework assembly. The System.Xaml implementation is found in the namespace. If you are using WPF types or are deriving from WPF types, you should typically use the WPF implementations of and instead of the System.Xaml implementations. For more information, see Remarks in and . If you are including references to both WPF assemblies and System.Xaml, and you also are using `include` statements for both the and namespaces, you may need to fully qualify the calls to these APIs in order to resolve the types without ambiguity. diff --git a/docs/framework/xaml-services/understanding-xaml-node-stream-structures-and-concepts.md b/docs/framework/xaml-services/understanding-xaml-node-stream-structures-and-concepts.md index 5f89465924ade..e340332d14f37 100644 --- a/docs/framework/xaml-services/understanding-xaml-node-stream-structures-and-concepts.md +++ b/docs/framework/xaml-services/understanding-xaml-node-stream-structures-and-concepts.md @@ -70,7 +70,7 @@ while (xxr.Read()) { } ``` - This basic example of a load path XAML node loop transparently connects the XAML reader and XAML writer, doing nothing different than if you had used . But this basic structure is then expanded to apply to your reading or writing scenario. Some possible scenarios are as follows: + This basic example of a load path XAML node loop transparently connects the XAML reader and XAML writer, doing nothing different than if you had used . But this basic structure is then expanded to apply to your reading or writing scenario. Some possible scenarios are as follows: - Switch on . Perform different actions depending on which node type is being read. @@ -179,7 +179,7 @@ public class GameBoard { `EndObject` matches `GameBoard` - Notice that there is no type converter instance in this node stream. But you can get type converter information by calling on the for `BoardSize`. If you have a valid XAML schema context, you can also invoke the converter methods by obtaining an instance from . + Notice that there is no type converter instance in this node stream. But you can get type converter information by calling on the for `BoardSize`. If you have a valid XAML schema context, you can also invoke the converter methods by obtaining an instance from . ### Markup Extensions in the XAML Node Stream A markup extension usage is reported in the XAML node stream as an object node within a member, where the object represents a markup extension instance. Thus a markup extension usage is presented more explicitly in the node stream representation than a type converter usage is, and carries more information. information could not have told you anything about the markup extension, because the usage is situational and varies in each possible markup case; it is not dedicated and implicit per type or member as is the case with type converters. diff --git a/docs/framework/xaml-services/x-array-markup-extension.md b/docs/framework/xaml-services/x-array-markup-extension.md index 115d73931ee18..434bc6742d3eb 100644 --- a/docs/framework/xaml-services/x-array-markup-extension.md +++ b/docs/framework/xaml-services/x-array-markup-extension.md @@ -44,7 +44,7 @@ Provides general support for arrays of objects in XAML through a markup extensio In the .NET Framework XAML Services implementation, the relationship between the input XAML type and the output CLR of the created array is influenced by service context for markup extensions. The output is the of the input XAML type, after looking up the necessary based on XAML schema context and the service the context provides. - When processed, the array contents are assigned to the `ArrayExtension.Items` intrinsic property. In the implementation, this is represented by . + When processed, the array contents are assigned to the `ArrayExtension.Items` intrinsic property. In the implementation, this is represented by . In the .NET Framework XAML Services implementation, the handling for this markup extension is defined by the class. is not sealed, and could be used as the basis for a markup extension implementation for a custom array type. diff --git a/docs/framework/xaml-services/x-class-directive.md b/docs/framework/xaml-services/x-class-directive.md index 707fdd83543ee..1c9f93cada95a 100644 --- a/docs/framework/xaml-services/x-class-directive.md +++ b/docs/framework/xaml-services/x-class-directive.md @@ -49,7 +49,7 @@ Configures XAML markup compilation to join partial classes between markup and co In existing programming models that use `x:Class`, `x:Class` is optional in the sense that it is entirely valid to have a XAML page that has no code-behind. However, that capability interacts with the build actions as implemented by frameworks that use XAML. `x:Class` capability is also influenced by the roles that various classifications of XAML-specified content have in an application model and in the corresponding build actions. If your XAML declares event-handling attribute values or instantiates custom elements where the defining classes are in the code-behind class, you have to provide the `x:Class` directive reference (or [x:Subclass](../../../docs/framework/xaml-services/x-subclass-directive.md)) to the appropriate class for code-behind. - The value of the `x:Class` directive must be a string that specifies the fully qualified name of a class but without any assembly information (equivalent to the ). For simple applications, you can omit CLR namespace information if the code-behind is also structured in that manner (code definition starts at the class level). + The value of the `x:Class` directive must be a string that specifies the fully qualified name of a class but without any assembly information (equivalent to the ). For simple applications, you can omit CLR namespace information if the code-behind is also structured in that manner (code definition starts at the class level). The code-behind file for a page or application definition must be within a code file that is included as part of the project that produces a compiled application and involves markup compilation. You must follow name rules for CLR classes. For more information, see [Framework Design Guidelines](../../../docs/standard/design-guidelines/index.md). By default, the code-behind class must be `public`; however, you can define it at a different access level by using the [x:ClassModifier Directive](../../../docs/framework/xaml-services/x-classmodifier-directive.md). diff --git a/docs/framework/xaml-services/x-classmodifier-directive.md b/docs/framework/xaml-services/x-classmodifier-directive.md index 1bc3b977cae3d..d61f2dd0a2328 100644 --- a/docs/framework/xaml-services/x-classmodifier-directive.md +++ b/docs/framework/xaml-services/x-classmodifier-directive.md @@ -38,23 +38,23 @@ Modifies XAML compilation behavior when `x:Class` is also provided. Specifically ||| |-|-| -|*NotPublic*|The exact string to pass to specify versus varies, depending on the code-behind programming language that you use. See Remarks.| +|*NotPublic*|The exact string to pass to specify versus varies, depending on the code-behind programming language that you use. See Remarks.| ## Dependencies [x:Class](../../../docs/framework/xaml-services/x-class-directive.md) must also be provided on the same element, and that element must be the root element in a page. For more information, see [\[MS-XAML\] Section 4.3.1.8](http://go.microsoft.com/fwlink/?LinkId=114525). ## Remarks - The value of `x:ClassModifier` in .NET Framework XAML Services usage varies by programming language. The string to use depends on how each language implements its and the type converters it returns to define the meanings for and , and whether that language is case sensitive. + The value of `x:ClassModifier` in .NET Framework XAML Services usage varies by programming language. The string to use depends on how each language implements its and the type converters it returns to define the meanings for and , and whether that language is case sensitive. -- For [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], the string to pass to designate is `internal`. +- For [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], the string to pass to designate is `internal`. -- For [!INCLUDE[TLA2#tla_visualbnet](../../../includes/tla2sharptla-visualbnet-md.md)], the string to pass to designate is `Friend`. +- For [!INCLUDE[TLA2#tla_visualbnet](../../../includes/tla2sharptla-visualbnet-md.md)], the string to pass to designate is `Friend`. - For [!INCLUDE[TLA2#tla_cppcli](../../../includes/tla2sharptla-cppcli-md.md)], no targets exist that support compiling XAML; therefore, the value to pass is unspecified. - You can also specify (`public` in [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], `Public` in [!INCLUDE[TLA2#tla_visualb](../../../includes/tla2sharptla-visualb-md.md)]); however, specifying is infrequently done because is already the default behavior. + You can also specify (`public` in [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], `Public` in [!INCLUDE[TLA2#tla_visualb](../../../includes/tla2sharptla-visualb-md.md)]); however, specifying is infrequently done because is already the default behavior. - Other values with equivalent user code access-level restrictions, such as `private` in [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], are not relevant for `x:ClassModifier` because nested class references are not supported in XAML, and therefore, the modifier has the same effect. + Other values with equivalent user code access-level restrictions, such as `private` in [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], are not relevant for `x:ClassModifier` because nested class references are not supported in XAML, and therefore, the modifier has the same effect. ## Security Notes The access level as declared in `x:ClassModifier` is still subject to interpretation by particular frameworks and their capabilities. WPF includes capabilities to load and instantiate types where `x:ClassModifier` is `internal`, if that class is referenced from a WPF resource through a pack URI reference. As a consequence of this case and potentially others like it implemented by other frameworks, do not rely exclusively on `x:ClassModifier` to block all possible instantiation attempts. diff --git a/docs/framework/xaml-services/x-fieldmodifier-directive.md b/docs/framework/xaml-services/x-fieldmodifier-directive.md index 1c439a116d9be..baa033a64772f 100644 --- a/docs/framework/xaml-services/x-fieldmodifier-directive.md +++ b/docs/framework/xaml-services/x-fieldmodifier-directive.md @@ -20,7 +20,7 @@ ms.author: "wpickett" manager: "wpickett" --- # x:FieldModifier Directive -Modifies XAML compilation behavior so that fields for named object references are defined with access instead of the default behavior. +Modifies XAML compilation behavior so that fields for named object references are defined with access instead of the default behavior. ## XAML Attribute Usage @@ -32,7 +32,7 @@ Modifies XAML compilation behavior so that fields for named object references ar ||| |-|-| -|*Public*|The exact string you pass to specify versus varies, depending on the code-behind programming language that is used. See Remarks.| +|*Public*|The exact string you pass to specify versus varies, depending on the code-behind programming language that is used. See Remarks.| ## Dependencies If a XAML production uses `x:FieldModifier` anywhere, the root element of that XAML production must declare an [x:Class Directive](../../../docs/framework/xaml-services/x-class-directive.md). @@ -40,17 +40,17 @@ Modifies XAML compilation behavior so that fields for named object references ar ## Remarks `x:FieldModifier` is not relevant for declaring the general access level of a class or its members. It is relevant only for XAML-processing behavior when a particular XAML object that is part of a XAML production is processed, and becomes an object that is potentially accessible in the object graph of an application. By default, the field reference for such an object is kept private, which prevents control consumers from modifying the object graph directly. Instead, control consumers are expected to modify the object graph by using standard patterns that are enabled by programming models, such as by obtaining the layout root, the child element collections, the dedicated public properties, and so on. - The value for the `x:FieldModifier` attribute varies by programming language, and its purpose can vary in specific frameworks. The string to use depends on how each language implements its and the type converters it returns to define the meanings for and , and whether that language is case sensitive. + The value for the `x:FieldModifier` attribute varies by programming language, and its purpose can vary in specific frameworks. The string to use depends on how each language implements its and the type converters it returns to define the meanings for and , and whether that language is case sensitive. -- For [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], the string to pass to designate is `public`. +- For [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], the string to pass to designate is `public`. -- For [!INCLUDE[TLA2#tla_visualbnet](../../../includes/tla2sharptla-visualbnet-md.md)], the string to pass to designate is `Public`. +- For [!INCLUDE[TLA2#tla_visualbnet](../../../includes/tla2sharptla-visualbnet-md.md)], the string to pass to designate is `Public`. - For [!INCLUDE[TLA2#tla_cppcli](../../../includes/tla2sharptla-cppcli-md.md)], no targets for XAML currently exist; therefore, the string to pass is undefined. - You can also specify (`internal` in [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], `Friend` in [!INCLUDE[TLA2#tla_visualb](../../../includes/tla2sharptla-visualb-md.md)]) but specifying is unusual because `NotPublic` as the behavior is already the default. + You can also specify (`internal` in [!INCLUDE[TLA2#tla_cshrp](../../../includes/tla2sharptla-cshrp-md.md)], `Friend` in [!INCLUDE[TLA2#tla_visualb](../../../includes/tla2sharptla-visualb-md.md)]) but specifying is unusual because `NotPublic` as the behavior is already the default. - is the default behavior because it is infrequent that code outside the assembly that compiled the XAML needs access to a XAML-created element. WPF security architecture together with XAML compilation behavior will not declare fields that store element instances as public, unless you specifically set the `x:FieldModifier` to allow public access. + is the default behavior because it is infrequent that code outside the assembly that compiled the XAML needs access to a XAML-created element. WPF security architecture together with XAML compilation behavior will not declare fields that store element instances as public, unless you specifically set the `x:FieldModifier` to allow public access. `x:FieldModifier` is only relevant for elements with an [x:Name Directive](../../../docs/framework/xaml-services/x-name-directive.md) because that name is used to reference the field after it is public. diff --git a/docs/framework/xaml-services/x-key-directive.md b/docs/framework/xaml-services/x-key-directive.md index e6b77d9537655..9b5fd5158baf3 100644 --- a/docs/framework/xaml-services/x-key-directive.md +++ b/docs/framework/xaml-services/x-key-directive.md @@ -62,7 +62,7 @@ Uniquely identifies elements that are created and referenced in a XAML-defined d Child elements of a parent element that is an implementation must typically include an `x:Key` attribute that specifies a unique key value within that dictionary. Frameworks might implement aliased key properties to substitute for `x:Key` on particular types; types that define such properties should be attributed with . - The code equivalent of specifying `x:Key` is the key that is used for the underlying . For example, an `x:Key` that is applied in markup for a resource in WPF is equivalent to the value of the `key` parameter of when you add the resource to a WPF in code. + The code equivalent of specifying `x:Key` is the key that is used for the underlying . For example, an `x:Key` that is applied in markup for a resource in WPF is equivalent to the value of the `key` parameter of when you add the resource to a WPF in code. ## WPF Usage Notes Child objects of a parent object that is an implementation, such as the WPF , must typically include an `x:Key` attribute, and the key value must be unique within that dictionary. There are two notable exceptions: diff --git a/docs/framework/xaml-services/x-name-directive.md b/docs/framework/xaml-services/x-name-directive.md index 25be83fe84dd2..cd5a8f49677a5 100644 --- a/docs/framework/xaml-services/x-name-directive.md +++ b/docs/framework/xaml-services/x-name-directive.md @@ -73,6 +73,6 @@ Uniquely identifies XAML-defined elements in a XAML namescope. XAML namescopes a `x:Name` for Silverlight is documented separately. For more information, see [XAML Namespace (x:) Language Features (Silverlight)](http://go.microsoft.com/fwlink/?LinkId=199081). ## See Also - - + + [Trees in WPF](../../../docs/framework/wpf/advanced/trees-in-wpf.md) diff --git a/docs/framework/xaml-services/x-type-markup-extension.md b/docs/framework/xaml-services/x-type-markup-extension.md index d32c15eb4d0da..881b6213835e5 100644 --- a/docs/framework/xaml-services/x-type-markup-extension.md +++ b/docs/framework/xaml-services/x-type-markup-extension.md @@ -70,7 +70,7 @@ Supplies the CLR object that is the underlying type for a spe The default XAML namespace for WPF programming contains most of the XAML types you need for typical XAML scenarios; therefore, you can often avoid prefixes when referencing XAML type values. You might need to map a prefix if you are referencing a type from a custom assembly or for types that exist in a WPF assembly but are from a CLR namespace that was not mapped to the default XAML namespace. For more information about prefixes, XAML namespaces, and mapping CLR namespaces, see [XAML Namespaces and Namespace Mapping for WPF XAML](../../../docs/framework/wpf/advanced/xaml-namespaces-and-namespace-mapping-for-wpf-xaml.md). ### Type Properties That Support Typename-as-String - WPF supports techniques that enable specifying the value of some properties of type without requiring an `x:Type` markup extension usage. Instead, you can specify the value as a string that names the type. Examples of this are and . Support for this behavior is not provided through either type converters or markup extensions. Instead, this is a deferral behavior implemented through . + WPF supports techniques that enable specifying the value of some properties of type without requiring an `x:Type` markup extension usage. Instead, you can specify the value as a string that names the type. Examples of this are and . Support for this behavior is not provided through either type converters or markup extensions. Instead, this is a deferral behavior implemented through . Silverlight supports a similar convention. In fact, Silverlight does not currently support `{x:Type}` in its XAML language support, and does not accept `{x:Type}` usages outside of a few circumstances that are intended to support WPF-Silverlight XAML migration. Therefore, the typename-as-string behavior is built-in to all Silverlight native property evaluation where a is the value. diff --git a/docs/framework/xaml-services/x-xdata-intrinsic-xaml-type.md b/docs/framework/xaml-services/x-xdata-intrinsic-xaml-type.md index 703fcf9f874ba..7016843b41425 100644 --- a/docs/framework/xaml-services/x-xdata-intrinsic-xaml-type.md +++ b/docs/framework/xaml-services/x-xdata-intrinsic-xaml-type.md @@ -49,11 +49,11 @@ Enables placement of XML data islands within a XAML production. XML elements wit Programmatic access to XML data and the `x:XData` intrinsic XAML type is possible in .NET Framework XAML Services through the class. ## WPF Usage Notes - The `x:XData` object is primarily used as a child object of an , or alternatively, as the child object of the property (in XAML, this is typically expressed in property element syntax). + The `x:XData` object is primarily used as a child object of an , or alternatively, as the child object of the property (in XAML, this is typically expressed in property element syntax). The data should typically redefine the base XML namespace within the data island to be a new default XML namespace (set to an empty string). This is easiest for simple data islands because the expressions that are used to reference and bind to the data can avoid inclusion of prefixes. More complex data islands might define multiple prefixes for the data and use a specific prefix for the XML namespace at the root. In this case, all expression references should include the appropriate namespace-mapped prefix. For more information, see [Data Binding Overview](../../../docs/framework/wpf/data/data-binding-overview.md). - Technically, `x:XData` can be used as the content of any property of type . However, is the only prominent implementation. + Technically, `x:XData` can be used as the content of any property of type . However, is the only prominent implementation. ## See Also diff --git a/docs/framework/xaml-services/xaml-namespaces-for-net-framework-xaml-services.md b/docs/framework/xaml-services/xaml-namespaces-for-net-framework-xaml-services.md index 679d1c3483dc4..b008183f62265 100644 --- a/docs/framework/xaml-services/xaml-namespaces-for-net-framework-xaml-services.md +++ b/docs/framework/xaml-services/xaml-namespaces-for-net-framework-xaml-services.md @@ -42,20 +42,20 @@ A XAML namespace is a concept that expands on the definition of an XML namespace *clrnsName* is the string name that identifies a CLR namespace. This string name includes any internal dot characters (.) that provide hints about the CLR namespace and its relation to other CLR namespaces. - *assemblyShortName* is the string name of an assembly that defines types that are useful in XAML. The types to be accessed through the declared XAML namespace are expected to be defined by the assembly and to be specifically declared within the CLR namespace specified by *clrnsName*. This string name typically parallels the information as reported by . + *assemblyShortName* is the string name of an assembly that defines types that are useful in XAML. The types to be accessed through the declared XAML namespace are expected to be defined by the assembly and to be specifically declared within the CLR namespace specified by *clrnsName*. This string name typically parallels the information as reported by . A more complete definition of the CLR namespace and assembly convention is as follows: `clr-namespace:` *clrnsName* `; assembly=` *assemblyName* - *assemblyName* represents any string that is legal as an input. This string can include culture, public key, or version information (definitions of these concepts are defined in the reference topic for ). COFF format and evidence (as used by other overloads of ) are not relevant for XAML assembly loading purposes; all load information must be presented as a string. + *assemblyName* represents any string that is legal as an input. This string can include culture, public key, or version information (definitions of these concepts are defined in the reference topic for ). COFF format and evidence (as used by other overloads of ) are not relevant for XAML assembly loading purposes; all load information must be presented as a string. Specifying a public key for the assembly is a useful technique for XAML security, or for removing possible ambiguity that can exist if assemblies are loaded by simple name, or pre-exist in a cache or application domain. For more information, see [XAML Security Considerations](../../../docs/framework/xaml-services/xaml-security-considerations.md). ## XAML Namespace Declarations in the XAML Services API In the XAML Services API, a XAML namespace declaration is represented by a object. If you are declaring a XAML namespace in code, you call the constructor. The `ns` and `prefix` parameters are specified as strings, and the input to provide for these parameters corresponds to the definition of XAML namespace identifier and XAML namespace prefix as provided previously in this topic. - If you are examining XAML namespace information as part of a XAML node stream or through other access to the XAML type system, reports the XAML namespace identifier, and reports the XAML namespace prefix. + If you are examining XAML namespace information as part of a XAML node stream or through other access to the XAML type system, reports the XAML namespace identifier, and reports the XAML namespace prefix. In a XAML node stream, the XAML namespace information can appear as a XAML node that precedes the entity to which it applies. This includes cases where the XAML namespace information precedes the `StartObject` of the XAML root element. For more information, see [Understanding XAML Node Stream Structures and Concepts](../../../docs/framework/xaml-services/understanding-xaml-node-stream-structures-and-concepts.md). @@ -65,7 +65,7 @@ A XAML namespace is a concept that expands on the definition of an XML namespace In order to generate an object graph from a XAML node stream, XAML namespace declarations must exist for each XAML prefix used in the original markup and recorded in the XAML node stream. At this point, instances are being created, and true type-mapping behavior occurs. - If you need to prepopulate XAML namespace information, in cases where the XAML namespace you intend the XAML schema context to use is not defined in the markup, one technique you can use is to declare XML namespace declarations in the for an . Then use that as input for a XAML reader constructor, or . + If you need to prepopulate XAML namespace information, in cases where the XAML namespace you intend the XAML schema context to use is not defined in the markup, one technique you can use is to declare XML namespace declarations in the for an . Then use that as input for a XAML reader constructor, or . Two other API that are relevant for XAML namespace handling in .NET Framework XAML Services are the attributes and . These attributes apply to assemblies. is used by a XAML schema context to interpret any XAML namespace declaration that includes a URI. is used by tools that emit XAML so that a particular XAML namespace can be serialized with a predictable prefix. For more information, see [XAML-Related CLR Attributes for Custom Types and Libraries](../../../docs/framework/xaml-services/xaml-related-clr-attributes-for-custom-types-and-libraries.md). diff --git a/docs/framework/xaml-services/xaml-related-clr-attributes-for-custom-types-and-libraries.md b/docs/framework/xaml-services/xaml-related-clr-attributes-for-custom-types-and-libraries.md index 62dc919916015..95411d540b3bd 100644 --- a/docs/framework/xaml-services/xaml-related-clr-attributes-for-custom-types-and-libraries.md +++ b/docs/framework/xaml-services/xaml-related-clr-attributes-for-custom-types-and-libraries.md @@ -120,7 +120,7 @@ This topic describes the common language runtime (CLR) attributes that are defin **Arguments:** None. - is applied to specific types that might appear as child elements within whitespace significant content (content held by a collection that has ). is mainly relevant to the save path, but is available in the XAML type system in the load path by examining . For more information, see [Whitespace Processing in XAML](../../../docs/framework/xaml-services/whitespace-processing-in-xaml.md). + is applied to specific types that might appear as child elements within whitespace significant content (content held by a collection that has ). is mainly relevant to the save path, but is available in the XAML type system in the load path by examining . For more information, see [Whitespace Processing in XAML](../../../docs/framework/xaml-services/whitespace-processing-in-xaml.md). ### TypeConverterAttribute **Reference Documentation:** diff --git a/docs/framework/xaml-services/xamlservices-class-and-basic-xaml-reading-or-writing.md b/docs/framework/xaml-services/xamlservices-class-and-basic-xaml-reading-or-writing.md index 02d06fb3e131e..5c9f34585bb01 100644 --- a/docs/framework/xaml-services/xamlservices-class-and-basic-xaml-reading-or-writing.md +++ b/docs/framework/xaml-services/xamlservices-class-and-basic-xaml-reading-or-writing.md @@ -59,7 +59,7 @@ manager: "wpickett" In many scenarios the object tree that you save is related to an original operation that loaded XAML either with or with other API implemented by a framework/application model. There might be differences captured in the object tree that are due to state changes, changes where your application captured runtime settings from a user, changed XAML because your application is a XAML design surface, etc. With or without changes, the concept of first loading XAML from markup and then saving it again and comparing the two XAML markup forms is sometimes referred as a round-trip representation of the XAML. - The challenge with saving and serializing a complex object that is set in a markup form is in achieving a balance between full representation without information loss, versus verbosity that makes the XAML less human-readable. Moreover, different customers for XAML might have different definitions or expectations for how that balance should be set. The APIs represent one definition of that balance. The APIs use available XAML schema context and the default CLR-based characteristics of , , and other XAML intrinsic and XAML type system concepts to determine where certain XAML node stream constructs can be optimized when they are saved back into markup. For example, save paths can use CLR-based default XAML schema context to resolve for objects, can determine a , and then can omit property element tags when they write the property to the XAML content of the object. + The challenge with saving and serializing a complex object that is set in a markup form is in achieving a balance between full representation without information loss, versus verbosity that makes the XAML less human-readable. Moreover, different customers for XAML might have different definitions or expectations for how that balance should be set. The APIs represent one definition of that balance. The APIs use available XAML schema context and the default CLR-based characteristics of , , and other XAML intrinsic and XAML type system concepts to determine where certain XAML node stream constructs can be optimized when they are saved back into markup. For example, save paths can use CLR-based default XAML schema context to resolve for objects, can determine a , and then can omit property element tags when they write the property to the XAML content of the object. ## Transform diff --git a/docs/fsharp/language-reference/arrays.md b/docs/fsharp/language-reference/arrays.md index 68b0a7bf3bb54..b0dc7f3fefa2e 100644 --- a/docs/fsharp/language-reference/arrays.md +++ b/docs/fsharp/language-reference/arrays.md @@ -59,9 +59,9 @@ When slice notation is used, a new copy of the array is created. ## Array Types and Modules -The type of all F# arrays is the .NET Framework type . Therefore, F# arrays support all the functionality available in . +The type of all F# arrays is the .NET Framework type . Therefore, F# arrays support all the functionality available in . -The library module [`Microsoft.FSharp.Collections.Array`](https://msdn.microsoft.com/library/0cda8040-9396-40dd-8dcd-cf48542165a1) supports operations on one-dimensional arrays. The modules `Array2D`, `Array3D`, and `Array4D` contain functions that support operations on arrays of two, three, and four dimensions, respectively. You can create arrays of rank greater than four by using . +The library module [`Microsoft.FSharp.Collections.Array`](https://msdn.microsoft.com/library/0cda8040-9396-40dd-8dcd-cf48542165a1) supports operations on one-dimensional arrays. The modules `Array2D`, `Array3D`, and `Array4D` contain functions that support operations on arrays of two, three, and four dimensions, respectively. You can create arrays of rank greater than four by using . ### Simple Functions [`Array.get`](https://msdn.microsoft.com/library/dd93e85d-7e80-4d76-8de0-b6d45bcf07bc) gets an element. [`Array.length`](https://msdn.microsoft.com/library/0d775b6a-4a8f-4bd1-83e5-843b3251725f) gives the length of an array. [`Array.set`](https://msdn.microsoft.com/library/847edc0d-4dc5-4a39-98c7-d4320c60e790) sets an element to a specified value. The following code example illustrates the use of these functions. @@ -99,7 +99,7 @@ The output of the preceding code is as follows: [|; Test2; |] ``` -The string `Test1` appears only in the first array because the operation of creating a new element overwrites the reference in `firstArray` but does not affect the original reference to an empty string that is still present in `secondArray`. The string `Test2` appears in both arrays because the `Insert` operation on the type affects the underlying object, which is referenced in both arrays. +The string `Test1` appears only in the first array because the operation of creating a new element overwrites the reference in `firstArray` but does not affect the original reference to an empty string that is still present in `secondArray`. The string `Test2` appears in both arrays because the `Insert` operation on the type affects the underlying object, which is referenced in both arrays. [`Array.sub`](https://msdn.microsoft.com/library/40fb12ba-41d7-4ef0-b33a-56727deeef9d) generates a new array from a subrange of an array. You specify the subrange by providing the starting index and the length. The following code demonstrates the use of `Array.sub`. @@ -330,7 +330,7 @@ false ### Searching Arrays -[`Array.find`](https://msdn.microsoft.com/library/db6d920a-de19-4520-85a4-d83de77c1b33) takes a Boolean function and returns the first element for which the function returns `true`, or raises a if no element that satisfies the condition is found. [`Array.findIndex`](https://msdn.microsoft.com/library/5ae3a8f9-7b8f-44ea-a740-d5700f4d899f) is like `Array.find`, except that it returns the index of the element instead of the element itself. +[`Array.find`](https://msdn.microsoft.com/library/db6d920a-de19-4520-85a4-d83de77c1b33) takes a Boolean function and returns the first element for which the function returns `true`, or raises a if no element that satisfies the condition is found. [`Array.findIndex`](https://msdn.microsoft.com/library/5ae3a8f9-7b8f-44ea-a740-d5700f4d899f) is like `Array.find`, except that it returns the index of the element instead of the element itself. The following code uses `Array.find` and `Array.findIndex` to locate a number that is both a perfect square and perfect cube. diff --git a/docs/fsharp/language-reference/assertions.md b/docs/fsharp/language-reference/assertions.md index c184fe3d3df34..c48406d9882f7 100644 --- a/docs/fsharp/language-reference/assertions.md +++ b/docs/fsharp/language-reference/assertions.md @@ -33,7 +33,7 @@ Assertion checking is enabled only when you compile in Debug mode; that is, if t The assertion failure error cannot be caught by using F# exception handling. >[!NOTE] -The `assert` function resolves to . +The `assert` function resolves to . ## Example diff --git a/docs/fsharp/language-reference/computation-expressions.md b/docs/fsharp/language-reference/computation-expressions.md index 2e418c3285f8f..25163ac5d8a87 100644 --- a/docs/fsharp/language-reference/computation-expressions.md +++ b/docs/fsharp/language-reference/computation-expressions.md @@ -217,7 +217,7 @@ comp |> step |> step |> step |> step |> step |> step comp |> step |> step |> step |> step |> step |> step |> step |> step ``` -A computation expression has an underlying type, which the expression returns. The underlying type may represent a computed result or a delayed computation that can be performed, or it may provide a way to iterate through some type of collection. In the previous example, the underlying type was **Eventually**. For a sequence expression, the underlying type is . For a query expression, the underlying type is . For an asychronous workflow, the underlying type is [`Async`](https://msdn.microsoft.com/library/03eb4d12-a01a-4565-a077-5e83f17cf6f7). The `Async` object represents the work to be performed to compute the result. For example, you call [`Async.RunSynchronously`](https://msdn.microsoft.com/library/0a6663a9-50f2-4d38-8bf3-cefd1a51fd6b) to execute a computation and return the result. +A computation expression has an underlying type, which the expression returns. The underlying type may represent a computed result or a delayed computation that can be performed, or it may provide a way to iterate through some type of collection. In the previous example, the underlying type was **Eventually**. For a sequence expression, the underlying type is . For a query expression, the underlying type is . For an asychronous workflow, the underlying type is [`Async`](https://msdn.microsoft.com/library/03eb4d12-a01a-4565-a077-5e83f17cf6f7). The `Async` object represents the work to be performed to compute the result. For example, you call [`Async.RunSynchronously`](https://msdn.microsoft.com/library/0a6663a9-50f2-4d38-8bf3-cefd1a51fd6b) to execute a computation and return the result. ## Custom Operations You can define a custom operation on a computation expression and use a custom operation as an operator in a computation expression. For example, you can include a query operator in a query expression. When you define a custom operation, you must define the Yield and For methods in the computation expression. To define a custom operation, put it in a builder class for the computation expression, and then apply the [`CustomOperationAttribute`](https://msdn.microsoft.com/library/199f3927-79df-484b-ba66-85f58cc49b19). This attribute takes a string as an argument, which is the name to be used in a custom operation. This name comes into scope at the start of the opening curly brace of the computation expression. Therefore, you shouldn’t use identifiers that have the same name as a custom operation in this block. For example, avoid the use of identifiers such as `all` or `last` in query expressions. diff --git a/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md b/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md index 6282954c3c89d..d8771b4f37660 100644 --- a/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md +++ b/docs/fsharp/language-reference/symbol-and-operator-reference/arithmetic-operators.md @@ -58,7 +58,7 @@ Floating-point numbers should never be directly compared for equality, because t ## Overloaded and Generic Operators All of the operators discussed in this topic are defined in the **Microsoft.FSharp.Core.Operators** namespace. Some of the operators are defined by using statically resolved type parameters. This means that there are individual definitions for each specific type that works with that operator. All of the unary and binary arithmetic and bitwise operators are in this category. The comparison operators are generic and therefore work with any type, not just primitive arithmetic types. Discriminated union and record types have their own custom implementations that are generated by the F# compiler. Class types use the method . -The generic operators are customizable. To customize the comparison functions, override to provide your own custom equality comparison, and then implement . The interface has a single method, the method. +The generic operators are customizable. To customize the comparison functions, override to provide your own custom equality comparison, and then implement . The interface has a single method, the method. ## Operators and Type Inference diff --git a/docs/standard/assembly-format.md b/docs/standard/assembly-format.md index 519dba46d2eef..dbdc6a6a1fc9e 100644 --- a/docs/standard/assembly-format.md +++ b/docs/standard/assembly-format.md @@ -34,4 +34,4 @@ Assembly Headers from ECMA 335 II.25.1, Structure of the runtime file format. ## Processing the Assemblies -It is possible to write tools or APIs to process assemblies. Assembly information enables making programmatic decisions at runtime, re-writing assemblies, providing API IntelliSense in an editor and generating documentation. and [Mono.Cecil](http://www.mono-project.com/docs/tools+libraries/libraries/Mono.Cecil/) are good examples of tools that are frequently used for this purpose. +It is possible to write tools or APIs to process assemblies. Assembly information enables making programmatic decisions at runtime, re-writing assemblies, providing API IntelliSense in an editor and generating documentation. and [Mono.Cecil](http://www.mono-project.com/docs/tools+libraries/libraries/Mono.Cecil/) are good examples of tools that are frequently used for this purpose. diff --git a/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md index bb8f79ced77be..bcc42384400a8 100644 --- a/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/best-practices-for-implementing-the-event-based-asynchronous-pattern.md @@ -87,7 +87,7 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr - If there was an error during execution of the asynchronous operation, the results should not be accessible. Ensure that accessing any property in the when is not `null` raises the exception referenced by . The class provides the method for this purpose. -- Ensure that any attempt to access the result raises an stating that the operation was canceled. Use the method to perform this verification. +- Ensure that any attempt to access the result raises an stating that the operation was canceled. Use the method to perform this verification. ### Progress Reporting @@ -111,7 +111,7 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr - In the case of cancellation, set the flag in the object. -- Ensure that any attempt to access the result raises an stating that the operation was canceled. Use the method to perform this verification. +- Ensure that any attempt to access the result raises an stating that the operation was canceled. Use the method to perform this verification. - Ensure that calls to a cancellation method always return successfully, and never raise an exception. In general, a client is not notified as to whether an operation is truly cancelable at any given time, and is not notified as to whether a previously issued cancellation has succeeded. However, the application will always be given notification when a cancellation succeeded, because the application takes part in the completion status. @@ -119,7 +119,7 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr ### Errors and Exceptions -- Catch any exceptions that occur in the asynchronous operation and set the value of the property to that exception. +- Catch any exceptions that occur in the asynchronous operation and set the value of the property to that exception. ### Threading and Contexts For correct operation of your class, it is critical that the client's event handlers are invoked on the proper thread or context for the given application model, including [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)] and Windows Forms applications. Two important helper classes are provided to ensure that your asynchronous class behaves correctly under any application model: and . @@ -129,7 +129,7 @@ private void Form1_MethodNameCompleted(object sender, MethodNameCompletedEventAr To report progress, incremental results, and completion to the client, call the and methods on the . is responsible for marshaling calls to the client's event handlers to the proper thread or context. > [!NOTE] -> You can circumvent these rules if you explicitly want to go against the policy of the application model, but still benefit from the other advantages of using the Event-based Asynchronous Pattern. For example, you may want a class operating in Windows Forms to be free threaded. You can create a free threaded class, as long as developers understand the implied restrictions. Console applications do not synchronize the execution of calls. This can cause `ProgressChanged` events to be raised out of order. If you wish to have serialized execution of calls, implement and install a class. +> You can circumvent these rules if you explicitly want to go against the policy of the application model, but still benefit from the other advantages of using the Event-based Asynchronous Pattern. For example, you may want a class operating in Windows Forms to be free threaded. You can create a free threaded class, as long as developers understand the implied restrictions. Console applications do not synchronize the execution of calls. This can cause `ProgressChanged` events to be raised out of order. If you wish to have serialized execution of calls, implement and install a class. For more information about using and to enable your asynchronous operations, see [Walkthrough: Implementing a Component That Supports the Event-based Asynchronous Pattern](../../../docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md). diff --git a/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md b/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md index 252b1b8c63d5f..2acc9ebcd4f35 100644 --- a/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md +++ b/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md @@ -44,7 +44,7 @@ The .NET Framework enables you to call any method asynchronously. To do this you - Do some work and then call `EndInvoke` to block until the call completes. -- Obtain a using the property, use its method to block execution until the is signaled, and then call `EndInvoke`. +- Obtain a using the property, use its method to block execution until the is signaled, and then call `EndInvoke`. - Poll the returned by `BeginInvoke` to determine when the asynchronous call has completed, and then call `EndInvoke`. @@ -78,7 +78,7 @@ The .NET Framework enables you to call any method asynchronously. To do this you If you use a , you can perform additional processing before or after the asynchronous call completes, but before calling `EndInvoke` to retrieve the results. > [!NOTE] -> The wait handle is not closed automatically when you call `EndInvoke`. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, dispose of it by calling the method. Garbage collection works more efficiently when disposable objects are explicitly disposed. +> The wait handle is not closed automatically when you call `EndInvoke`. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, dispose of it by calling the method. Garbage collection works more efficiently when disposable objects are explicitly disposed. [!code-cpp[AsyncDelegateExamples#3](../../../samples/snippets/cpp/VS_Snippets_CLR/AsyncDelegateExamples/cpp/waithandle.cpp#3)] [!code-csharp[AsyncDelegateExamples#3](../../../samples/snippets/csharp/VS_Snippets_CLR/AsyncDelegateExamples/CS/waithandle.cs#3)] @@ -94,7 +94,7 @@ The .NET Framework enables you to call any method asynchronously. To do this you ## Executing a Callback Method When an Asynchronous Call Completes If the thread that initiates the asynchronous call does not need to be the thread that processes the results, you can execute a callback method when the call completes. The callback method is executed on a thread. - To use a callback method, you must pass `BeginInvoke` an delegate that represents the callback method. You can also pass an object that contains information to be used by the callback method. In the callback method, you can cast the , which is the only parameter of the callback method, to an object. You can then use the property to get the delegate that was used to initiate the call so that you can call `EndInvoke`. + To use a callback method, you must pass `BeginInvoke` an delegate that represents the callback method. You can also pass an object that contains information to be used by the callback method. In the callback method, you can cast the , which is the only parameter of the callback method, to an object. You can then use the property to get the delegate that was used to initiate the call so that you can call `EndInvoke`. Notes on the example: diff --git a/docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md index ce3a7101a2705..c06969f5f1275 100644 --- a/docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md @@ -29,7 +29,7 @@ manager: "wpickett" # Walkthrough: Implementing a Component That Supports the Event-based Asynchronous Pattern If you are writing a class with some operations that may incur noticeable delays, consider giving it asynchronous functionality by implementing the [Event-based Asynchronous Pattern Overview](../../../docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md). - This walkthrough illustrates how to create a component that implements the Event-based Asynchronous Pattern. It is implemented using helper classes from the namespace, which ensures that the component works correctly under any application model, including [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)], Console applications and Windows Forms applications. This component is also designable with a control and your own custom designers. + This walkthrough illustrates how to create a component that implements the Event-based Asynchronous Pattern. It is implemented using helper classes from the namespace, which ensures that the component works correctly under any application model, including [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)], Console applications and Windows Forms applications. This component is also designable with a control and your own custom designers. When you are through, you will have an application that computes prime numbers asynchronously. Your application will have a main user interface (UI) thread and a thread for each prime number calculation. Although testing whether a large number is prime can take a noticeable amount of time, the main UI thread will not be interrupted by this delay, and the form will be responsive during the calculations. You will be able to run as many calculations as you like concurrently and selectively cancel pending calculations. @@ -63,7 +63,7 @@ If you are writing a class with some operations that may incur noticeable delays #### To define asynchronous events for clients of your component: -1. Import the and namespaces at the top of your file. +1. Import the and namespaces at the top of your file. [!code-csharp[System.ComponentModel.AsyncOperationManager#11](../../../samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#11)] [!code-vb[System.ComponentModel.AsyncOperationManager#11](../../../samples/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb#11)] diff --git a/docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md index 25dae05c5c9b9..e3b58914f8527 100644 --- a/docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md @@ -21,21 +21,21 @@ ms.author: "ronpet" manager: "wpickett" --- # Consuming the Task-based Asynchronous Pattern -When you use the Task-based Asynchronous Pattern (TAP) to work with asynchronous operations, you can use callbacks to achieve waiting without blocking. For tasks, this is achieved through methods such as . Language-based asynchronous support hides callbacks by allowing asynchronous operations to be awaited within normal control flow, and compiler-generated code provides this same API-level support. +When you use the Task-based Asynchronous Pattern (TAP) to work with asynchronous operations, you can use callbacks to achieve waiting without blocking. For tasks, this is achieved through methods such as . Language-based asynchronous support hides callbacks by allowing asynchronous operations to be awaited within normal control flow, and compiler-generated code provides this same API-level support. ## Suspending Execution with Await Starting with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], you can use the [await](~/docs/csharp/language-reference/keywords/await.md) keyword in C# and the [Await Operator](~/docs/visual-basic/language-reference/operators/await-operator.md) in Visual Basic to asynchronously await and objects. When you're awaiting a , the `await` expression is of type `void`. When you're awaiting a , the `await` expression is of type `TResult`. An `await` expression must occur inside the body of an asynchronous method. For more information about C# and Visual Basic language support in the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], see the C# and Visual Basic language specifications. - Under the covers, the await functionality installs a callback on the task by using a continuation. This callback resumes the asynchronous method at the point of suspension. When the asynchronous method is resumed, if the awaited operation completed successfully and was a , its `TResult` is returned. If the or that was awaited ended in the state, an exception is thrown. If the or that was awaited ended in the state, the exception that caused it to fault is thrown. A `Task` can fault as a result of multiple exceptions, but only one of these exceptions is propagated. However, the property returns an exception that contains all the errors. + Under the covers, the await functionality installs a callback on the task by using a continuation. This callback resumes the asynchronous method at the point of suspension. When the asynchronous method is resumed, if the awaited operation completed successfully and was a , its `TResult` is returned. If the or that was awaited ended in the state, an exception is thrown. If the or that was awaited ended in the state, the exception that caused it to fault is thrown. A `Task` can fault as a result of multiple exceptions, but only one of these exceptions is propagated. However, the property returns an exception that contains all the errors. - If a synchronization context ( object) is associated with the thread that was executing the asynchronous method at the time of suspension (for example, if the property is not `null`), the asynchronous method resumes on that same synchronization context by using the context’s method. Otherwise, it relies on the task scheduler ( object) that was current at the time of suspension. Typically, this is the default task scheduler (), which targets the thread pool. This task scheduler determines whether the awaited asynchronous operation should resume where it completed or whether the resumption should be scheduled. The default scheduler typically allows the continuation to run on the thread that the awaited operation completed. + If a synchronization context ( object) is associated with the thread that was executing the asynchronous method at the time of suspension (for example, if the property is not `null`), the asynchronous method resumes on that same synchronization context by using the context’s method. Otherwise, it relies on the task scheduler ( object) that was current at the time of suspension. Typically, this is the default task scheduler (), which targets the thread pool. This task scheduler determines whether the awaited asynchronous operation should resume where it completed or whether the resumption should be scheduled. The default scheduler typically allows the continuation to run on the thread that the awaited operation completed. When an asynchronous method is called, it synchronously executes the body of the function up until the first await expression on an awaitable instance that has not yet completed, at which point the invocation returns to the caller. If the asynchronous method does not return `void`, a or object is returned to represent the ongoing computation. In a non-void asynchronous method, if a return statement is encountered or the end of the method body is reached, the task is completed in the final state. If an unhandled exception causes control to leave the body of the asynchronous method, the task ends in the state. If that exception is an , the task instead ends in the state. In this manner, the result or exception is eventually published. There are several important variations of this behavior. For performance reasons, if a task has already completed by the time the task is awaited, control is not yielded, and the function continues to execute. Additionally, returning to the original context isn't always the desired behavior and can be changed; this is described in more detail in the next section. ### Configuring Suspension and Resumption with Yield and ConfigureAwait - Several methods provide more control over an asynchronous method’s execution. For example, you can use the method to introduce a yield point into the asynchronous method: + Several methods provide more control over an asynchronous method’s execution. For example, you can use the method to introduce a yield point into the asynchronous method: ```csharp public class Task : … @@ -58,7 +58,7 @@ Task.Run(async delegate }); ``` - You can also use the method for better control over suspension and resumption in an asynchronous method. As mentioned previously, by default, the current context is captured at the time an asynchronous method is suspended, and that captured context is used to invoke the asynchronous method’s continuation upon resumption. In many cases, this is the exact behavior you want. In other cases, you may not care about the continuation context, and you can achieve better performance by avoiding such posts back to the original context. To enable this, use the method to inform the await operation not to capture and resume on the context, but to continue execution wherever the asynchronous operation that was being awaited completed: + You can also use the method for better control over suspension and resumption in an asynchronous method. As mentioned previously, by default, the current context is captured at the time an asynchronous method is suspended, and that captured context is used to invoke the asynchronous method’s continuation upon resumption. In many cases, this is the exact behavior you want. In other cases, you may not care about the continuation context, and you can achieve better performance by avoiding such posts back to the original context. To enable this, use the method to inform the await operation not to capture and resume on the context, but to continue execution wherever the asynchronous operation that was being awaited completed: ```csharp await someTask.ConfigureAwait(continueOnCapturedContext:false); @@ -98,7 +98,7 @@ var cts = new CancellationTokenSource(); Cancellation requests may be initiated from any thread. - You can pass the value to any method that accepts a cancellation token to indicate that cancellation will never be requested. This causes the property to return `false`, and the called method can optimize accordingly. For testing purposes, you can also pass in a pre-canceled cancellation token that is instantiated by using the constructor that accepts a Boolean value to indicate whether the token should start in an already-canceled or not-cancelable state. + You can pass the value to any method that accepts a cancellation token to indicate that cancellation will never be requested. This causes the property to return `false`, and the called method can optimize accordingly. For testing purposes, you can also pass in a pre-canceled cancellation token that is instantiated by using the constructor that accepts a Boolean value to indicate whether the token should start in an already-canceled or not-cancelable state. This approach to cancellation has several advantages: @@ -144,7 +144,7 @@ public async void button1_Click(object sender, EventArgs e) } ``` - Some of these methods, such as the overload, exist as shorthand for the method. Other overloads, such as , enable you to use await within the offloaded work, for example: + Some of these methods, such as the overload, exist as shorthand for the method. Other overloads, such as , enable you to use await within the offloaded work, for example: ```csharp public async void button1_Click(object sender, EventArgs e) @@ -158,7 +158,7 @@ public async void button1_Click(object sender, EventArgs e) } ``` - Such overloads are logically equivalent to using the method in conjunction with the extension method in the Task Parallel Library. + Such overloads are logically equivalent to using the method in conjunction with the extension method in the Task Parallel Library. ### Task.FromResult Use the method in scenarios where data may already be available and just needs to be returned from a task-returning method lifted into a : @@ -480,9 +480,9 @@ public async void btnRun_Click(object sender, EventArgs e) Another example of early bailout involves using the method in conjunction with the method, as discussed in the next section. ### Task.Delay - You can use the method to introduce pauses into an asynchronous method’s execution. This is useful for many kinds of functionality, including building polling loops and delaying the handling of user input for a predetermined period of time. The method can also be useful in combination with for implementing time-outs on awaits. + You can use the method to introduce pauses into an asynchronous method’s execution. This is useful for many kinds of functionality, including building polling loops and delaying the handling of user input for a predetermined period of time. The method can also be useful in combination with for implementing time-outs on awaits. - If a task that’s part of a larger asynchronous operation (for example, an ASP.NET web service) takes too long to complete, the overall operation could suffer, especially if it fails to ever complete. For this reason, it’s important to be able to time out when waiting on an asynchronous operation. The synchronous , , and methods accept time-out values, but the corresponding / and the previously mentioned / methods do not. Instead, you can use and in combination to implement a time-out. + If a task that’s part of a larger asynchronous operation (for example, an ASP.NET web service) takes too long to complete, the overall operation could suffer, especially if it fails to ever complete. For this reason, it’s important to be able to time out when waiting on an asynchronous operation. The synchronous , , and methods accept time-out values, but the corresponding / and the previously mentioned / methods do not. Instead, you can use and in combination to implement a time-out. For example, in your UI application, let's say that you want to download an image and disable the UI while the image is downloading. However, if the download takes too long, you want to re-enable the UI and discard the download: diff --git a/docs/standard/asynchronous-programming-patterns/deciding-when-to-implement-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/deciding-when-to-implement-the-event-based-asynchronous-pattern.md index e4494823831ef..668e14f3321ca 100644 --- a/docs/standard/asynchronous-programming-patterns/deciding-when-to-implement-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/deciding-when-to-implement-the-event-based-asynchronous-pattern.md @@ -24,7 +24,7 @@ ms.author: dotnetcontent manager: "wpickett" --- # Deciding When to Implement the Event-based Asynchronous Pattern -The Event-based Asynchronous Pattern provides a pattern for exposing the asynchronous behavior of a class. With the introduction of this pattern, the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] defines two patterns for exposing asynchronous behavior: the Asynchronous Pattern based on the interface, and the event-based pattern. This topic describes when it is appropriate for you to implement both patterns. +The Event-based Asynchronous Pattern provides a pattern for exposing the asynchronous behavior of a class. With the introduction of this pattern, the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] defines two patterns for exposing asynchronous behavior: the Asynchronous Pattern based on the interface, and the event-based pattern. This topic describes when it is appropriate for you to implement both patterns. For more information about asynchronous programming with the interface, see [Event-based Asynchronous Pattern (EAP)](../../../docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md). diff --git a/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md b/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md index 3aa0d79a789e2..7a79f1ea9cb79 100644 --- a/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md +++ b/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-eap.md @@ -38,7 +38,7 @@ There are a number of ways to expose asynchronous features to client code. The E Describes how to determine when you should choose to implement the Event-based Asynchronous Pattern instead of the pattern. [Walkthrough: Implementing a Component That Supports the Event-based Asynchronous Pattern](../../../docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md) - Illustrates how to create a component that implements the Event-based Asynchronous Pattern. It is implemented using helper classes from the namespace, which ensures that the component works correctly under any application model. + Illustrates how to create a component that implements the Event-based Asynchronous Pattern. It is implemented using helper classes from the namespace, which ensures that the component works correctly under any application model. [How to: Use Components That Support the Event-based Asynchronous Pattern](../../../docs/standard/asynchronous-programming-patterns/how-to-use-components-that-support-the-event-based-asynchronous-pattern.md) Describes how to use a component that supports the Event-based Asynchronous Pattern. diff --git a/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md b/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md index 87ea5fd5775d4..ac431e55ea6df 100644 --- a/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md +++ b/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md @@ -113,7 +113,7 @@ public class AsyncExample The `userState` parameter for the multiple-invocation overloads allows you to distinguish among asynchronous operations. You provide a unique value (for example, a GUID or hash code) for each call to `Method1Async(string param, object userState)`, and when each operation is completed, your event handler can determine which instance of the operation raised the completion event. ### Tracking Pending Operations - If you use the multiple-invocation overloads, your code will need to keep track of the `userState` objects (task IDs) for pending tasks. For each call to `Method1Async(string param, object userState)`, you will typically generate a new, unique `userState` object and add it to a collection. When the task corresponding to this `userState` object raises the completion event, your completion method implementation will examine and remove it from your collection. Used this way, the `userState` parameter takes the role of a task ID. + If you use the multiple-invocation overloads, your code will need to keep track of the `userState` objects (task IDs) for pending tasks. For each call to `Method1Async(string param, object userState)`, you will typically generate a new, unique `userState` object and add it to a collection. When the task corresponding to this `userState` object raises the completion event, your completion method implementation will examine and remove it from your collection. Used this way, the `userState` parameter takes the role of a task ID. > [!NOTE] > You must be careful to provide a unique value for `userState` in your calls to multiple-invocation overloads. Non-unique task IDs will cause the asynchronous class throw an . @@ -128,7 +128,7 @@ public class AsyncExample ### Receiving Progress Updates and Incremental Results A class that adheres to the Event-based Asynchronous Pattern may optionally provide an event for tracking progress and incremental results. This will typically be named `ProgressChanged` or *MethodName*`ProgressChanged`, and its corresponding event handler will take a parameter. - The event handler for the `ProgressChanged` event can examine the property to determine what percentage of an asynchronous task has been completed. This property will range from 0 to 100, and it can be used to update the property of a . If multiple asynchronous operations are pending, you can use the property to distinguish which operation is reporting progress. + The event handler for the `ProgressChanged` event can examine the property to determine what percentage of an asynchronous task has been completed. This property will range from 0 to 100, and it can be used to update the property of a . If multiple asynchronous operations are pending, you can use the property to distinguish which operation is reporting progress. Some classes may report incremental results as asynchronous operations proceed. These results will be stored in a class that derives from and they will appear as properties in the derived class. You can access these results in the event handler for the `ProgressChanged` event, just as you would access the property. If multiple asynchronous operations are pending, you can use the property to distinguish which operation is reporting incremental results. diff --git a/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md index a9b1e142469ac..7f3f4e2d0d003 100644 --- a/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern.md @@ -23,16 +23,16 @@ You can implement the Task-based Asynchronous Pattern (TAP) in three ways: by us ## Generating TAP methods ### Using the compilers -Starting with [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], any method that is attributed with the `async` keyword (`Async` in Visual Basic) is considered an asynchronous method, and the C# and Visual Basic compilers perform the necessary transformations to implement the method asynchronously by using TAP. An asynchronous method should return either a or a object. For the latter, the body of the function should return a `TResult`, and the compiler ensures that this result is made available through the resulting task object. Similarly, any exceptions that go unhandled within the body of the method are marshaled to the output task and cause the resulting task to end in the state. The exception is when an (or derived type) goes unhandled, in which case the resulting task ends in the state. +Starting with [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], any method that is attributed with the `async` keyword (`Async` in Visual Basic) is considered an asynchronous method, and the C# and Visual Basic compilers perform the necessary transformations to implement the method asynchronously by using TAP. An asynchronous method should return either a or a object. For the latter, the body of the function should return a `TResult`, and the compiler ensures that this result is made available through the resulting task object. Similarly, any exceptions that go unhandled within the body of the method are marshaled to the output task and cause the resulting task to end in the state. The exception is when an (or derived type) goes unhandled, in which case the resulting task ends in the state. ### Generating TAP methods manually -You may implement the TAP pattern manually for better control over implementation. The compiler relies on the public surface area exposed from the namespace and supporting types in the namespace. To implement the TAP yourself, you create a object, perform the asynchronous operation, and when it completes, call the , , or method, or the `Try` version of one of these methods. When you implement a TAP method manually, you must complete the resulting task when the represented asynchronous operation completes. For example: +You may implement the TAP pattern manually for better control over implementation. The compiler relies on the public surface area exposed from the namespace and supporting types in the namespace. To implement the TAP yourself, you create a object, perform the asynchronous operation, and when it completes, call the , , or method, or the `Try` version of one of these methods. When you implement a TAP method manually, you must complete the resulting task when the represented asynchronous operation completes. For example: [!code-csharp[Conceptual.TAP_Patterns#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#1)] [!code-vb[Conceptual.TAP_Patterns#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#1)] ### Hybrid approach - You may find it useful to implement the TAP pattern manually but to delegate the core logic for the implementation to the compiler. For example, you may want to use the hybrid approach when you want to verify arguments outside a compiler-generated asynchronous method so that exceptions can escape to the method’s direct caller rather than being exposed through the object: + You may find it useful to implement the TAP pattern manually but to delegate the core logic for the implementation to the compiler. For example, you may want to use the hybrid approach when you want to verify arguments outside a compiler-generated asynchronous method so that exceptions can escape to the method’s direct caller rather than being exposed through the object: [!code-csharp[Conceptual.TAP_Patterns#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#2)] [!code-vb[Conceptual.TAP_Patterns#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#2)] @@ -43,19 +43,19 @@ You may implement the TAP pattern manually for better control over implementatio You may implement both compute-bound and I/O-bound asynchronous operations as TAP methods. However, when TAP methods are exposed publicly from a library, they should be provided only for workloads that involve I/O-bound operations (they may also involve computation, but should not be purely computational). If a method is purely compute-bound, it should be exposed only as a synchronous implementation. The code that consumes it may then choose whether to wrap an invocation of that synchronous method into a task to offload the work to another thread or to achieve parallelism. And if a method is IO-bound, it should be exposed only as an asynchronous implementation. ### Compute-bound tasks -The class is ideally suited for representing computationally intensive operations. By default, it takes advantage of special support within the class to provide efficient execution, and it also provides significant control over when, where, and how asynchronous computations execute. +The class is ideally suited for representing computationally intensive operations. By default, it takes advantage of special support within the class to provide efficient execution, and it also provides significant control over when, where, and how asynchronous computations execute. You can generate compute-bound tasks in the following ways: -- In the .NET Framework 4, use the method, which accepts a delegate (typically an or a ) to be executed asynchronously. If you provide an delegate, the method returns a object that represents the asynchronous execution of that delegate. If you provide a delegate, the method returns a object. Overloads of the method accept a cancellation token (), task creation options (), and a task scheduler (), all of which provide fine-grained control over the scheduling and execution of the task. A factory instance that targets the current task scheduler is available as a static property () of the class; for example: `Task.Factory.StartNew(…)`. +- In the .NET Framework 4, use the method, which accepts a delegate (typically an or a ) to be executed asynchronously. If you provide an delegate, the method returns a object that represents the asynchronous execution of that delegate. If you provide a delegate, the method returns a object. Overloads of the method accept a cancellation token (), task creation options (), and a task scheduler (), all of which provide fine-grained control over the scheduling and execution of the task. A factory instance that targets the current task scheduler is available as a static property () of the class; for example: `Task.Factory.StartNew(…)`. -- In the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] and later versions (including .NET Core and .NET Standard), use the static method as a shortcut to . You may use to easily launch a compute-bound task that targets the thread pool. In the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] and later versions, this is the preferred mechanism for launching a compute-bound task. Use `StartNew` directly only when you want more fine-grained control over the task. +- In the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] and later versions (including .NET Core and .NET Standard), use the static method as a shortcut to . You may use to easily launch a compute-bound task that targets the thread pool. In the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] and later versions, this is the preferred mechanism for launching a compute-bound task. Use `StartNew` directly only when you want more fine-grained control over the task. - Use the constructors of the `Task` type or the `Start` method if you want to generate and schedule the task separately. Public methods must only return tasks that have already been started. -- Use the overloads of the method. This method creates a new task that is scheduled when another task completes. Some of the overloads accept a cancellation token, continuation options, and a task scheduler for better control over the scheduling and execution of the continuation task. +- Use the overloads of the method. This method creates a new task that is scheduled when another task completes. Some of the overloads accept a cancellation token, continuation options, and a task scheduler for better control over the scheduling and execution of the continuation task. -- Use the and methods. These methods create a new task that is scheduled when all or any of a supplied set of tasks completes. These methods also provide overloads to control the scheduling and execution of these tasks. +- Use the and methods. These methods create a new task that is scheduled when all or any of a supplied set of tasks completes. These methods also provide overloads to control the scheduling and execution of these tasks. In compute-bound tasks, the system can prevent the execution of a scheduled task if it receives a cancellation request before it starts running the task. As such, if you provide a cancellation token ( object), you can pass that token to the asynchronous code that monitors the token. You can also provide the token to one of the previously mentioned methods such as `StartNew` or `Run` so that the `Task` runtime may also monitor the token. @@ -75,12 +75,12 @@ If another exception goes unhandled within the body of the task, the task ends i ### I/O-bound tasks To create a task that should not be directly backed by a thread for the entirety of its execution, use the type. This type exposes a property that returns an associated instance. The life cycle of this task is controlled by methods such as , , , and their `TrySet` variants. -Let's say that you want to create a task that will complete after a specified period of time. For example, you may want to delay an activity in the user interface. The class already provides the ability to asynchronously invoke a delegate after a specified period of time, and by using you can put a front on the timer, for example: +Let's say that you want to create a task that will complete after a specified period of time. For example, you may want to delay an activity in the user interface. The class already provides the ability to asynchronously invoke a delegate after a specified period of time, and by using you can put a front on the timer, for example: [!code-csharp[Conceptual.TAP_Patterns#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#4)] [!code-vb[Conceptual.TAP_Patterns#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#4)] -Starting with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], the method is provided for this purpose, and you can use it inside another asynchronous method, for example, to implement an asynchronous polling loop: +Starting with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], the method is provided for this purpose, and you can use it inside another asynchronous method, for example, to implement an asynchronous polling loop: [!code-csharp[Conceptual.TAP_Patterns#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.tap_patterns/cs/patterns1.cs#5)] [!code-vb[Conceptual.TAP_Patterns#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.tap_patterns/vb/patterns1.vb#5)] diff --git a/docs/standard/asynchronous-programming-patterns/interop-with-other-asynchronous-patterns-and-types.md b/docs/standard/asynchronous-programming-patterns/interop-with-other-asynchronous-patterns-and-types.md index cc36d13c50a1d..a0bc669802563 100644 --- a/docs/standard/asynchronous-programming-patterns/interop-with-other-asynchronous-patterns-and-types.md +++ b/docs/standard/asynchronous-programming-patterns/interop-with-other-asynchronous-patterns-and-types.md @@ -47,7 +47,7 @@ The .NET Framework 1.0 introduced the pattern, otherw [!code-csharp[Conceptual.AsyncInterop#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Stream1.cs#3)] [!code-vb[Conceptual.AsyncInterop#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/stream1.vb#3)] - You can use the method to implement a TAP wrapper for this operation as follows: + You can use the method to implement a TAP wrapper for this operation as follows: [!code-csharp[Conceptual.AsyncInterop#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Wrap1.cs#4)] [!code-vb[Conceptual.AsyncInterop#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wrap1.vb#4)] @@ -93,12 +93,12 @@ The .NET Framework 1.0 introduced the pattern, otherw ### From Wait Handles to TAP - Although wait handles don't implement an asynchronous pattern, advanced developers may use the class and the method for asynchronous notifications when a wait handle is set. You can wrap the method to enable a task-based alternative to any synchronous wait on a wait handle: + Although wait handles don't implement an asynchronous pattern, advanced developers may use the class and the method for asynchronous notifications when a wait handle is set. You can wrap the method to enable a task-based alternative to any synchronous wait on a wait handle: [!code-csharp[Conceptual.AsyncInterop#12](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Wait1.cs#12)] [!code-vb[Conceptual.AsyncInterop#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Wait1.vb#12)] - With this method, you can use existing implementations in asynchronous methods. For example, if you want to throttle the number of asynchronous operations that are executing at any particular time, you can utilize a semaphore (a object). You can throttle to *N* the number of operations that run concurrently by initializing the semaphore’s count to *N*, waiting on the semaphore any time you want to perform an operation, and releasing the semaphore when you’re done with an operation: + With this method, you can use existing implementations in asynchronous methods. For example, if you want to throttle the number of asynchronous operations that are executing at any particular time, you can utilize a semaphore (a object). You can throttle to *N* the number of operations that run concurrently by initializing the semaphore’s count to *N*, waiting on the semaphore any time you want to perform an operation, and releasing the semaphore when you’re done with an operation: [!code-csharp[Conceptual.AsyncInterop#13](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.AsyncInterop/cs/Semaphore1.cs#13)] [!code-vb[Conceptual.AsyncInterop#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.AsyncInterop/vb/Semaphore1.vb#13)] diff --git a/docs/standard/asynchronous-programming-patterns/multithreaded-programming-with-the-event-based-asynchronous-pattern.md b/docs/standard/asynchronous-programming-patterns/multithreaded-programming-with-the-event-based-asynchronous-pattern.md index f6ae0eb710c4c..ef188f7bed580 100644 --- a/docs/standard/asynchronous-programming-patterns/multithreaded-programming-with-the-event-based-asynchronous-pattern.md +++ b/docs/standard/asynchronous-programming-patterns/multithreaded-programming-with-the-event-based-asynchronous-pattern.md @@ -41,7 +41,7 @@ There are a number of ways to expose asynchronous features to client code. The E Describes how to determine when you should choose to implement the Event-based Asynchronous Pattern instead of the pattern. [Walkthrough: Implementing a Component That Supports the Event-based Asynchronous Pattern](../../../docs/standard/asynchronous-programming-patterns/component-that-supports-the-event-based-asynchronous-pattern.md) - Illustrates how to create a component that implements the Event-based Asynchronous Pattern. It is implemented using helper classes from the namespace, which ensures that the component works correctly under any application model. + Illustrates how to create a component that implements the Event-based Asynchronous Pattern. It is implemented using helper classes from the namespace, which ensures that the component works correctly under any application model. [How to: Use Components That Support the Event-based Asynchronous Pattern](../../../docs/standard/asynchronous-programming-patterns/how-to-use-components-that-support-the-event-based-asynchronous-pattern.md) Describes how to use a component that supports the Event-based Asynchronous Pattern. diff --git a/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md b/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md index cbc14da860435..ce675508dac6d 100644 --- a/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md +++ b/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md @@ -21,12 +21,12 @@ ms.author: "ronpet" manager: "wpickett" --- # Task-based Asynchronous Pattern (TAP) -The Task-based Asynchronous Pattern (TAP) is based on the and types in the namespace, which are used to represent arbitrary asynchronous operations. TAP is the recommended asynchronous design pattern for new development. +The Task-based Asynchronous Pattern (TAP) is based on the and types in the namespace, which are used to represent arbitrary asynchronous operations. TAP is the recommended asynchronous design pattern for new development. ## Naming, Parameters, and Return Types TAP uses a single method to represent the initiation and completion of an asynchronous operation. This is in contrast to the Asynchronous Programming Model (APM or `IAsyncResult`) pattern, which requires `Begin` and `End` methods, and in contrast to the Event-based Asynchronous Pattern (EAP), which requires a method that has the `Async` suffix and also requires one or more events, event handler delegate types, and `EventArg`-derived types. Asynchronous methods in TAP include the `Async` suffix after the operation name; for example, `GetAsync` for a `Get` operation. If you're adding a TAP method to a class that already contains that method name with the `Async` suffix, use the suffix `TaskAsync` instead. For example, if the class already has a `GetAsync` method, use the name `GetTaskAsync`.   - The TAP method returns either a or a , based on whether the corresponding synchronous method returns void or a type `TResult`. + The TAP method returns either a or a , based on whether the corresponding synchronous method returns void or a type `TResult`. The parameters of a TAP method should match the parameters of its synchronous counterpart, and should be provided in the same order. However, `out` and `ref` parameters are exempt from this rule and should be avoided entirely. Any data that would have been returned through an `out` or `ref` parameter should instead be returned as part of the `TResult` returned by , and should use a tuple or a custom data structure to accommodate multiple values. Methods that are devoted exclusively to the creation, manipulation, or combination of tasks (where the asynchronous intent of the method is clear in the method name or in the name of the type to which the method belongs) need not follow this naming pattern; such methods are often referred to as *combinators*. Examples of combinators include and , and are discussed in the [Using the Built-in Task-based Combinators](../../../docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md#combinators) section of the article [Consuming the Task-based Asynchronous Pattern](../../../docs/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern.md). @@ -50,7 +50,7 @@ The Task-based Asynchronous Pattern (TAP) is based on the class provides a life cycle for asynchronous operations, and that cycle is represented by the enumeration. To support corner cases of types that derive from and , and to support the separation of construction from scheduling, the class exposes a method. Tasks that are created by the public constructors are referred to as *cold tasks*, because they begin their life cycle in the non-scheduled state and are scheduled only when is called on these instances. - All other tasks begin their life cycle in a hot state, which means that the asynchronous operations they represent have already been initiated and their task status is an enumeration value other than . All tasks that are returned from TAP methods must be activated. **If a TAP method internally uses a task’s constructor to instantiate the task to be returned, the TAP method must call on the object before returning it.** Consumers of a TAP method may safely assume that the returned task is active and should not try to call on any that is returned from a TAP method. Calling on an active task results in an exception. + All other tasks begin their life cycle in a hot state, which means that the asynchronous operations they represent have already been initiated and their task status is an enumeration value other than . All tasks that are returned from TAP methods must be activated. **If a TAP method internally uses a task’s constructor to instantiate the task to be returned, the TAP method must call on the object before returning it.** Consumers of a TAP method may safely assume that the returned task is active and should not try to call on any that is returned from a TAP method. Calling on an active task results in an exception. ## Cancellation (Optional) In TAP, cancellation is optional for both asynchronous method implementers and asynchronous method consumers. If an operation allows cancellation, it exposes an overload of the asynchronous method that accepts a cancellation token ( instance). By convention, the parameter is named `cancellationToken`. diff --git a/docs/standard/attributes/applying-attributes.md b/docs/standard/attributes/applying-attributes.md index f31864831c711..c9d097dda644f 100644 --- a/docs/standard/attributes/applying-attributes.md +++ b/docs/standard/attributes/applying-attributes.md @@ -32,7 +32,7 @@ Use the following process to apply an attribute to an element of your code. The attribute is emitted into metadata when you compile your code and is available to the common language runtime and any custom tool or application through the runtime reflection services. - By convention, all attribute names end with Attribute. However, several languages that target the runtime, such as Visual Basic and C#, do not require you to specify the full name of an attribute. For example, if you want to initialize , you only need to reference it as **Obsolete**. + By convention, all attribute names end with Attribute. However, several languages that target the runtime, such as Visual Basic and C#, do not require you to specify the full name of an attribute. For example, if you want to initialize , you only need to reference it as **Obsolete**. ## Applying an Attribute to a Method The following code example shows how to declare **System.ObsoleteAttribute**, which marks code as obsolete. The string `"Will be removed in next version"` is passed to the attribute. This attribute causes a compiler warning that displays the passed string when code that the attribute describes is called. diff --git a/docs/standard/attributes/index.md b/docs/standard/attributes/index.md index dadc73187c140..196bd8db0cf9d 100644 --- a/docs/standard/attributes/index.md +++ b/docs/standard/attributes/index.md @@ -24,7 +24,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Extending Metadata Using Attributes -The common language runtime allows you to add keyword-like descriptive declarations, called attributes, to annotate programming elements such as types, fields, methods, and properties. When you compile your code for the runtime, it is converted into Microsoft intermediate language (MSIL) and placed inside a portable executable (PE) file along with metadata generated by the compiler. Attributes allow you to place extra descriptive information into metadata that can be extracted using runtime reflection services. The compiler creates attributes when you declare instances of special classes that derive from . +The common language runtime allows you to add keyword-like descriptive declarations, called attributes, to annotate programming elements such as types, fields, methods, and properties. When you compile your code for the runtime, it is converted into Microsoft intermediate language (MSIL) and placed inside a portable executable (PE) file along with metadata generated by the compiler. Attributes allow you to place extra descriptive information into metadata that can be extracted using runtime reflection services. The compiler creates attributes when you declare instances of special classes that derive from . The .NET Framework uses attributes for a variety of reasons and to address a number of issues. Attributes describe how to serialize data, specify characteristics that are used to enforce security, and limit optimizations by the just-in-time (JIT) compiler so the code remains easy to debug. Attributes can also record the name of a file or the author of code, or control the visibility of controls and members during forms development. @@ -39,4 +39,4 @@ The common language runtime allows you to add keyword-like descriptive declarati |[How to: Load Assemblies into the Reflection-Only Context](../../../docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md)|Explains how to retrieve custom attribute information in the reflection-only context.| ## Reference - + diff --git a/docs/standard/attributes/retrieving-information-stored-in-attributes.md b/docs/standard/attributes/retrieving-information-stored-in-attributes.md index 9b5144c43369a..8c95fd04bd1fe 100644 --- a/docs/standard/attributes/retrieving-information-stored-in-attributes.md +++ b/docs/standard/attributes/retrieving-information-stored-in-attributes.md @@ -19,7 +19,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Retrieving Information Stored in Attributes -Retrieving a custom attribute is a simple process. First, declare an instance of the attribute you want to retrieve. Then, use the method to initialize the new attribute to the value of the attribute you want to retrieve. Once the new attribute is initialized, you simply use its properties to get the values. +Retrieving a custom attribute is a simple process. First, declare an instance of the attribute you want to retrieve. Then, use the method to initialize the new attribute to the value of the attribute you want to retrieve. Once the new attribute is initialized, you simply use its properties to get the values. > [!IMPORTANT] > This topic describes how to retrieve attributes for code loaded into the execution context. To retrieve attributes for code loaded into the reflection-only context, you must use the class, as shown in [How to: Load Assemblies into the Reflection-Only Context](../../../docs/framework/reflection-and-codedom/how-to-load-assemblies-into-the-reflection-only-context.md). @@ -58,7 +58,7 @@ The attribute was not found. ## Retrieving Multiple Instances of an Attribute Applied to the Same Scope - In the previous example, the class to inspect and the specific attribute to find are passed to . That code works well if only one instance of an attribute is applied on the class level. However, if multiple instances of an attribute are applied on the same class level, the **GetCustomAttribute** method does not retrieve all the information. In cases where multiple instances of the same attribute are applied to the same scope, you can use to place all instances of an attribute into an array. For example, if two instances of `DeveloperAttribute` are applied on the class level of the same class, the `GetAttribute` method can be modified to display the information found in both attributes. Remember, to apply multiple attributes on the same level, the attribute must be defined with the **AllowMultiple** property set to **true** in the . + In the previous example, the class to inspect and the specific attribute to find are passed to . That code works well if only one instance of an attribute is applied on the class level. However, if multiple instances of an attribute are applied on the same class level, the **GetCustomAttribute** method does not retrieve all the information. In cases where multiple instances of the same attribute are applied to the same scope, you can use to place all instances of an attribute into an array. For example, if two instances of `DeveloperAttribute` are applied on the class level of the same class, the `GetAttribute` method can be modified to display the information found in both attributes. Remember, to apply multiple attributes on the same level, the attribute must be defined with the **AllowMultiple** property set to **true** in the . The following code example shows how to use the **GetCustomAttributes** method to create an array that references all instances of `DeveloperAttribute` in any given class. The values of all attributes are then displayed to the console. @@ -80,10 +80,10 @@ The attribute was not found. If no instances of the `DeveloperAttribute` are found on the method level or class level, the `GetAttribute` method notifies the user that no attributes were found and displays the name of the method or class that does not contain the attribute. If an attribute is found, the `Name`, `Level`, and `Reviewed` fields are displayed to the console. - You can use the members of the class to get the individual methods and members in the passed class. This example first queries the **Type** object to get attribute information for the class level. Next, it uses to place instances of all methods into an array of objects to retrieve attribute information for the method level. You can also use the method to check for attributes on the property level or to check for attributes on the constructor level. + You can use the members of the class to get the individual methods and members in the passed class. This example first queries the **Type** object to get attribute information for the class level. Next, it uses to place instances of all methods into an array of objects to retrieve attribute information for the method level. You can also use the method to check for attributes on the property level or to check for attributes on the constructor level. ## See Also - - - + + + [Attributes](../../../docs/standard/attributes/index.md) diff --git a/docs/standard/attributes/writing-custom-attributes.md b/docs/standard/attributes/writing-custom-attributes.md index 6edd7f310b39f..7498d9663a28e 100644 --- a/docs/standard/attributes/writing-custom-attributes.md +++ b/docs/standard/attributes/writing-custom-attributes.md @@ -24,7 +24,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Writing Custom Attributes -To design your own custom attributes, you do not need to master many new concepts. If you are familiar with object-oriented programming and know how to design classes, you already have most of the knowledge needed. Custom attributes are essentially traditional classes that derive directly or indirectly from . Just like traditional classes, custom attributes contain methods that store and retrieve data. +To design your own custom attributes, you do not need to master many new concepts. If you are familiar with object-oriented programming and know how to design classes, you already have most of the knowledge needed. Custom attributes are essentially traditional classes that derive directly or indirectly from . Just like traditional classes, custom attributes contain methods that store and retrieve data. The primary steps to properly design custom attribute classes are as follows: @@ -46,7 +46,7 @@ To design your own custom attributes, you do not need to master many new concept [!code-csharp[Conceptual.Attributes.Usage#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.attributes.usage/cs/source2.cs#5)] [!code-vb[Conceptual.Attributes.Usage#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.attributes.usage/vb/source2.vb#5)] - The has three members that are important for the creation of custom attributes: [AttributeTargets](#cpconwritingcustomattributesanchor1), [Inherited](#cpconwritingcustomattributesanchor2), and [AllowMultiple](#cpconwritingcustomattributesanchor3). + The has three members that are important for the creation of custom attributes: [AttributeTargets](#cpconwritingcustomattributesanchor1), [Inherited](#cpconwritingcustomattributesanchor2), and [AllowMultiple](#cpconwritingcustomattributesanchor3). ### AttributeTargets Member @@ -60,7 +60,7 @@ To design your own custom attributes, you do not need to master many new concept ### Inherited Property - The property indicates whether your attribute can be inherited by classes that are derived from the classes to which your attribute is applied. This property takes either a **true** (the default) or **false** flag. For example, in the following example, `MyAttribute` has a default value of **true**, while `YourAttribute` has an value of **false**. + The property indicates whether your attribute can be inherited by classes that are derived from the classes to which your attribute is applied. This property takes either a **true** (the default) or **false** flag. For example, in the following example, `MyAttribute` has a default value of **true**, while `YourAttribute` has an value of **false**. [!code-cpp[Conceptual.Attributes.Usage#7](../../../samples/snippets/cpp/VS_Snippets_CLR/conceptual.attributes.usage/cpp/source2.cpp#7)] [!code-csharp[Conceptual.Attributes.Usage#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.attributes.usage/cs/source2.cs#7)] @@ -80,7 +80,7 @@ To design your own custom attributes, you do not need to master many new concept ### AllowMultiple Property - The property indicates whether multiple instances of your attribute can exist on an element. If set to **true**, multiple instances are allowed; if set to **false** (the default), only one instance is allowed. + The property indicates whether multiple instances of your attribute can exist on an element. If set to **true**, multiple instances are allowed; if set to **false** (the default), only one instance is allowed. In the following example, `MyAttribute` has a default value of **false**, while `YourAttribute` has a value of **true**. @@ -155,6 +155,6 @@ To design your own custom attributes, you do not need to master many new concept The first example shows the attribute applied with only the required named parameters, while the second example shows the attribute applied with both the required and optional parameters. ## See Also - + [Attributes](../../../docs/standard/attributes/index.md) diff --git a/docs/standard/base-types/anchors-in-regular-expressions.md b/docs/standard/base-types/anchors-in-regular-expressions.md index fea71458fd66c..9c07ecfb69d7e 100644 --- a/docs/standard/base-types/anchors-in-regular-expressions.md +++ b/docs/standard/base-types/anchors-in-regular-expressions.md @@ -39,13 +39,13 @@ manager: "wpickett" ## Start of String or Line: ^ - The `^` anchor specifies that the following pattern must begin at the first character position of the string. If you use `^` with the option (see [Regular Expression Options](../../../docs/standard/base-types/regular-expression-options.md)), the match must occur at the beginning of each line. + The `^` anchor specifies that the following pattern must begin at the first character position of the string. If you use `^` with the option (see [Regular Expression Options](../../../docs/standard/base-types/regular-expression-options.md)), the match must occur at the beginning of each line. - The following example uses the `^` anchor in a regular expression that extracts information about the years during which some professional baseball teams existed. The example calls two overloads of the method: + The following example uses the `^` anchor in a regular expression that extracts information about the years during which some professional baseball teams existed. The example calls two overloads of the method: - The call to the overload finds only the first substring in the input string that matches the regular expression pattern. -- The call to the overload with the `options` parameter set to finds all five substrings. +- The call to the overload with the `options` parameter set to finds all five substrings. [!code-csharp[Conceptual.RegEx.Language.Assertions#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/startofstring1.cs#1)] [!code-vb[Conceptual.RegEx.Language.Assertions#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/startofstring1.vb#1)] @@ -54,7 +54,7 @@ manager: "wpickett" |Pattern|Description| |-------------|-----------------| -|`^`|Begin the match at the beginning of the input string (or the beginning of the line if the method is called with the option).| +|`^`|Begin the match at the beginning of the input string (or the beginning of the line if the method is called with the option).| |`((\w+(\s?)){2,}`|Match one or more word characters followed either by zero or by one space exactly two times. This is the first capturing group. This expression also defines a second and third capturing group: The second consists of the captured word, and the third consists of the captured spaces.| |`,\s`|Match a comma followed by a white-space character.| |`(\w+\s\w+)`|Match one or more word characters followed by a space, followed by one or more word characters. This is the fourth capturing group.| @@ -70,9 +70,9 @@ manager: "wpickett" ## End of String or Line: $ The `$` anchor specifies that the preceding pattern must occur at the end of the input string, or before `\n` at the end of the input string. - If you use `$` with the option, the match can also occur at the end of a line. Note that `$` matches `\n` but does not match `\r\n` (the combination of carriage return and newline characters, or CR/LF). To match the CR/LF character combination, include `\r?$` in the regular expression pattern. + If you use `$` with the option, the match can also occur at the end of a line. Note that `$` matches `\n` but does not match `\r\n` (the combination of carriage return and newline characters, or CR/LF). To match the CR/LF character combination, include `\r?$` in the regular expression pattern. - The following example adds the `$` anchor to the regular expression pattern used in the example in the [Start of String or Line](#Start) section. When used with the original input string, which includes five lines of text, the method is unable to find a match, because the end of the first line does not match the `$` pattern. When the original input string is split into a string array, the method succeeds in matching each of the five lines. When the method is called with the `options` parameter set to , no matches are found because the regular expression pattern does not account for the carriage return element (\u+000D). However, when the regular expression pattern is modified by replacing `$` with `\r?$`, calling the method with the `options` parameter set to again finds five matches. + The following example adds the `$` anchor to the regular expression pattern used in the example in the [Start of String or Line](#Start) section. When used with the original input string, which includes five lines of text, the method is unable to find a match, because the end of the first line does not match the `$` pattern. When the original input string is split into a string array, the method succeeds in matching each of the five lines. When the method is called with the `options` parameter set to , no matches are found because the regular expression pattern does not account for the carriage return element (\u+000D). However, when the regular expression pattern is modified by replacing `$` with `\r?$`, calling the method with the `options` parameter set to again finds five matches. [!code-csharp[Conceptual.RegEx.Language.Assertions#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/endofstring1.cs#2)] [!code-vb[Conceptual.RegEx.Language.Assertions#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/endofstring1.vb#2)] @@ -81,9 +81,9 @@ manager: "wpickett" ## Start of String Only: \A - The `\A` anchor specifies that a match must occur at the beginning of the input string. It is identical to the `^` anchor, except that `\A` ignores the option. Therefore, it can only match the start of the first line in a multiline input string. + The `\A` anchor specifies that a match must occur at the beginning of the input string. It is identical to the `^` anchor, except that `\A` ignores the option. Therefore, it can only match the start of the first line in a multiline input string. - The following example is similar to the examples for the `^` and `$` anchors. It uses the `\A` anchor in a regular expression that extracts information about the years during which some professional baseball teams existed. The input string includes five lines. The call to the method finds only the first substring in the input string that matches the regular expression pattern. As the example shows, the option has no effect. + The following example is similar to the examples for the `^` and `$` anchors. It uses the `\A` anchor in a regular expression that extracts information about the years during which some professional baseball teams existed. The input string includes five lines. The call to the method finds only the first substring in the input string that matches the regular expression pattern. As the example shows, the option has no effect. [!code-csharp[Conceptual.RegEx.Language.Assertions#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.assertions/cs/startofstring2.cs#3)] [!code-vb[Conceptual.RegEx.Language.Assertions#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.assertions/vb/startofstring2.vb#3)] @@ -92,7 +92,7 @@ manager: "wpickett" ## End of String or Before Ending Newline: \Z - The `\Z` anchor specifies that a match must occur at the end of the input string, or before `\n` at the end of the input string. It is identical to the `$` anchor, except that `\Z` ignores the option. Therefore, in a multiline string, it can only match the end of the last line, or the last line before `\n`. + The `\Z` anchor specifies that a match must occur at the end of the input string, or before `\n` at the end of the input string. It is identical to the `$` anchor, except that `\Z` ignores the option. Therefore, in a multiline string, it can only match the end of the last line, or the last line before `\n`. Note that `\Z` matches `\n` but does not match `\r\n` (the CR/LF character combination). To match CR/LF, include `\r?\Z` in the regular expression pattern. @@ -105,7 +105,7 @@ manager: "wpickett" ## End of String Only: \z - The `\z` anchor specifies that a match must occur at the end of the input string. Like the `$` language element, `\z` ignores the option. Unlike the `\Z` language element, `\z` does not match a `\n` character at the end of a string. Therefore, it can only match the last line of the input string. + The `\z` anchor specifies that a match must occur at the end of the input string. Like the `$` language element, `\z` ignores the option. Unlike the `\Z` language element, `\z` does not match a `\n` character at the end of a string. Therefore, it can only match the last line of the input string. The following example uses the `\z` anchor in a regular expression that is otherwise identical to the example in the previous section, which extracts information about the years during which some professional baseball teams existed. The example tries to match each of five elements in a string array with the regular expression pattern `^((\w+(\s?)){2,}),\s(\w+\s\w+),(\s\d{4}(-(\d{4}|present))?,?)+\r?\z`. Two of the strings end with carriage return and line feed characters, one ends with a line feed character, and two end with neither a carriage return nor a line feed character. As the output shows, only the strings without a carriage return or line feed character match the pattern. @@ -116,7 +116,7 @@ manager: "wpickett" ## Contiguous Matches: \G - The `\G` anchor specifies that a match must occur at the point where the previous match ended. When you use this anchor with the or method, it ensures that all matches are contiguous. + The `\G` anchor specifies that a match must occur at the point where the previous match ended. When you use this anchor with the or method, it ensures that all matches are contiguous. The following example uses a regular expression to extract the names of rodent species from a comma-delimited string. diff --git a/docs/standard/base-types/backtracking-in-regular-expressions.md b/docs/standard/base-types/backtracking-in-regular-expressions.md index bf572fa3fcfe8..4e8c84f2f6055 100644 --- a/docs/standard/base-types/backtracking-in-regular-expressions.md +++ b/docs/standard/base-types/backtracking-in-regular-expressions.md @@ -104,7 +104,7 @@ manager: "wpickett" ## Backtracking with Nested Optional Quantifiers - The number of comparison operations required to match a regular expression pattern can increase exponentially if the pattern includes a large number of alternation constructs, if it includes nested alternation constructs, or, most commonly, if it includes nested optional quantifiers. For example, the regular expression pattern `^(a+)+$` is designed to match a complete string that contains one or more "a" characters. The example provides two input strings of identical length, but only the first string matches the pattern. The class is used to determine how long the match operation takes. + The number of comparison operations required to match a regular expression pattern can increase exponentially if the pattern includes a large number of alternation constructs, if it includes nested alternation constructs, or, most commonly, if it includes nested optional quantifiers. For example, the regular expression pattern `^(a+)+$` is designed to match a complete string that contains one or more "a" characters. The example provides two input strings of identical length, but only the first string matches the pattern. The class is used to determine how long the match operation takes. [!code-csharp[Conceptual.RegularExpressions.Backtracking#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.backtracking/cs/backtracking3.cs#3)] [!code-vb[Conceptual.RegularExpressions.Backtracking#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.backtracking/vb/backtracking3.vb#3)] @@ -127,14 +127,14 @@ manager: "wpickett" ### Defining a Time-out Interval - Starting with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], you can set a time-out value that represents the longest interval the regular expression engine will search for a single match before it abandons the attempt and throws a exception. You specify the time-out interval by supplying a value to the constructor for instance regular expressions. In addition, each static pattern matching method has an overload with a parameter that allows you to specify a time-out value. By default, the time-out interval is set to and the regular expression engine does not time out. + Starting with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], you can set a time-out value that represents the longest interval the regular expression engine will search for a single match before it abandons the attempt and throws a exception. You specify the time-out interval by supplying a value to the constructor for instance regular expressions. In addition, each static pattern matching method has an overload with a parameter that allows you to specify a time-out value. By default, the time-out interval is set to and the regular expression engine does not time out. > [!IMPORTANT] > We recommend that you always set a time-out interval if your regular expression relies on backtracking. A exception indicates that the regular expression engine was unable to find a match within in the specified time-out interval but does not indicate why the exception was thrown. The reason might be excessive backtracking, but it is also possible that the time-out interval was set too low given the system load at the time the exception was thrown. When you handle the exception, you can choose to abandon further matches with the input string or increase the time-out interval and retry the matching operation. - For example, the following code calls the constructor to instantiate a object with a time-out value of one second. The regular expression pattern `(a+)+$`, which matches one or more sequences of one or more "a" characters at the end of a line, is subject to excessive backtracking. If a is thrown, the example increases the time-out value up to a maximum interval of three seconds. After that, it abandons the attempt to match the pattern. + For example, the following code calls the constructor to instantiate a object with a time-out value of one second. The regular expression pattern `(a+)+$`, which matches one or more sequences of one or more "a" characters at the end of a line, is subject to excessive backtracking. If a is thrown, the example increases the time-out value up to a maximum interval of three seconds. After that, it abandons the attempt to match the pattern. [!code-csharp[System.Text.RegularExpressions.Regex.ctor#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ctor/cs/ctor1.cs#1)] [!code-vb[System.Text.RegularExpressions.Regex.ctor#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.ctor/vb/ctor1.vb#1)] @@ -154,7 +154,7 @@ manager: "wpickett" `(?<=` *subexpression* `)` is a positive lookbehind assertion; that is, the character or characters before the current position must match *subexpression*. `(? method. + The following example uses two equivalent regular expression patterns that validate the user name in an e-mail address. The first pattern is subject to poor performance because of excessive backtracking. The second pattern modifies the first regular expression by replacing a nested quantifier with a positive lookbehind assertion. The output from the example displays the execution time of the method. [!code-csharp[Conceptual.RegularExpressions.Backtracking#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.backtracking/cs/backtracking5.cs#5)] [!code-vb[Conceptual.RegularExpressions.Backtracking#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.backtracking/vb/backtracking5.vb#5)] @@ -164,7 +164,7 @@ manager: "wpickett" |Pattern|Description| |-------------|-----------------| |`^`|Start the match at the beginning of the string.| -|`[0-9A-Z]`|Match an alphanumeric character. This comparison is case-insensitive, because the method is called with the option.| +|`[0-9A-Z]`|Match an alphanumeric character. This comparison is case-insensitive, because the method is called with the option.| |`[-.\w]*`|Match zero, one, or more occurrences of a hyphen, period, or word character.| |`[0-9A-Z]`|Match an alphanumeric character.| |`([-.\w]*[0-9A-Z])*`|Match zero or more occurrences of the combination of zero or more hyphens, periods, or word characters, followed by an alphanumeric character. This is the first capturing group.| @@ -175,7 +175,7 @@ manager: "wpickett" |Pattern|Description| |-------------|-----------------| |`^`|Start the match at the beginning of the string.| -|`[0-9A-Z]`|Match an alphanumeric character. This comparison is case-insensitive, because the method is called with the option.| +|`[0-9A-Z]`|Match an alphanumeric character. This comparison is case-insensitive, because the method is called with the option.| |`[-.\w]*`|Match zero or more occurrences of a hyphen, period, or word character.| |`(?<=[0-9A-Z])`|Look back at the last matched character and continue the match if it is alphanumeric. Note that alphanumeric characters are a subset of the set that consists of periods, hyphens, and all word characters.| |`@`|Match an at sign ("@").| @@ -186,7 +186,7 @@ manager: "wpickett" `(?=` *subexpression* `)` is a positive lookahead assertion; that is, the character or characters after the current position must match *subexpression*. `(?!`*subexpression*`)` is a negative lookahead assertion; that is, the character or characters after the current position must not match *subexpression*. Both positive and negative lookahead assertions are most useful when *subexpression* is a subset of the next subexpression. - The following example uses two equivalent regular expression patterns that validate a fully qualified type name. The first pattern is subject to poor performance because of excessive backtracking. The second modifies the first regular expression by replacing a nested quantifier with a positive lookahead assertion. The output from the example displays the execution time of the method. + The following example uses two equivalent regular expression patterns that validate a fully qualified type name. The first pattern is subject to poor performance because of excessive backtracking. The second modifies the first regular expression by replacing a nested quantifier with a positive lookahead assertion. The output from the example displays the execution time of the method. [!code-csharp[Conceptual.RegularExpressions.Backtracking#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.backtracking/cs/backtracking6.cs#6)] [!code-vb[Conceptual.RegularExpressions.Backtracking#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.backtracking/vb/backtracking6.vb#6)] @@ -196,7 +196,7 @@ manager: "wpickett" |Pattern|Description| |-------------|-----------------| |`^`|Start the match at the beginning of the string.| -|`([A-Z]\w*)+\.`|Match an alphabetical character (A-Z) followed by zero or more word characters one or more times, followed by a period. This comparison is case-insensitive, because the method is called with the option.| +|`([A-Z]\w*)+\.`|Match an alphabetical character (A-Z) followed by zero or more word characters one or more times, followed by a period. This comparison is case-insensitive, because the method is called with the option.| |`(([A-Z]\w*)+\.)*`|Match the previous pattern zero or more times.| |`[A-Z]\w*`|Match an alphabetical character followed by zero or more word characters.| |`$`|End the match at the end of the input string.| @@ -206,7 +206,7 @@ manager: "wpickett" |Pattern|Description| |-------------|-----------------| |`^`|Start the match at the beginning of the string.| -|`(?=[A-Z])`|Look ahead to the first character and continue the match if it is alphabetical (A-Z). This comparison is case-insensitive, because the method is called with the option.| +|`(?=[A-Z])`|Look ahead to the first character and continue the match if it is alphabetical (A-Z). This comparison is case-insensitive, because the method is called with the option.| |`\w+\.`|Match one or more word characters followed by a period.| |`((?=[A-Z])\w+\.)*`|Match the pattern of one or more word characters followed by a period zero or more times. The initial word character must be alphabetical.| |`[A-Z]\w*`|Match an alphabetical character followed by zero or more word characters.| diff --git a/docs/standard/base-types/basic-string-operations.md b/docs/standard/base-types/basic-string-operations.md index 42b8699f15b18..a31ef2f4f1793 100644 --- a/docs/standard/base-types/basic-string-operations.md +++ b/docs/standard/base-types/basic-string-operations.md @@ -18,7 +18,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Basic String Operations in .NET -Applications often respond to users by constructing messages based on user input. For example, it is not uncommon for Web sites to respond to a newly logged-on user with a specialized greeting that includes the user's name. Several methods in the and classes allow you to dynamically construct custom strings to display in your user interface. These methods also help you perform a number of basic string operations like creating new strings from arrays of bytes, comparing the values of strings, and modifying existing strings. +Applications often respond to users by constructing messages based on user input. For example, it is not uncommon for Web sites to respond to a newly logged-on user with a specialized greeting that includes the user's name. Several methods in the and classes allow you to dynamically construct custom strings to display in your user interface. These methods also help you perform a number of basic string operations like creating new strings from arrays of bytes, comparing the values of strings, and modifying existing strings. ## In This Section [Creating New Strings](../../../docs/standard/base-types/creating-new.md) diff --git a/docs/standard/base-types/best-practices-strings.md b/docs/standard/base-types/best-practices-strings.md index 8f4e63299c184..6bafaee6a436d 100644 --- a/docs/standard/base-types/best-practices-strings.md +++ b/docs/standard/base-types/best-practices-strings.md @@ -52,19 +52,19 @@ manager: "wpickett" - Use overloads that explicitly specify the string comparison rules for string operations. Typically, this involves calling a method overload that has a parameter of type . -- Use or for comparisons as your safe default for culture-agnostic string matching. +- Use or for comparisons as your safe default for culture-agnostic string matching. -- Use comparisons with or for better performance. +- Use comparisons with or for better performance. -- Use string operations that are based on when you display output to the user. +- Use string operations that are based on when you display output to the user. -- Use the non-linguistic or values instead of string operations based on when the comparison is linguistically irrelevant (symbolic, for example). +- Use the non-linguistic or values instead of string operations based on when the comparison is linguistically irrelevant (symbolic, for example). -- Use the method instead of the method when you normalize strings for comparison. +- Use the method instead of the method when you normalize strings for comparison. -- Use an overload of the method to test whether two strings are equal. +- Use an overload of the method to test whether two strings are equal. -- Use the and methods to sort strings, not to check for equality. +- Use the and methods to sort strings, not to check for equality. - Use culture-sensitive formatting to display non-string data, such as numbers and dates, in a user interface. Use formatting with the invariant culture to persist non-string data in string form. @@ -72,9 +72,9 @@ manager: "wpickett" - Do not use overloads that do not explicitly or implicitly specify the string comparison rules for string operations. -- Do not use string operations based on in most cases. One of the few exceptions is when you are persisting linguistically meaningful but culturally agnostic data. +- Do not use string operations based on in most cases. One of the few exceptions is when you are persisting linguistically meaningful but culturally agnostic data. -- Do not use an overload of the or method and test for a return value of zero to determine whether two strings are equal. +- Do not use an overload of the or method and test for a return value of zero to determine whether two strings are equal. - Do not use culture-sensitive formatting to persist numeric data or date and time data in string form. @@ -136,17 +136,17 @@ manager: "wpickett" Comparisons that use current culture semantics are the default for the following methods: -- overloads that do not include a parameter. +- overloads that do not include a parameter. -- overloads. +- overloads. -- The default method, and the method with a `null` parameter. +- The default method, and the method with a `null` parameter. -- The default method, and the method with a `null` parameter. +- The default method, and the method with a `null` parameter. -- overloads that accept a as a search parameter and that do not have a parameter. +- overloads that accept a as a search parameter and that do not have a parameter. -- overloads that accept a as a search parameter and that do not have a parameter. +- overloads that accept a as a search parameter and that do not have a parameter. In any case, we recommend that you call an overload that has a parameter to make the intent of the method call clear. @@ -170,14 +170,14 @@ manager: "wpickett" [!code-vb[Conceptual.Strings.BestPractices#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/turkish1.vb#13)] ### Ordinal String Operations - Specifying the or value in a method call signifies a non-linguistic comparison in which the features of natural languages are ignored. Methods that are invoked with these values base string operation decisions on simple byte comparisons instead of casing or equivalence tables that are parameterized by culture. In most cases, this approach best fits the intended interpretation of strings while making code faster and more reliable. + Specifying the or value in a method call signifies a non-linguistic comparison in which the features of natural languages are ignored. Methods that are invoked with these values base string operation decisions on simple byte comparisons instead of casing or equivalence tables that are parameterized by culture. In most cases, this approach best fits the intended interpretation of strings while making code faster and more reliable. Ordinal comparisons are string comparisons in which each byte of each string is compared without linguistic interpretation; for example, "windows" does not match "Windows". This is essentially a call to the C runtime `strcmp` function. Use this comparison when the context dictates that strings should be matched exactly or demands conservative matching policy. Additionally, ordinal comparison is the fastest comparison operation because it applies no linguistic rules when determining a result. - Strings in .NET can contain embedded null characters. One of the clearest differences between ordinal and culture-sensitive comparison (including comparisons that use the invariant culture) concerns the handling of embedded null characters in a string. These characters are ignored when you use the and methods to perform culture-sensitive comparisons (including comparisons that use the invariant culture). As a result, in culture-sensitive comparisons, strings that contain embedded null characters can be considered equal to strings that do not. + Strings in .NET can contain embedded null characters. One of the clearest differences between ordinal and culture-sensitive comparison (including comparisons that use the invariant culture) concerns the handling of embedded null characters in a string. These characters are ignored when you use the and methods to perform culture-sensitive comparisons (including comparisons that use the invariant culture). As a result, in culture-sensitive comparisons, strings that contain embedded null characters can be considered equal to strings that do not. > [!IMPORTANT] -> Although string comparison methods disregard embedded null characters, string search methods such as , , , , and do not. +> Although string comparison methods disregard embedded null characters, string search methods such as , , , , and do not. The following example performs a culture-sensitive comparison of the string "Aa" with a similar string that contains several embedded null characters between "A" and "a", and shows how the two strings are considered equal. @@ -189,7 +189,7 @@ manager: "wpickett" [!code-csharp[Conceptual.Strings.BestPractices#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.bestpractices/cs/embeddednulls2.cs#20)] [!code-vb[Conceptual.Strings.BestPractices#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/embeddednulls2.vb#20)] - Case-insensitive ordinal comparisons are the next most conservative approach. These comparisons ignore most casing; for example, "windows" matches "Windows". When dealing with ASCII characters, this policy is equivalent to , except that it ignores the usual ASCII casing. Therefore, any character in [A, Z] (\u0041-\u005A) matches the corresponding character in [a,z] (\u0061-\007A). Casing outside the ASCII range uses the invariant culture's tables. Therefore, the following comparison: + Case-insensitive ordinal comparisons are the next most conservative approach. These comparisons ignore most casing; for example, "windows" matches "Windows". When dealing with ASCII characters, this policy is equivalent to , except that it ignores the usual ASCII casing. Therefore, any character in [A, Z] (\u0041-\u005A) matches the corresponding character in [a,z] (\u0061-\007A). Casing outside the ASCII range uses the invariant culture's tables. Therefore, the following comparison: [!code-csharp[Conceptual.Strings.BestPractices#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.bestpractices/cs/comparison2.cs#4)] [!code-vb[Conceptual.Strings.BestPractices#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/comparison2.vb#4)] @@ -202,18 +202,18 @@ manager: "wpickett" These comparisons are still very fast. > [!NOTE] -> The string behavior of the file system, registry keys and values, and environment variables is best represented by . +> The string behavior of the file system, registry keys and values, and environment variables is best represented by . - Both and use the binary values directly, and are best suited for matching. When you are not sure about your comparison settings, use one of these two values. However, because they perform a byte-by-byte comparison, they do not sort by a linguistic sort order (like an English dictionary) but by a binary sort order. The results may look odd in most contexts if displayed to users. + Both and use the binary values directly, and are best suited for matching. When you are not sure about your comparison settings, use one of these two values. However, because they perform a byte-by-byte comparison, they do not sort by a linguistic sort order (like an English dictionary) but by a binary sort order. The results may look odd in most contexts if displayed to users. - Ordinal semantics are the default for overloads that do not include a argument (including the equality operator). In any case, we recommend that you call an overload that has a parameter. + Ordinal semantics are the default for overloads that do not include a argument (including the equality operator). In any case, we recommend that you call an overload that has a parameter. ### String Operations that Use the Invariant Culture - Comparisons with the invariant culture use the property returned by the static property. This behavior is the same on all systems; it translates any characters outside its range into what it believes are equivalent invariant characters. This policy can be useful for maintaining one set of string behavior across cultures, but it often provides unexpected results. + Comparisons with the invariant culture use the property returned by the static property. This behavior is the same on all systems; it translates any characters outside its range into what it believes are equivalent invariant characters. This policy can be useful for maintaining one set of string behavior across cultures, but it often provides unexpected results. - Case-insensitive comparisons with the invariant culture use the static property returned by the static property for comparison information as well. Any case differences among these translated characters are ignored. + Case-insensitive comparisons with the invariant culture use the static property returned by the static property for comparison information as well. Any case differences among these translated characters are ignored. - Comparisons that use and work identically on ASCII strings. However, makes linguistic decisions that might not be appropriate for strings that have to be interpreted as a set of bytes. The `CultureInfo.InvariantCulture.CompareInfo` object makes the method interpret certain sets of characters as equivalent. For example, the following equivalence is valid under the invariant culture: + Comparisons that use and work identically on ASCII strings. However, makes linguistic decisions that might not be appropriate for strings that have to be interpreted as a set of bytes. The `CultureInfo.InvariantCulture.CompareInfo` object makes the method interpret certain sets of characters as equivalent. For example, the following equivalence is valid under the invariant culture: InvariantCulture: a + ̊ = å @@ -224,7 +224,7 @@ manager: "wpickett" When interpreting file names, cookies, or anything else where a combination such as "å" can appear, ordinal comparisons still offer the most transparent and fitting behavior. - On balance, the invariant culture has very few properties that make it useful for comparison. It does comparison in a linguistically relevant manner, which prevents it from guaranteeing full symbolic equivalence, but it is not the choice for display in any culture. One of the few reasons to use for comparison is to persist ordered data for a cross-culturally identical display. For example, if a large data file that contains a list of sorted identifiers for display accompanies an application, adding to this list would require an insertion with invariant-style sorting. + On balance, the invariant culture has very few properties that make it useful for comparison. It does comparison in a linguistically relevant manner, which prevents it from guaranteeing full symbolic equivalence, but it is not the choice for display in any culture. One of the few reasons to use for comparison is to persist ordered data for a cross-culturally identical display. For example, if a large data file that contains a list of sorted identifiers for display accompanies an application, adding to this list would require an insertion with invariant-style sorting. [Back to top](#top) @@ -246,16 +246,16 @@ manager: "wpickett" The following sections describe the methods that are most commonly used for string comparison. ### String.Compare - Default interpretation: . + Default interpretation: . - As the operation most central to string interpretation, all instances of these method calls should be examined to determine whether strings should be interpreted according to the current culture, or dissociated from the culture (symbolically). Typically, it is the latter, and a comparison should be used instead. + As the operation most central to string interpretation, all instances of these method calls should be examined to determine whether strings should be interpreted according to the current culture, or dissociated from the culture (symbolically). Typically, it is the latter, and a comparison should be used instead. - The class, which is returned by the property, also includes a method that provides a large number of matching options (ordinal, ignoring white space, ignoring kana type, and so on) by means of the flag enumeration. + The class, which is returned by the property, also includes a method that provides a large number of matching options (ordinal, ignoring white space, ignoring kana type, and so on) by means of the flag enumeration. ### String.CompareTo - Default interpretation: . + Default interpretation: . - This method does not currently offer an overload that specifies a type. It is usually possible to convert this method to the recommended form. + This method does not currently offer an overload that specifies a type. It is usually possible to convert this method to the recommended form. Types that implement the and interfaces implement this method. Because it does not offer the option of a parameter, implementing types often let the user specify a in their constructor. The following example defines a `FileName` class whose class constructor includes a parameter. This object is then used in the `FileName.CompareTo` method. @@ -263,58 +263,58 @@ manager: "wpickett" [!code-vb[Conceptual.Strings.BestPractices#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/api1.vb#6)] ### String.Equals - Default interpretation: . + Default interpretation: . The class lets you test for equality by calling either the static or instance method overloads, or by using the static equality operator. The overloads and operator use ordinal comparison by default. However, we still recommend that you call an overload that explicitly specifies the type even if you want to perform an ordinal comparison; this makes it easier to search code for a certain string interpretation. ### String.ToUpper and String.ToLower - Default interpretation: . + Default interpretation: . You should be careful when you use these methods, because forcing a string to a uppercase or lowercase is often used as a small normalization for comparing strings regardless of case. If so, consider using a case-insensitive comparison. - The and methods are also available. is the standard way to normalize case. Comparisons made using are behaviorally the composition of two calls: calling on both string arguments, and doing a comparison using . + The and methods are also available. is the standard way to normalize case. Comparisons made using are behaviorally the composition of two calls: calling on both string arguments, and doing a comparison using . Overloads are also available for converting to uppercase and lowercase in a specific culture, by passing a object that represents that culture to the method. ### Char.ToUpper and Char.ToLower - Default interpretation: . + Default interpretation: . - These methods work similarly to the and methods described in the previous section. + These methods work similarly to the and methods described in the previous section. ### String.StartsWith and String.EndsWith - Default interpretation: . + Default interpretation: . By default, both of these methods perform a culture-sensitive comparison. ### String.IndexOf and String.LastIndexOf - Default interpretation: . + Default interpretation: . - There is a lack of consistency in how the default overloads of these methods perform comparisons. All and methods that include a parameter perform an ordinal comparison, but the default and methods that include a parameter perform a culture-sensitive comparison. + There is a lack of consistency in how the default overloads of these methods perform comparisons. All and methods that include a parameter perform an ordinal comparison, but the default and methods that include a parameter perform a culture-sensitive comparison. - If you call the or method and pass it a string to locate in the current instance, we recommend that you call an overload that explicitly specifies the type. The overloads that include a argument do not allow you to specify a type. + If you call the or method and pass it a string to locate in the current instance, we recommend that you call an overload that explicitly specifies the type. The overloads that include a argument do not allow you to specify a type. [Back to top](#top) ## Methods that Perform String Comparison Indirectly - Some non-string methods that have string comparison as a central operation use the type. The class includes six static properties that return instances whose methods perform the following types of string comparisons: + Some non-string methods that have string comparison as a central operation use the type. The class includes six static properties that return instances whose methods perform the following types of string comparisons: -- Culture-sensitive string comparisons using the current culture. This object is returned by the property. +- Culture-sensitive string comparisons using the current culture. This object is returned by the property. -- Case-insensitive comparisons using the current culture. This object is returned by the property. +- Case-insensitive comparisons using the current culture. This object is returned by the property. -- Culture-insensitive comparisons using the word comparison rules of the invariant culture. This object is returned by the property. +- Culture-insensitive comparisons using the word comparison rules of the invariant culture. This object is returned by the property. -- Case-insensitive and culture-insensitive comparisons using the word comparison rules of the invariant culture. This object is returned by the property. +- Case-insensitive and culture-insensitive comparisons using the word comparison rules of the invariant culture. This object is returned by the property. -- Ordinal comparison. This object is returned by the property. +- Ordinal comparison. This object is returned by the property. -- Case-insensitive ordinal comparison. This object is returned by the property. +- Case-insensitive ordinal comparison. This object is returned by the property. ### Array.Sort and Array.BinarySearch - Default interpretation: . + Default interpretation: . - When you store any data in a collection, or read persisted data from a file or database into a collection, switching the current culture can invalidate the invariants in the collection. The method assumes that the elements in the array to be searched are already sorted. To sort any string element in the array, the method calls the method to order individual elements. Using a culture-sensitive comparer can be dangerous if the culture changes between the time that the array is sorted and its contents are searched. For example, in the following code, storage and retrieval operate on the comparer that is provided implicitly by the `Thread.CurrentThread.CurrentCulture` property. If the culture can change between the calls to `StoreNames` and `DoesNameExist`, and especially if the array contents are persisted somewhere between the two method calls, the binary search may fail. + When you store any data in a collection, or read persisted data from a file or database into a collection, switching the current culture can invalidate the invariants in the collection. The method assumes that the elements in the array to be searched are already sorted. To sort any string element in the array, the method calls the method to order individual elements. Using a culture-sensitive comparer can be dangerous if the culture changes between the time that the array is sorted and its contents are searched. For example, in the following code, storage and retrieval operate on the comparer that is provided implicitly by the `Thread.CurrentThread.CurrentCulture` property. If the culture can change between the calls to `StoreNames` and `DoesNameExist`, and especially if the array contents are persisted somewhere between the two method calls, the binary search may fail. [!code-csharp[Conceptual.Strings.BestPractices#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.bestpractices/cs/indirect1.cs#7)] [!code-vb[Conceptual.Strings.BestPractices#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/indirect1.vb#7)] @@ -324,7 +324,7 @@ manager: "wpickett" [!code-csharp[Conceptual.Strings.BestPractices#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.bestpractices/cs/indirect1.cs#8)] [!code-vb[Conceptual.Strings.BestPractices#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/indirect1.vb#8)] - If this data is persisted and moved across cultures, and sorting is used to present this data to the user, you might consider using , which operates linguistically for better user output but is unaffected by changes in culture. The following example modifies the two previous examples to use the invariant culture for sorting and searching the array. + If this data is persisted and moved across cultures, and sorting is used to present this data to the user, you might consider using , which operates linguistically for better user output but is unaffected by changes in culture. The following example modifies the two previous examples to use the invariant culture for sorting and searching the array. [!code-csharp[Conceptual.Strings.BestPractices#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.bestpractices/cs/indirect1.cs#9)] [!code-vb[Conceptual.Strings.BestPractices#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/indirect1.vb#9)] @@ -332,7 +332,7 @@ manager: "wpickett" ### Collections Example: Hashtable Constructor Hashing strings provides a second example of an operation that is affected by the way in which strings are compared. - The following example instantiates a object by passing it the object that is returned by the property. Because a class that is derived from implements the interface, its method is used to compute the hash code of strings in the hash table. + The following example instantiates a object by passing it the object that is returned by the property. Because a class that is derived from implements the interface, its method is used to compute the hash code of strings in the hash table. [!code-csharp[Conceptual.Strings.BestPractices#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.bestpractices/cs/indirect2.cs#10)] [!code-vb[Conceptual.Strings.BestPractices#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/indirect2.vb#10)] @@ -341,9 +341,9 @@ manager: "wpickett" ## Displaying and Persisting Formatted Data - When you display non-string data such as numbers and dates and times to users, format them by using the user's cultural settings. By default, the method and the `ToString` methods of the numeric types and the date and time types use the current thread culture for formatting operations. To explicitly specify that the formatting method should use the current culture, you can call an overload of a formatting method that has a `provider` parameter, such as or , and pass it the property. + When you display non-string data such as numbers and dates and times to users, format them by using the user's cultural settings. By default, the method and the `ToString` methods of the numeric types and the date and time types use the current thread culture for formatting operations. To explicitly specify that the formatting method should use the current culture, you can call an overload of a formatting method that has a `provider` parameter, such as or , and pass it the property. - You can persist non-string data either as binary data or as formatted data. If you choose to save it as formatted data, you should call a formatting method overload that includes a `provider` parameter and pass it the property. The invariant culture provides a consistent format for formatted data that is independent of culture and machine. In contrast, persisting data that is formatted by using cultures other than the invariant culture has a number of limitations: + You can persist non-string data either as binary data or as formatted data. If you choose to save it as formatted data, you should call a formatting method overload that includes a `provider` parameter and pass it the property. The invariant culture provides a consistent format for formatted data that is independent of culture and machine. In contrast, persisting data that is formatted by using cultures other than the invariant culture has a number of limitations: - The data is likely to be unusable if it is retrieved on a system that has a different culture, or if the user of the current system changes the current culture and tries to retrieve the data. @@ -356,7 +356,7 @@ manager: "wpickett" [!code-csharp[Conceptual.Strings.BestPractices#21](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.bestpractices/cs/persistence.cs#21)] [!code-vb[Conceptual.Strings.BestPractices#21](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.bestpractices/vb/persistence.vb#21)] - However, if you replace the property with in the calls to and , the persisted date and time data is successfully restored, as the following output shows. + However, if you replace the property with in the calls to and , the persisted date and time data is successfully restored, as the following output shows. ``` 06.05.1758 21:26 diff --git a/docs/standard/base-types/best-practices.md b/docs/standard/base-types/best-practices.md index 825ee8848e225..5e045bfe5d4a3 100644 --- a/docs/standard/base-types/best-practices.md +++ b/docs/standard/base-types/best-practices.md @@ -72,20 +72,20 @@ manager: "wpickett" ## Handle Object Instantiation Appropriately - At the heart of .NET’s regular expression object model is the class, which represents the regular expression engine. Often, the single greatest factor that affects regular expression performance is the way in which the engine is used. Defining a regular expression involves tightly coupling the regular expression engine with a regular expression pattern. That coupling process, whether it involves instantiating a object by passing its constructor a regular expression pattern or calling a static method by passing it the regular expression pattern along with the string to be analyzed, is by necessity an expensive one. + At the heart of .NET’s regular expression object model is the class, which represents the regular expression engine. Often, the single greatest factor that affects regular expression performance is the way in which the engine is used. Defining a regular expression involves tightly coupling the regular expression engine with a regular expression pattern. That coupling process, whether it involves instantiating a object by passing its constructor a regular expression pattern or calling a static method by passing it the regular expression pattern along with the string to be analyzed, is by necessity an expensive one. > [!NOTE] > For a more detailed discussion of the performance implications of using interpreted and compiled regular expressions, see [Optimizing Regular Expression Performance, Part II: Taking Charge of Backtracking](http://go.microsoft.com/fwlink/?LinkId=211566) in the BCL Team blog. You can couple the regular expression engine with a particular regular expression pattern and then use the engine to match text in several ways: -- You can call a static pattern-matching method, such as . This does not require instantiation of a regular expression object. +- You can call a static pattern-matching method, such as . This does not require instantiation of a regular expression object. - You can instantiate a object and call an instance pattern-matching method of an interpreted regular expression. This is the default method for binding the regular expression engine to a regular expression pattern. It results when a object is instantiated without an `options` argument that includes the flag. - You can instantiate a object and call an instance pattern-matching method of a compiled regular expression. Regular expression objects represent compiled patterns when a object is instantiated with an `options` argument that includes the flag. -- You can create a special-purpose object that is tightly coupled with a particular regular expression pattern, compile it, and save it to a standalone assembly. You do this by calling the method. +- You can create a special-purpose object that is tightly coupled with a particular regular expression pattern, compile it, and save it to a standalone assembly. You do this by calling the method. The particular way in which you call regular expression matching methods can have a significant impact on your application. The following sections discuss when to use static method calls, interpreted regular expressions, and compiled regular expressions to improve your application's performance. @@ -105,12 +105,12 @@ manager: "wpickett" [!code-csharp[Conceptual.RegularExpressions.BestPractices#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.bestpractices/cs/static1.cs#3)] [!code-vb[Conceptual.RegularExpressions.BestPractices#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.bestpractices/vb/static1.vb#3)] - You should replace this inefficient code with a call to the static method. This eliminates the need to instantiate a object each time you want to call a pattern-matching method, and enables the regular expression engine to retrieve a compiled version of the regular expression from its cache. + You should replace this inefficient code with a call to the static method. This eliminates the need to instantiate a object each time you want to call a pattern-matching method, and enables the regular expression engine to retrieve a compiled version of the regular expression from its cache. [!code-csharp[Conceptual.RegularExpressions.BestPractices#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.bestpractices/cs/static2.cs#4)] [!code-vb[Conceptual.RegularExpressions.BestPractices#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.bestpractices/vb/static2.vb#4)] - By default, the last 15 most recently used static regular expression patterns are cached. For applications that require a larger number of cached static regular expressions, the size of the cache can be adjusted by setting the property. + By default, the last 15 most recently used static regular expression patterns are cached. For applications that require a larger number of cached static regular expressions, the size of the cache can be adjusted by setting the property. The regular expression `\p{Sc}+\s*\d+` that is used in this example verifies that the input string consists of a currency symbol and at least one decimal digit. The pattern is defined as shown in the following table. @@ -147,7 +147,7 @@ manager: "wpickett" ### Regular Expressions: Compiled to an Assembly .NET also enables you to create an assembly that contains compiled regular expressions. This moves the performance hit of regular expression compilation from run time to design time. However, it also involves some additional work: You must define the regular expressions in advance and compile them to an assembly. The compiler can then reference this assembly when compiling source code that uses the assembly’s regular expressions. Each compiled regular expression in the assembly is represented by a class that derives from . - To compile regular expressions to an assembly, you call the method and pass it an array of objects that represent the regular expressions to be compiled, and an object that contains information about the assembly to be created. + To compile regular expressions to an assembly, you call the method and pass it an array of objects that represent the regular expressions to be compiled, and an object that contains information about the assembly to be created. We recommend that you compile regular expressions to an assembly in the following situations: @@ -232,13 +232,13 @@ manager: "wpickett" ## Use Time-out Values If your regular expressions processes input that nearly matches the regular expression pattern, it can often rely on excessive backtracking, which impacts its performance significantly. In addition to carefully considering your use of backtracking and testing the regular expression against near-matching input, you should always set a time-out value to ensure that the impact of excessive backtracking, if it occurs, is minimized. - The regular expression time-out interval defines the period of time that the regular expression engine will look for a single match before it times out. The default time-out interval is , which means that the regular expression will not time out. You can override this value and define a time-out interval as follows: + The regular expression time-out interval defines the period of time that the regular expression engine will look for a single match before it times out. The default time-out interval is , which means that the regular expression will not time out. You can override this value and define a time-out interval as follows: -- By providing a time-out value when you instantiate a object by calling the constructor. +- By providing a time-out value when you instantiate a object by calling the constructor. -- By calling a static pattern matching method, such as or , that includes a `matchTimeout` parameter. +- By calling a static pattern matching method, such as or , that includes a `matchTimeout` parameter. -- For compiled regular expressions that are created by calling the method, by calling the constructor that has a parameter of type . +- For compiled regular expressions that are created by calling the method, by calling the constructor that has a parameter of type . If you have defined a time-out interval and a match is not found at the end of that interval, the regular expression method throws a exception. In your exception handler, you can choose to retry the match with a longer time-out interval, abandon the match attempt and assume that there is no match, or abandon the match attempt and log the exception information for future analysis. @@ -253,9 +253,9 @@ manager: "wpickett" ## Capture Only When Necessary Regular expressions in .NET support a number of grouping constructs, which let you group a regular expression pattern into one or more subexpressions. The most commonly used grouping constructs in .NET regular expression language are `(`*subexpression*`)`, which defines a numbered capturing group, and `(?<`*name*`>`*subexpression*`)`, which defines a named capturing group. Grouping constructs are essential for creating backreferences and for defining a subexpression to which a quantifier is applied. - However, the use of these language elements has a cost. They cause the object returned by the property to be populated with the most recent unnamed or named captures, and if a single grouping construct has captured multiple substrings in the input string, they also populate the object returned by the property of a particular capturing group with multiple objects. + However, the use of these language elements has a cost. They cause the object returned by the property to be populated with the most recent unnamed or named captures, and if a single grouping construct has captured multiple substrings in the input string, they also populate the object returned by the property of a particular capturing group with multiple objects. - Often, grouping constructs are used in a regular expression only so that quantifiers can be applied to them, and the groups captured by these subexpressions are not subsequently used. For example, the regular expression `\b(\w+[;,]?\s?)+[.?!]` is designed to capture an entire sentence. The following table describes the language elements in this regular expression pattern and their effect on the object's and collections. + Often, grouping constructs are used in a regular expression only so that quantifiers can be applied to them, and the groups captured by these subexpressions are not subsequently used. For example, the regular expression `\b(\w+[;,]?\s?)+[.?!]` is designed to capture an entire sentence. The following table describes the language elements in this regular expression pattern and their effect on the object's and collections. |Pattern|Description| |-------------|-----------------| diff --git a/docs/standard/base-types/changing-case.md b/docs/standard/base-types/changing-case.md index aef083d970240..d4d1b0a3653c8 100644 --- a/docs/standard/base-types/changing-case.md +++ b/docs/standard/base-types/changing-case.md @@ -26,48 +26,48 @@ If you write an application that accepts input from a user, you can never be sur |Method name|Use| |-----------------|---------| -||Converts all characters in a string to uppercase.| -||Converts all characters in a string to lowercase.| -||Converts a string to title case.| +||Converts all characters in a string to uppercase.| +||Converts all characters in a string to lowercase.| +||Converts a string to title case.| > [!WARNING] -> Note that the and methods should not be used to convert strings in order to compare them or test them for equality. For more information, see the [Comparing strings of mixed case](#Comparing) section. +> Note that the and methods should not be used to convert strings in order to compare them or test them for equality. For more information, see the [Comparing strings of mixed case](#Comparing) section. ## Comparing strings of mixed case - To compare strings of mixed case to determine their ordering, call one of the overloads of the method with a `comparisonType` parameter, and provide a value of either , , or for the `comparisonType` argument. For a comparison using a specific culture other than the current culture, call an overload of the method with both a `culture` and `options` parameter, and provide a value of as the `options` argument. + To compare strings of mixed case to determine their ordering, call one of the overloads of the method with a `comparisonType` parameter, and provide a value of either , , or for the `comparisonType` argument. For a comparison using a specific culture other than the current culture, call an overload of the method with both a `culture` and `options` parameter, and provide a value of as the `options` argument. - To compare strings of mixed case to determine whether they are equal, their, call one of the overloads of the method with a `comparisonType` parameter, and provide a value of either , , or for the `comparisonType` argument. + To compare strings of mixed case to determine whether they are equal, their, call one of the overloads of the method with a `comparisonType` parameter, and provide a value of either , , or for the `comparisonType` argument. For more information, see [Best Practices for Using Strings](../../../docs/standard/base-types/best-practices-strings.md). ## ToUpper - The method changes all characters in a string to uppercase. The following example converts the string "Hello World!" from mixed case to uppercase. + The method changes all characters in a string to uppercase. The following example converts the string "Hello World!" from mixed case to uppercase. [!code-csharp[Strings.ChangingCase#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.ChangingCase/cs/Example.cs#1)] [!code-vb[Strings.ChangingCase#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.ChangingCase/vb/Example.vb#1)] - The preceding example is culture-sensitive by default; it applies the casing conventions of the current culture. To perform a culture-insensitive case change or to apply the casing conventions of a particular culture, use the method overload and supply a value of or a object that represents the specified culture to the *culture* parameter. For an example that demonstrates how to use the method to perform a culture-insensitive case change, see [Performing Culture-Insensitive Case Changes](../../../docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md). + The preceding example is culture-sensitive by default; it applies the casing conventions of the current culture. To perform a culture-insensitive case change or to apply the casing conventions of a particular culture, use the method overload and supply a value of or a object that represents the specified culture to the *culture* parameter. For an example that demonstrates how to use the method to perform a culture-insensitive case change, see [Performing Culture-Insensitive Case Changes](../../../docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md). ## ToLower - The method is similar to the previous method, but instead converts all the characters in a string to lowercase. The following example converts the string "Hello World!" to lowercase. + The method is similar to the previous method, but instead converts all the characters in a string to lowercase. The following example converts the string "Hello World!" to lowercase. [!code-csharp[Strings.ChangingCase#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.ChangingCase/cs/Example.cs#2)] [!code-vb[Strings.ChangingCase#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.ChangingCase/vb/Example.vb#2)] - The preceding example is culture-sensitive by default; it applies the casing conventions of the current culture. To perform a culture-insensitive case change or to apply the casing conventions of a particular culture, use the method overload and supply a value of or a object that represents the specified culture to the *culture* parameter. For an example that demonstrates how to use the method to perform a culture-insensitive case change, see [Performing Culture-Insensitive Case Changes](../../../docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md). + The preceding example is culture-sensitive by default; it applies the casing conventions of the current culture. To perform a culture-insensitive case change or to apply the casing conventions of a particular culture, use the method overload and supply a value of or a object that represents the specified culture to the *culture* parameter. For an example that demonstrates how to use the method to perform a culture-insensitive case change, see [Performing Culture-Insensitive Case Changes](../../../docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md). ## ToTitleCase - The converts the first character of each word to uppercase and the remaining characters to lowercase. However, words that are entirely uppercase are assumed to be acronyms and are not converted. + The converts the first character of each word to uppercase and the remaining characters to lowercase. However, words that are entirely uppercase are assumed to be acronyms and are not converted. - The method is culture-sensitive; that is, it uses the casing conventions of a particular culture. In order to call the method, you first retrieve the object that represents the casing conventions of the particular culture from the property of a particular culture. + The method is culture-sensitive; that is, it uses the casing conventions of a particular culture. In order to call the method, you first retrieve the object that represents the casing conventions of the particular culture from the property of a particular culture. - The following example passes each string in an array to the method. The strings include proper title strings as well as acronyms. The strings are converted to title case by using the casing conventions of the English (United States) culture. + The following example passes each string in an array to the method. The strings include proper title strings as well as acronyms. The strings are converted to title case by using the casing conventions of the English (United States) culture. [!code-csharp[System.Globalization.TextInfo.ToTitleCase#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.textinfo.totitlecase/cs/totitlecase2.cs#1)] [!code-vb[System.Globalization.TextInfo.ToTitleCase#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.textinfo.totitlecase/vb/totitlecase2.vb#1)] - Note that although it is culture-sensitive, the method does not provide linguistically correct casing rules. For instance, in the previous example, the method converts "a tale of two cities" to "A Tale Of Two Cities". However, the linguistically correct title casing for the en-US culture is "A Tale of Two Cities." + Note that although it is culture-sensitive, the method does not provide linguistically correct casing rules. For instance, in the previous example, the method converts "a tale of two cities" to "A Tale Of Two Cities". However, the linguistically correct title casing for the en-US culture is "A Tale of Two Cities." ## See Also [Basic String Operations](../../../docs/standard/base-types/basic-string-operations.md) diff --git a/docs/standard/base-types/character-classes-in-regular-expressions.md b/docs/standard/base-types/character-classes-in-regular-expressions.md index 4b44469631461..9d08bbfd535b5 100644 --- a/docs/standard/base-types/character-classes-in-regular-expressions.md +++ b/docs/standard/base-types/character-classes-in-regular-expressions.md @@ -157,9 +157,9 @@ manager: "wpickett" ## Any Character: . The period character (.) matches any character except `\n` (the newline character, \u000A), with the following two qualifications: -- If a regular expression pattern is modified by the option, or if the portion of the pattern that contains the `.` character class is modified by the `s` option, `.` matches any character. For more information, see [Regular Expression Options](../../../docs/standard/base-types/regular-expression-options.md). +- If a regular expression pattern is modified by the option, or if the portion of the pattern that contains the `.` character class is modified by the `s` option, `.` matches any character. For more information, see [Regular Expression Options](../../../docs/standard/base-types/regular-expression-options.md). - The following example illustrates the different behavior of the `.` character class by default and with the option. The regular expression `^.+` starts at the beginning of the string and matches every character. By default, the match ends at the end of the first line; the regular expression pattern matches the carriage return character, `\r` or \u000D, but it does not match `\n`. Because the option interprets the entire input string as a single line, it matches every character in the input string, including `\n`. + The following example illustrates the different behavior of the `.` character class by default and with the option. The regular expression `^.+` starts at the beginning of the string and matches every character. By default, the match ends at the end of the first line; the regular expression pattern matches the carriage return character, `\r` or \u000D, but it does not match `\n`. Because the option interprets the entire input string as a single line, it matches every character in the input string, including `\n`. [!code-csharp[Conceptual.Regex.Language.CharacterClasses#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.characterclasses/cs/any2.cs#5)] [!code-vb[Conceptual.Regex.Language.CharacterClasses#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.characterclasses/vb/any2.vb#5)] @@ -296,7 +296,7 @@ manager: "wpickett" [!code-csharp[Conceptual.RegEx.Language.CharacterClasses#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.characterclasses/cs/nonwordchar1.cs#9)] [!code-vb[Conceptual.RegEx.Language.CharacterClasses#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.characterclasses/vb/nonwordchar1.vb#9)] - Because the object for the second capturing group contains only a single captured non-word character, the example retrieves all captured non-word characters from the object that is returned by the property. + Because the object for the second capturing group contains only a single captured non-word character, the example retrieves all captured non-word characters from the object that is returned by the property. [Back to Top](#Top) diff --git a/docs/standard/base-types/character-encoding.md b/docs/standard/base-types/character-encoding.md index 005ce96a029cc..807ec1f18f7f7 100644 --- a/docs/standard/base-types/character-encoding.md +++ b/docs/standard/base-types/character-encoding.md @@ -28,7 +28,7 @@ Characters are abstract entities that can be represented in many different ways. Character encoding describes the rules by which an encoder and a decoder operate. For example, the class describes the rules for encoding to, and decoding from, 8-bit Unicode Transformation Format (UTF-8), which uses one to four bytes to represent a single Unicode character. Encoding and decoding can also include validation. For example, the class checks all surrogates to make sure they constitute valid surrogate pairs. (A surrogate pair consists of a character with a code point that ranges from U+D800 to U+DBFF followed by a character with a code point that ranges from U+DC00 to U+DFFF.) A fallback strategy determines how an encoder handles invalid characters or how a decoder handles invalid bytes. > [!WARNING] -> .NET encoding classes provide a way to store and convert character data. They should not be used to store binary data in string form. Depending on the encoding used, converting binary data to string format with the encoding classes can introduce unexpected behavior and produce inaccurate or corrupted data. To convert binary data to a string form, use the method. +> .NET encoding classes provide a way to store and convert character data. They should not be used to store binary data in string form. Depending on the encoding used, converting binary data to string format with the encoding classes can introduce unexpected behavior and produce inaccurate or corrupted data. To convert binary data to a string form, use the method. .NET uses the UTF-16 encoding (represented by the class) to represent characters and strings. Applications that target the common language runtime use encoders to map Unicode character representations supported by the common language runtime to other encoding schemes. They use decoders to map characters from non-Unicode encodings to Unicode. @@ -46,22 +46,22 @@ Characters are abstract entities that can be represented in many different ways. ## Encodings in .NET - All character encoding classes in .NET inherit from the class, which is an abstract class that defines the functionality common to all character encodings. To access the individual encoding objects implemented in .NET, do the following: + All character encoding classes in .NET inherit from the class, which is an abstract class that defines the functionality common to all character encodings. To access the individual encoding objects implemented in .NET, do the following: -- Use the static properties of the class, which return objects that represent the standard character encodings available in .NET (ASCII, UTF-7, UTF-8, UTF-16, and UTF-32). For example, the property returns a object. Each object uses replacement fallback to handle strings that it cannot encode and bytes that it cannot decode. (For more information, see the [Replacement Fallback](../../../docs/standard/base-types/character-encoding.md#Replacement) section.) +- Use the static properties of the class, which return objects that represent the standard character encodings available in .NET (ASCII, UTF-7, UTF-8, UTF-16, and UTF-32). For example, the property returns a object. Each object uses replacement fallback to handle strings that it cannot encode and bytes that it cannot decode. (For more information, see the [Replacement Fallback](../../../docs/standard/base-types/character-encoding.md#Replacement) section.) - Call the encoding's class constructor. Objects for the ASCII, UTF-7, UTF-8, UTF-16, and UTF-32 encodings can be instantiated in this way. By default, each object uses replacement fallback to handle strings that it cannot encode and bytes that it cannot decode, but you can specify that an exception should be thrown instead. (For more information, see the [Replacement Fallback](../../../docs/standard/base-types/character-encoding.md#Replacement) and [Exception Fallback](../../../docs/standard/base-types/character-encoding.md#Exception) sections.) -- Call the constructor and pass it an integer that represents the encoding. Standard encoding objects use replacement fallback, and code page and double-byte character set (DBCS) encoding objects use best-fit fallback to handle strings that they cannot encode and bytes that they cannot decode. (For more information, see the [Best-Fit Fallback](../../../docs/standard/base-types/character-encoding.md#BestFit) section.) +- Call the constructor and pass it an integer that represents the encoding. Standard encoding objects use replacement fallback, and code page and double-byte character set (DBCS) encoding objects use best-fit fallback to handle strings that they cannot encode and bytes that they cannot decode. (For more information, see the [Best-Fit Fallback](../../../docs/standard/base-types/character-encoding.md#BestFit) section.) -- Call the method, which returns any standard, code page, or DBCS encoding available in .NET. Overloads let you specify a fallback object for both the encoder and the decoder. +- Call the method, which returns any standard, code page, or DBCS encoding available in .NET. Overloads let you specify a fallback object for both the encoder and the decoder. > [!NOTE] > The Unicode Standard assigns a code point (a number) and a name to each character in every supported script. For example, the character "A" is represented by the code point U+0041 and the name "LATIN CAPITAL LETTER A". The Unicode Transformation Format (UTF) encodings define ways to encode that code point into a sequence of one or more bytes. A Unicode encoding scheme simplifies world-ready application development because it allows characters from any character set to be represented in a single encoding. Application developers no longer have to keep track of the encoding scheme that was used to produce characters for a specific language or writing system, and data can be shared among systems internationally without being corrupted. > > .NET supports three encodings defined by the Unicode standard: UTF-8, UTF-16, and UTF-32. For more information, see The Unicode Standard at the [Unicode home page](http://go.microsoft.com/fwlink/?LinkId=37123). - You can retrieve information about all the encodings available in .NET by calling the method. .NET supports the character encoding systems listed in the following table. + You can retrieve information about all the encodings available in .NET by calling the method. .NET supports the character encoding systems listed in the following table. |Encoding|Class|Description|Advantages/disadvantages| |--------------|-----------|-----------------|-------------------------------| @@ -70,8 +70,8 @@ Characters are abstract entities that can be represented in many different ways. |UTF-8||Represents each Unicode code point as a sequence of one to four bytes.|UTF-8 supports 8-bit data sizes and works well with many existing operating systems. For the ASCII range of characters, UTF-8 is identical to ASCII encoding and allows a broader set of characters. However, for Chinese-Japanese-Korean (CJK) scripts, UTF-8 can require three bytes for each character, and can potentially cause larger data sizes than UTF-16. Note that sometimes the amount of ASCII data, such as HTML tags, justifies the increased size for the CJK range.| |UTF-16||Represents each Unicode code point as a sequence of one or two 16-bit integers. Most common Unicode characters require only one UTF-16 code point, although Unicode supplementary characters (U+10000 and greater) require two UTF-16 surrogate code points. Both little-endian and big-endian byte orders are supported.|UTF-16 encoding is used by the common language runtime to represent and values, and it is used by the Windows operating system to represent `WCHAR` values.| |UTF-32||Represents each Unicode code point as a 32-bit integer. Both little-endian and big-endian byte orders are supported.|UTF-32 encoding is used when applications want to avoid the surrogate code point behavior of UTF-16 encoding on operating systems for which encoded space is too important. Single glyphs rendered on a display can still be encoded with more than one UTF-32 character.| -|ANSI/ISO encodings||Provides support for a variety of code pages. On Windows operating systems, code pages are used to support a specific language or group of languages. For a table that lists the code pages supported by .NET, see the class. You can retrieve an encoding object for a particular code page by calling the method.|A code page contains 256 code points and is zero-based. In most code pages, code points 0 through 127 represent the ASCII character set, and code points 128 through 255 differ significantly between code pages. For example, code page 1252 provides the characters for Latin writing systems, including English, German, and French. The last 128 code points in code page 1252 contain the accent characters. Code page 1253 provides character codes that are required in the Greek writing system. The last 128 code points in code page 1253 contain the Greek characters. As a result, an application that relies on ANSI code pages cannot store Greek and German in the same text stream unless it includes an identifier that indicates the referenced code page.| -|Double-byte character set (DBCS) encodings||Supports languages, such as Chinese, Japanese, and Korean, that contain more than 256 characters. In a DBCS, a pair of code points (a double byte) represents each character. The property returns `false` for DBCS encodings. You can retrieve an encoding object for a particular DBCS by calling the method.|In a DBCS, a pair of code points (a double byte) represents each character. When an application handles DBCS data, the first byte of a DBCS character (the lead byte) is processed in combination with the trail byte that immediately follows it. Because a single pair of double-byte code points can represent different characters depending on the code page, this scheme still does not allow for the combination of two languages, such as Japanese and Chinese, in the same data stream.| +|ANSI/ISO encodings||Provides support for a variety of code pages. On Windows operating systems, code pages are used to support a specific language or group of languages. For a table that lists the code pages supported by .NET, see the class. You can retrieve an encoding object for a particular code page by calling the method.|A code page contains 256 code points and is zero-based. In most code pages, code points 0 through 127 represent the ASCII character set, and code points 128 through 255 differ significantly between code pages. For example, code page 1252 provides the characters for Latin writing systems, including English, German, and French. The last 128 code points in code page 1252 contain the accent characters. Code page 1253 provides character codes that are required in the Greek writing system. The last 128 code points in code page 1253 contain the Greek characters. As a result, an application that relies on ANSI code pages cannot store Greek and German in the same text stream unless it includes an identifier that indicates the referenced code page.| +|Double-byte character set (DBCS) encodings||Supports languages, such as Chinese, Japanese, and Korean, that contain more than 256 characters. In a DBCS, a pair of code points (a double byte) represents each character. The property returns `false` for DBCS encodings. You can retrieve an encoding object for a particular DBCS by calling the method.|In a DBCS, a pair of code points (a double byte) represents each character. When an application handles DBCS data, the first byte of a DBCS character (the lead byte) is processed in combination with the trail byte that immediately follows it. Because a single pair of double-byte code points can represent different characters depending on the code page, this scheme still does not allow for the combination of two languages, such as Japanese and Chinese, in the same data stream.| These encodings enable you to work with Unicode characters as well as with encodings that are most commonly used in legacy applications. In addition, you can create a custom encoding by defining a class that derives from and overriding its members. @@ -96,29 +96,29 @@ Characters are abstract entities that can be represented in many different ways. - If your application has content that is not strictly ASCII and encodes it with , the result seems unintelligible if interpreted as ASCII. However, if the application then uses a UTF-8 decoder to decode this data, the data performs a round trip successfully. - In a web application, characters sent to the client in response to a web request should reflect the encoding used on the client. In most cases, you should set the property to the value returned by the property to display text in the encoding that the user expects. + In a web application, characters sent to the client in response to a web request should reflect the encoding used on the client. In most cases, you should set the property to the value returned by the property to display text in the encoding that the user expects. ## Using an Encoding Object - An encoder converts a string of characters (most commonly, Unicode characters) to its numeric (byte) equivalent. For example, you might use an ASCII encoder to convert Unicode characters to ASCII so that they can be displayed at the console. To perform the conversion, you call the method. If you want to determine how many bytes are needed to store the encoded characters before performing the encoding, you can call the method. + An encoder converts a string of characters (most commonly, Unicode characters) to its numeric (byte) equivalent. For example, you might use an ASCII encoder to convert Unicode characters to ASCII so that they can be displayed at the console. To perform the conversion, you call the method. If you want to determine how many bytes are needed to store the encoded characters before performing the encoding, you can call the method. - The following example uses a single byte array to encode strings in two separate operations. It maintains an index that indicates the starting position in the byte array for the next set of ASCII-encoded bytes. It calls the method to ensure that the byte array is large enough to accommodate the encoded string. It then calls the method to encode the characters in the string. + The following example uses a single byte array to encode strings in two separate operations. It maintains an index that indicates the starting position in the byte array for the next set of ASCII-encoded bytes. It calls the method to ensure that the byte array is large enough to accommodate the encoded string. It then calls the method to encode the characters in the string. [!code-csharp[Conceptual.Encoding#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/getbytes1.cs#8)] [!code-vb[Conceptual.Encoding#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/getbytes1.vb#8)] - A decoder converts a byte array that reflects a particular character encoding into a set of characters, either in a character array or in a string. To decode a byte array into a character array, you call the method. To decode a byte array into a string, you call the method. If you want to determine how many characters are needed to store the decoded bytes before performing the decoding, you can call the method. + A decoder converts a byte array that reflects a particular character encoding into a set of characters, either in a character array or in a string. To decode a byte array into a character array, you call the method. To decode a byte array into a string, you call the method. If you want to determine how many characters are needed to store the decoded bytes before performing the decoding, you can call the method. - The following example encodes three strings and then decodes them into a single array of characters. It maintains an index that indicates the starting position in the character array for the next set of decoded characters. It calls the method to ensure that the character array is large enough to accommodate all the decoded characters. It then calls the method to decode the byte array. + The following example encodes three strings and then decodes them into a single array of characters. It maintains an index that indicates the starting position in the character array for the next set of decoded characters. It calls the method to ensure that the character array is large enough to accommodate all the decoded characters. It then calls the method to decode the byte array. [!code-csharp[Conceptual.Encoding#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/getchars1.cs#9)] [!code-vb[Conceptual.Encoding#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/getchars1.vb#9)] The encoding and decoding methods of a class derived from are designed to work on a complete set of data; that is, all the data to be encoded or decoded is supplied in a single method call. However, in some cases, data is available in a stream, and the data to be encoded or decoded may be available only from separate read operations. This requires the encoding or decoding operation to remember any saved state from its previous invocation. Methods of classes derived from and are able to handle encoding and decoding operations that span multiple method calls. - An object for a particular encoding is available from that encoding's property. A object for a particular encoding is available from that encoding's property. For decoding operations, note that classes derived from include a method, but they do not have a method that corresponds to . + An object for a particular encoding is available from that encoding's property. A object for a particular encoding is available from that encoding's property. For decoding operations, note that classes derived from include a method, but they do not have a method that corresponds to . - The following example illustrates the difference between using the and methods for decoding a Unicode byte array. The example encodes a string that contains some Unicode characters to a file, and then uses the two decoding methods to decode them ten bytes at a time. Because a surrogate pair occurs in the tenth and eleventh bytes, it is decoded in separate method calls. As the output shows, the method is not able to correctly decode the bytes and instead replaces them with U+FFFD (REPLACEMENT CHARACTER). On the other hand, the method is able to successfully decode the byte array to get the original string. + The following example illustrates the difference between using the and methods for decoding a Unicode byte array. The example encodes a string that contains some Unicode characters to a file, and then uses the two decoding methods to decode them ten bytes at a time. Because a surrogate pair occurs in the tenth and eleventh bytes, it is decoded in separate method calls. As the output shows, the method is not able to correctly decode the bytes and instead replaces them with U+FFFD (REPLACEMENT CHARACTER). On the other hand, the method is able to successfully decode the byte array to get the original string. [!code-csharp[Conceptual.Encoding#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/stream1.cs#10)] [!code-vb[Conceptual.Encoding#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/stream1.vb#10)] @@ -138,14 +138,14 @@ Characters are abstract entities that can be represented in many different ways. ### Best-Fit Fallback - When a character does not have an exact match in the target encoding, the encoder can try to map it to a similar character. (Best-fit fallback is mostly an encoding rather than a decoding issue. There are very few code pages that contain characters that cannot be successfully mapped to Unicode.) Best-fit fallback is the default for code page and double-byte character set encodings that are retrieved by the and overloads. + When a character does not have an exact match in the target encoding, the encoder can try to map it to a similar character. (Best-fit fallback is mostly an encoding rather than a decoding issue. There are very few code pages that contain characters that cannot be successfully mapped to Unicode.) Best-fit fallback is the default for code page and double-byte character set encodings that are retrieved by the and overloads. > [!NOTE] > In theory, the Unicode encoding classes provided in .NET (, , and ) support every character in every character set, so they can be used to eliminate best-fit fallback issues. Best-fit strategies vary for different code pages, and they are not documented in detail. For example, for some code pages, full-width Latin characters map to the more common half-width Latin characters. For other code pages, this mapping is not made. Even under an aggressive best-fit strategy, there is no imaginable fit for some characters in some encodings. For example, a Chinese ideograph has no reasonable mapping to code page 1252. In this case, a replacement string is used. By default, this string is just a single QUESTION MARK (U+003F). - The following example uses code page 1252 (the Windows code page for Western European languages) to illustrate best-fit mapping and its drawbacks. The method is used to retrieve an encoding object for code page 1252. By default, it uses a best-fit mapping for Unicode characters that it does not support. The example instantiates a string that contains three non-ASCII characters - CIRCLED LATIN CAPITAL LETTER S (U+24C8), SUPERSCRIPT FIVE (U+2075), and INFINITY (U+221E) - separated by spaces. As the output from the example shows, when the string is encoded, the three original non-space characters are replaced by QUESTION MARK (U+003F), DIGIT FIVE (U+0035), and DIGIT EIGHT (U+0038). DIGIT EIGHT is a particularly poor replacement for the unsupported INFINITY character, and QUESTION MARK indicates that no mapping was available for the original character. + The following example uses code page 1252 (the Windows code page for Western European languages) to illustrate best-fit mapping and its drawbacks. The method is used to retrieve an encoding object for code page 1252. By default, it uses a best-fit mapping for Unicode characters that it does not support. The example instantiates a string that contains three non-ASCII characters - CIRCLED LATIN CAPITAL LETTER S (U+24C8), SUPERSCRIPT FIVE (U+2075), and INFINITY (U+221E) - separated by spaces. As the output from the example shows, when the string is encoded, the three original non-space characters are replaced by QUESTION MARK (U+003F), DIGIT FIVE (U+0035), and DIGIT EIGHT (U+0038). DIGIT EIGHT is a particularly poor replacement for the unsupported INFINITY character, and QUESTION MARK indicates that no mapping was available for the original character. [!code-csharp[Conceptual.Encoding#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/bestfit1.cs#1)] [!code-vb[Conceptual.Encoding#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/bestfit1.vb#1)] @@ -155,7 +155,7 @@ Characters are abstract entities that can be represented in many different ways. > [!NOTE] > You can also implement a custom best-fit fallback mapping for an encoding. For more information, see the [Implementing a Custom Fallback Strategy](../../../docs/standard/base-types/character-encoding.md#Custom) section. - If best-fit fallback is the default for an encoding object, you can choose another fallback strategy when you retrieve an object by calling the or overload. The following section includes an example that replaces each character that cannot be mapped to code page 1252 with an asterisk (*). + If best-fit fallback is the default for an encoding object, you can choose another fallback strategy when you retrieve an object by calling the or overload. The following section includes an example that replaces each character that cannot be mapped to code page 1252 with an asterisk (*). [!code-csharp[Conceptual.Encoding#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/bestfit1a.cs#3)] [!code-vb[Conceptual.Encoding#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/bestfit1a.vb#3)] @@ -179,7 +179,7 @@ Characters are abstract entities that can be represented in many different ways. ### Exception Fallback - Instead of providing a best-fit fallback or a replacement string, an encoder can throw an if it is unable to encode a set of characters, and a decoder can throw a if it is unable to decode a byte array. To throw an exception in encoding and decoding operations, you supply an object and a object, respectively, to the method. The following example illustrates exception fallback with the class. + Instead of providing a best-fit fallback or a replacement string, an encoder can throw an if it is unable to encode a set of characters, and a decoder can throw a if it is unable to decode a byte array. To throw an exception in encoding and decoding operations, you supply an object and a object, respectively, to the method. The following example illustrates exception fallback with the class. [!code-csharp[Conceptual.Encoding#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/exceptionascii.cs#4)] [!code-vb[Conceptual.Encoding#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/exceptionascii.vb#4)] @@ -189,9 +189,9 @@ Characters are abstract entities that can be represented in many different ways. The and objects provide the following information about the condition that caused the exception: -- The object includes an method, which indicates whether the character or characters that cannot be encoded represent an unknown surrogate pair (in which case, the method returns `true`) or an unknown single character (in which case, the method returns `false`). The characters in the surrogate pair are available from the and properties. The unknown single character is available from the property. The property indicates the position in the string at which the first character that could not be encoded was found. +- The object includes an method, which indicates whether the character or characters that cannot be encoded represent an unknown surrogate pair (in which case, the method returns `true`) or an unknown single character (in which case, the method returns `false`). The characters in the surrogate pair are available from the and properties. The unknown single character is available from the property. The property indicates the position in the string at which the first character that could not be encoded was found. -- The object includes a property that returns an array of bytes that cannot be decoded. The property indicates the starting position of the unknown bytes. +- The object includes a property that returns an array of bytes that cannot be decoded. The property indicates the starting position of the unknown bytes. Although the and objects provide adequate diagnostic information about the exception, they do not provide access to the encoding or decoding buffer. Therefore, they do not allow invalid data to be replaced or corrected within the encoding or decoding method. @@ -216,28 +216,28 @@ Characters are abstract entities that can be represented in many different ways. 3. For exception fallback, if the predefined and classes do not meet your needs, derive a class from an exception object such as or . ### Deriving from EncoderFallback or DecoderFallback - To implement a custom fallback solution, you must create a class that inherits from for encoding operations, and from for decoding operations. Instances of these classes are passed to the method and serve as the intermediary between the encoding class and the fallback implementation. + To implement a custom fallback solution, you must create a class that inherits from for encoding operations, and from for decoding operations. Instances of these classes are passed to the method and serve as the intermediary between the encoding class and the fallback implementation. When you create a custom fallback solution for an encoder or decoder, you must implement the following members: -- The or property, which returns the maximum possible number of characters that the best-fit, replacement, or exception fallback can return to replace a single character. For a custom exception fallback, its value is zero. +- The or property, which returns the maximum possible number of characters that the best-fit, replacement, or exception fallback can return to replace a single character. For a custom exception fallback, its value is zero. -- The or method, which returns your custom or implementation. The method is called by the encoder when it encounters the first character that it is unable to successfully encode, or by the decoder when it encounters the first byte that it is unable to successfully decode. +- The or method, which returns your custom or implementation. The method is called by the encoder when it encounters the first character that it is unable to successfully encode, or by the decoder when it encounters the first byte that it is unable to successfully decode. ### Deriving from EncoderFallbackBuffer or DecoderFallbackBuffer - To implement a custom fallback solution, you must also create a class that inherits from for encoding operations, and from for decoding operations. Instances of these classes are returned by the method of the and classes. The method is called by the encoder when it encounters the first character that it is not able to encode, and the method is called by the decoder when it encounters one or more bytes that it is not able to decode. The and classes provide the fallback implementation. Each instance represents a buffer that contains the fallback characters that will replace the character that cannot be encoded or the byte sequence that cannot be decoded. + To implement a custom fallback solution, you must also create a class that inherits from for encoding operations, and from for decoding operations. Instances of these classes are returned by the method of the and classes. The method is called by the encoder when it encounters the first character that it is not able to encode, and the method is called by the decoder when it encounters one or more bytes that it is not able to decode. The and classes provide the fallback implementation. Each instance represents a buffer that contains the fallback characters that will replace the character that cannot be encoded or the byte sequence that cannot be decoded. When you create a custom fallback solution for an encoder or decoder, you must implement the following members: -- The or method. is called by the encoder to provide the fallback buffer with information about the character that it cannot encode. Because the character to be encoded may be a surrogate pair, this method is overloaded. One overload is passed the character to be encoded and its index in the string. The second overload is passed the high and low surrogate along with its index in the string. The method is called by the decoder to provide the fallback buffer with information about the bytes that it cannot decode. This method is passed an array of bytes that it cannot decode, along with the index of the first byte. The fallback method should return `true` if the fallback buffer can supply a best-fit or replacement character or characters; otherwise, it should return `false`. For an exception fallback, the fallback method should throw an exception. +- The or method. is called by the encoder to provide the fallback buffer with information about the character that it cannot encode. Because the character to be encoded may be a surrogate pair, this method is overloaded. One overload is passed the character to be encoded and its index in the string. The second overload is passed the high and low surrogate along with its index in the string. The method is called by the decoder to provide the fallback buffer with information about the bytes that it cannot decode. This method is passed an array of bytes that it cannot decode, along with the index of the first byte. The fallback method should return `true` if the fallback buffer can supply a best-fit or replacement character or characters; otherwise, it should return `false`. For an exception fallback, the fallback method should throw an exception. -- The or method, which is called repeatedly by the encoder or decoder to get the next character from the fallback buffer. When all fallback characters have been returned, the method should return U+0000. +- The or method, which is called repeatedly by the encoder or decoder to get the next character from the fallback buffer. When all fallback characters have been returned, the method should return U+0000. -- The or property, which returns the number of characters remaining in the fallback buffer. +- The or property, which returns the number of characters remaining in the fallback buffer. -- The or method, which moves the current position in the fallback buffer to the previous character. +- The or method, which moves the current position in the fallback buffer to the previous character. -- The or method, which reinitializes the fallback buffer. +- The or method, which reinitializes the fallback buffer. If the fallback implementation is a best-fit fallback or a replacement fallback, the classes derived from and also maintain two private instance fields: the exact number of characters in the buffer; and the index of the next character in the buffer to return. @@ -254,7 +254,7 @@ Characters are abstract entities that can be represented in many different ways. [!code-csharp[Conceptual.Encoding#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/custom1.cs#6)] [!code-vb[Conceptual.Encoding#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/custom1.vb#6)] - The following code then instantiates the `CustomMapper` object and passes an instance of it to the method. The output indicates that the best-fit fallback implementation successfully handles the three non-ASCII characters in the original string. + The following code then instantiates the `CustomMapper` object and passes an instance of it to the method. The output indicates that the best-fit fallback implementation successfully handles the three non-ASCII characters in the original string. [!code-csharp[Conceptual.Encoding#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.encoding/cs/custom1.cs#7)] [!code-vb[Conceptual.Encoding#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.encoding/vb/custom1.vb#7)] diff --git a/docs/standard/base-types/common-type-system.md b/docs/standard/base-types/common-type-system.md index e6153248ed947..0d23677e97ac5 100644 --- a/docs/standard/base-types/common-type-system.md +++ b/docs/standard/base-types/common-type-system.md @@ -66,7 +66,7 @@ The common type system defines how types are declared, used, and managed in the ### Classes - A class is a reference type that can be derived directly from another class and that is derived implicitly from . The class defines the operations that an object (which is an instance of the class) can perform (methods, events, or properties) and the data that the object contains (fields). Although a class generally includes both definition and implementation (unlike interfaces, for example, which contain only definition without implementation), it can have one or more members that have no implementation. + A class is a reference type that can be derived directly from another class and that is derived implicitly from . The class defines the operations that an object (which is an instance of the class) can perform (methods, events, or properties) and the data that the object contains (fields). Although a class generally includes both definition and implementation (unlike interfaces, for example, which contain only definition without implementation), it can have one or more members that have no implementation. The following table describes some of the characteristics that a class may have. Each language that supports the runtime provides a way to indicate that a class or class member has one or more of these characteristics. However, individual programming languages that target .NET may not make all these characteristics available. @@ -83,23 +83,23 @@ The common type system defines how types are declared, used, and managed in the Class members that have no implementation are abstract members. A class that has one or more abstract members is itself abstract; new instances of it cannot be created. Some languages that target the runtime let you mark a class as abstract even if none of its members are abstract. You can use an abstract class when you want to encapsulate a basic set of functionality that derived classes can inherit or override when appropriate. Classes that are not abstract are referred to as concrete classes. - A class can implement any number of interfaces, but it can inherit from only one base class in addition to , from which all classes inherit implicitly. All classes must have at least one constructor, which initializes new instances of the class. If you do not explicitly define a constructor, most compilers will automatically provide a default (parameterless) constructor. + A class can implement any number of interfaces, but it can inherit from only one base class in addition to , from which all classes inherit implicitly. All classes must have at least one constructor, which initializes new instances of the class. If you do not explicitly define a constructor, most compilers will automatically provide a default (parameterless) constructor. ### Structures - A structure is a value type that derives implicitly from , which in turn is derived from . A structure is very useful for representing values whose memory requirements are small, and for passing values as by-value parameters to methods that have strongly typed parameters. In .NET, all primitive data types (, , , , , , , , , , , , , and ) are defined as structures. + A structure is a value type that derives implicitly from , which in turn is derived from . A structure is very useful for representing values whose memory requirements are small, and for passing values as by-value parameters to methods that have strongly typed parameters. In .NET, all primitive data types (, , , , , , , , , , , , , and ) are defined as structures. - Like classes, structures define both data (the fields of the structure) and the operations that can be performed on that data (the methods of the structure). This means that you can call methods on structures, including the virtual methods defined on the and classes, and any methods defined on the value type itself. In other words, structures can have fields, properties, and events, as well as static and nonstatic methods. You can create instances of structures, pass them as parameters, store them as local variables, or store them in a field of another value type or reference type. Structures can also implement interfaces. + Like classes, structures define both data (the fields of the structure) and the operations that can be performed on that data (the methods of the structure). This means that you can call methods on structures, including the virtual methods defined on the and classes, and any methods defined on the value type itself. In other words, structures can have fields, properties, and events, as well as static and nonstatic methods. You can create instances of structures, pass them as parameters, store them as local variables, or store them in a field of another value type or reference type. Structures can also implement interfaces. - Value types also differ from classes in several respects. First, although they implicitly inherit from , they cannot directly inherit from any type. Similarly, all value types are sealed, which means that no other type can be derived from them. They also do not require constructors. + Value types also differ from classes in several respects. First, although they implicitly inherit from , they cannot directly inherit from any type. Similarly, all value types are sealed, which means that no other type can be derived from them. They also do not require constructors. - For each value type, the common language runtime supplies a corresponding boxed type, which is a class that has the same state and behavior as the value type. An instance of a value type is boxed when it is passed to a method that accepts a parameter of type . It is unboxed (that is, converted from an instance of a class back to an instance of a value type) when control returns from a method call that accepts a value type as a by-reference parameter. Some languages require that you use special syntax when the boxed type is required; others automatically use the boxed type when it is needed. When you define a value type, you are defining both the boxed and the unboxed type. + For each value type, the common language runtime supplies a corresponding boxed type, which is a class that has the same state and behavior as the value type. An instance of a value type is boxed when it is passed to a method that accepts a parameter of type . It is unboxed (that is, converted from an instance of a class back to an instance of a value type) when control returns from a method call that accepts a value type as a by-reference parameter. Some languages require that you use special syntax when the boxed type is required; others automatically use the boxed type when it is needed. When you define a value type, you are defining both the boxed and the unboxed type. ### Enumerations - An enumeration (enum) is a value type that inherits directly from and that supplies alternate names for the values of an underlying primitive type. An enumeration type has a name, an underlying type that must be one of the built-in signed or unsigned integer types (such as , , or ), and a set of fields. The fields are static literal fields, each of which represents a constant. The same value can be assigned to multiple fields. When this occurs, you must mark one of the values as the primary enumeration value for reflection and string conversion. + An enumeration (enum) is a value type that inherits directly from and that supplies alternate names for the values of an underlying primitive type. An enumeration type has a name, an underlying type that must be one of the built-in signed or unsigned integer types (such as , , or ), and a set of fields. The fields are static literal fields, each of which represents a constant. The same value can be assigned to multiple fields. When this occurs, you must mark one of the values as the primary enumeration value for reflection and string conversion. - You can assign a value of the underlying type to an enumeration and vice versa (no cast is required by the runtime). You can create an instance of an enumeration and call the methods of , as well as any methods defined on the enumeration's underlying type. However, some languages might not let you pass an enumeration as a parameter when an instance of the underlying type is required (or vice versa). + You can assign a value of the underlying type to an enumeration and vice versa (no cast is required by the runtime). You can create an instance of an enumeration and call the methods of , as well as any methods defined on the enumeration's underlying type. However, some languages might not let you pass an enumeration as a parameter when an instance of the underlying type is required (or vice versa). The following additional restrictions apply to enumerations: @@ -112,7 +112,7 @@ The common type system defines how types are declared, used, and managed in the - They cannot be generic, unless they are generic only because they are nested within a generic type. That is, an enumeration cannot have type parameters of its own. > [!NOTE] - > Nested types (including enumerations) created with Visual Basic, C#, and C++ include the type parameters of all enclosing generic types, and are therefore generic even if they do not have type parameters of their own. For more information, see "Nested Types" in the reference topic. + > Nested types (including enumerations) created with Visual Basic, C#, and C++ include the type parameters of all enclosing generic types, and are therefore generic even if they do not have type parameters of their own. For more information, see "Nested Types" in the reference topic. The attribute denotes a special kind of enumeration called a bit field. The runtime itself does not distinguish between traditional enumerations and bit fields, but your language might do so. When this distinction is made, bitwise operators can be used on bit fields, but not on enumerations, to generate unnamed values. Enumerations are generally used for lists of unique elements, such as days of the week, country or region names, and so on. Bit fields are generally used for lists of qualities or quantities that might occur in combination, such as `Red And Big And Fast`. @@ -145,11 +145,11 @@ The common type system defines how types are declared, used, and managed in the Similarly, the return type of a delegate is compatible with the return type of a method if the return type of the method is more restrictive than the return type of the delegate, because this guarantees that the return value of the method can be cast safely to the return type of the delegate. - For example, a delegate that has a parameter of type and a return type of can represent a method that has a parameter of type and a return value of type . For more information and example code, see . + For example, a delegate that has a parameter of type and a return type of can represent a method that has a parameter of type and a return value of type . For more information and example code, see . - A delegate is said to be bound to the method it represents. In addition to being bound to the method, a delegate can be bound to an object. The object represents the first parameter of the method, and is passed to the method every time the delegate is invoked. If the method is an instance method, the bound object is passed as the implicit `this` parameter (`Me` in Visual Basic); if the method is static, the object is passed as the first formal parameter of the method, and the delegate signature must match the remaining parameters. For more information and example code, see . + A delegate is said to be bound to the method it represents. In addition to being bound to the method, a delegate can be bound to an object. The object represents the first parameter of the method, and is passed to the method every time the delegate is invoked. If the method is an instance method, the bound object is passed as the implicit `this` parameter (`Me` in Visual Basic); if the method is static, the object is passed as the first formal parameter of the method, and the delegate signature must match the remaining parameters. For more information and example code, see . - All delegates inherit from , which inherits from . The C#, Visual Basic, and C++ languages do not allow inheritance from these types. Instead, they provide keywords for declaring delegates. + All delegates inherit from , which inherits from . The C#, Visual Basic, and C++ languages do not allow inheritance from these types. Instead, they provide keywords for declaring delegates. Because delegates inherit from , a delegate has an invocation list, which is a list of methods that the delegate represents and that are executed when the delegate is invoked. All methods in the list receive the arguments supplied when the delegate is invoked. @@ -158,7 +158,7 @@ The common type system defines how types are declared, used, and managed in the In many cases, such as with callback methods, a delegate represents only one method, and the only actions you have to take are creating the delegate and invoking it. - For delegates that represent multiple methods, .NET provides methods of the and delegate classes to support operations such as adding a method to a delegate's invocation list (the method), removing a method (the method), and getting the invocation list (the method). + For delegates that represent multiple methods, .NET provides methods of the and delegate classes to support operations such as adding a method to a delegate's invocation list (the method), removing a method (the method), and getting the invocation list (the method). > [!NOTE] > It is not necessary to use these methods for event-handler delegates in C#, C++, and Visual Basic, because these languages provide syntax for adding and removing event handlers. @@ -184,7 +184,7 @@ The common type system defines how types are declared, used, and managed in the ### Attributes Attributes provide additional user-defined metadata. Most commonly, they are used to store additional information about a type in its assembly, or to modify the behavior of a type member in either the design-time or run-time environment. - Attributes are themselves classes that inherit from . Languages that support the use of attributes each have their own syntax for applying attributes to a language element. Attributes can be applied to almost any language element; the specific elements to which an attribute can be applied are defined by the that is applied to that attribute class. + Attributes are themselves classes that inherit from . Languages that support the use of attributes each have their own syntax for applying attributes to a language element. Attributes can be applied to almost any language element; the specific elements to which an attribute can be applied are defined by the that is applied to that attribute class. ### Type Accessibility All types have a modifier that governs their accessibility from other types. The following table describes the type accessibilities supported by the runtime. @@ -307,7 +307,7 @@ The common type system defines how types are declared, used, and managed in the |virtual|Methods, properties, and events|The method can be implemented by a derived type and can be invoked either statically or dynamically. If dynamic invocation is used, the type of the instance that makes the call at run time (rather than the type known at compile time) determines which implementation of the method is called. To invoke a virtual method statically, the variable might have to be cast to a type that uses the desired version of the method.| ### Overloading - Each type member has a unique signature. Method signatures consist of the method name and a parameter list (the order and types of the method's arguments). Multiple methods with the same name can be defined within a type as long as their signatures differ. When two or more methods with the same name are defined, the method is said to be overloaded. For example, in , the method is overloaded. One method takes a . The other method takes a and an . + Each type member has a unique signature. Method signatures consist of the method name and a parameter list (the order and types of the method's arguments). Multiple methods with the same name can be defined within a type as long as their signatures differ. When two or more methods with the same name are defined, the method is said to be overloaded. For example, in , the method is overloaded. One method takes a . The other method takes a and an . > [!NOTE] > The return type is not considered part of a method's signature. That is, methods cannot be overloaded if they differ only by return type. diff --git a/docs/standard/base-types/comparing.md b/docs/standard/base-types/comparing.md index 9d438b623f13c..497386f671796 100644 --- a/docs/standard/base-types/comparing.md +++ b/docs/standard/base-types/comparing.md @@ -30,17 +30,17 @@ manager: "wpickett" |Method name|Use| |-----------------|---------| -||Compares the values of two strings. Returns an integer value.| -||Compares two strings without regard to local culture. Returns an integer value.| -||Compares the current string object to another string. Returns an integer value.| -||Determines whether a string begins with the string passed. Returns a Boolean value.| -||Determines whether a string ends with the string passed. Returns a Boolean value.| -||Determines whether two strings are the same. Returns a Boolean value.| -||Returns the index position of a character or string, starting from the beginning of the string you are examining. Returns an integer value.| -||Returns the index position of a character or string, starting from the end of the string you are examining. Returns an integer value.| +||Compares the values of two strings. Returns an integer value.| +||Compares two strings without regard to local culture. Returns an integer value.| +||Compares the current string object to another string. Returns an integer value.| +||Determines whether a string begins with the string passed. Returns a Boolean value.| +||Determines whether a string ends with the string passed. Returns a Boolean value.| +||Determines whether two strings are the same. Returns a Boolean value.| +||Returns the index position of a character or string, starting from the beginning of the string you are examining. Returns an integer value.| +||Returns the index position of a character or string, starting from the end of the string you are examining. Returns an integer value.| ## Compare - The static method provides a thorough way of comparing two strings. This method is culturally aware. You can use this function to compare two strings or substrings of two strings. Additionally, overloads are provided that regard or disregard case and cultural variance. The following table shows the three integer values that this method might return. + The static method provides a thorough way of comparing two strings. This method is culturally aware. You can use this function to compare two strings or substrings of two strings. Additionally, overloads are provided that regard or disregard case and cultural variance. The following table shows the three integer values that this method might return. |Return value|Condition| |------------------|---------------| @@ -49,9 +49,9 @@ manager: "wpickett" |A positive integer

-or-

1|The first string follows the second string in the sort order.

-or-

The second string is `null`.| > [!IMPORTANT] -> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. +> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. - The following example uses the method to determine the relative values of two strings. + The following example uses the method to determine the relative values of two strings. [!code-cpp[Conceptual.String.BasicOps#6](../../../samples/snippets/cpp/VS_Snippets_CLR/conceptual.string.basicops/cpp/compare.cpp#6)] [!code-csharp[Conceptual.String.BasicOps#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/compare.cs#6)] @@ -59,13 +59,13 @@ manager: "wpickett" This example displays `-1` to the console. - The preceding example is culture-sensitive by default. To perform a culture-insensitive string comparison, use an overload of the method that allows you to specify the culture to use by supplying a *culture* parameter. For an example that demonstrates how to use the method to perform a culture-insensitive comparison, see [Performing Culture-Insensitive String Comparisons](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md). + The preceding example is culture-sensitive by default. To perform a culture-insensitive string comparison, use an overload of the method that allows you to specify the culture to use by supplying a *culture* parameter. For an example that demonstrates how to use the method to perform a culture-insensitive comparison, see [Performing Culture-Insensitive String Comparisons](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md). ## CompareOrdinal - The method compares two string objects without considering the local culture. The return values of this method are identical to the values returned by the **Compare** method in the previous table. + The method compares two string objects without considering the local culture. The return values of this method are identical to the values returned by the **Compare** method in the previous table. > [!IMPORTANT] -> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. +> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. The following example uses the **CompareOrdinal** method to compare the values of two strings. @@ -76,12 +76,12 @@ manager: "wpickett" This example displays `-32` to the console. ## CompareTo - The method compares the string that the current string object encapsulates to another string or object. The return values of this method are identical to the values returned by the method in the previous table. + The method compares the string that the current string object encapsulates to another string or object. The return values of this method are identical to the values returned by the method in the previous table. > [!IMPORTANT] -> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. +> The method is primarily intended for use when ordering or sorting strings. You should not use the method to test for equality (that is, to explicitly look for a return value of 0 with no regard for whether one string is less than or greater than the other). Instead, to determine whether two strings are equal, use the method. - The following example uses the method to compare the `string1` object to the `string2` object. + The following example uses the method to compare the `string1` object to the `string2` object. [!code-cpp[Conceptual.String.BasicOps#8](../../../samples/snippets/cpp/VS_Snippets_CLR/conceptual.string.basicops/cpp/compare.cpp#8)] [!code-csharp[Conceptual.String.BasicOps#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/compare.cs#8)] @@ -89,7 +89,7 @@ manager: "wpickett" This example displays `-1` to the console. - All overloads of the method perform culture-sensitive and case-sensitive comparisons by default. No overloads of this method are provided that allow you to perform a culture-insensitive comparison. For code clarity, we recommend that you use the **String.Compare** method instead, specifying for culture-sensitive operations or for culture-insensitive operations. For examples that demonstrate how to use the **String.Compare** method to perform both culture-sensitive and culture-insensitive comparisons, see [Performing Culture-Insensitive String Comparisons](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md). + All overloads of the method perform culture-sensitive and case-sensitive comparisons by default. No overloads of this method are provided that allow you to perform a culture-insensitive comparison. For code clarity, we recommend that you use the **String.Compare** method instead, specifying for culture-sensitive operations or for culture-insensitive operations. For examples that demonstrate how to use the **String.Compare** method to perform both culture-sensitive and culture-insensitive comparisons, see [Performing Culture-Insensitive String Comparisons](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md). ## Equals The **String.Equals** method can easily determine if two strings are the same. This case-sensitive method returns a **true** or **false** Boolean value. It can be used from an existing class, as illustrated in the next example. The following example uses the **Equals** method to determine whether a string object contains the phrase "Hello World". diff --git a/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md b/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md index 835c7af2f94d7..40db12c41b33e 100644 --- a/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md +++ b/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md @@ -29,16 +29,16 @@ You can optimize the performance of applications that make extensive use of regu ## Compiled Regular Expressions By default, the regular expression engine compiles a regular expression to a sequence of internal instructions (these are high-level codes that are different from Microsoft intermediate language, or MSIL). When the engine executes a regular expression, it interprets the internal codes. - If a object is constructed with the option, it compiles the regular expression to explicit MSIL code instead of high-level regular expression internal instructions. This allows .NET's just-in-time (JIT) compiler to convert the expression to native machine code for higher performance. + If a object is constructed with the option, it compiles the regular expression to explicit MSIL code instead of high-level regular expression internal instructions. This allows .NET's just-in-time (JIT) compiler to convert the expression to native machine code for higher performance. -However, generated MSIL cannot be unloaded. The only way to unload code is to unload an entire application domain (that is, to unload all of your application's code.). Effectively, once a regular expression is compiled with the option, never releases the resources used by the compiled expression, even if the regular expression was created by a object that is itself released to garbage collection. +However, generated MSIL cannot be unloaded. The only way to unload code is to unload an entire application domain (that is, to unload all of your application's code.). Effectively, once a regular expression is compiled with the option, never releases the resources used by the compiled expression, even if the regular expression was created by a object that is itself released to garbage collection. - You must be careful to limit the number of different regular expressions you compile with the option to avoid consuming too many resources. If an application must use a large or unbounded number of regular expressions, each expression should be interpreted, not compiled. However, if a small number of regular expressions are used repeatedly, they should be compiled with for better performance. An alternative is to use precompiled regular expressions. You can compile all of your expressions into a reusable DLL by using the method. This avoids the need to compile at runtime while still benefiting from the speed of compiled regular expressions. + You must be careful to limit the number of different regular expressions you compile with the option to avoid consuming too many resources. If an application must use a large or unbounded number of regular expressions, each expression should be interpreted, not compiled. However, if a small number of regular expressions are used repeatedly, they should be compiled with for better performance. An alternative is to use precompiled regular expressions. You can compile all of your expressions into a reusable DLL by using the method. This avoids the need to compile at runtime while still benefiting from the speed of compiled regular expressions. ## The Regular Expressions Cache To improve performance, the regular expression engine maintains an application-wide cache of compiled regular expressions. The cache stores regular expression patterns that are used only in static method calls. (Regular expression patterns supplied to instance methods are not cached.) This avoids the need to reparse an expression into high-level byte code each time it is used. - The maximum number of cached regular expressions is determined by the value of the `static` (`Shared` in Visual Basic) property. By default, the regular expression engine caches up to 15 compiled regular expressions. If the number of compiled regular expressions exceeds the cache size, the least recently used regular expression is discarded and the new regular expression is cached. + The maximum number of cached regular expressions is determined by the value of the `static` (`Shared` in Visual Basic) property. By default, the regular expression engine caches up to 15 compiled regular expressions. If the number of compiled regular expressions exceeds the cache size, the least recently used regular expression is discarded and the new regular expression is cached. Your application can take advantage of precompiled regular expressions in one of the following two ways: diff --git a/docs/standard/base-types/composite-formatting.md b/docs/standard/base-types/composite-formatting.md index b0c84921b07df..e1228367d32db 100644 --- a/docs/standard/base-types/composite-formatting.md +++ b/docs/standard/base-types/composite-formatting.md @@ -26,19 +26,19 @@ The .NET Framework composite formatting feature takes a list of objects and a co The composite formatting feature is supported by methods such as the following: -- , which returns a formatted result string. +- , which returns a formatted result string. -- , which appends a formatted result string to a object. +- , which appends a formatted result string to a object. -- Some overloads of the method, which display a formatted result string to the console. +- Some overloads of the method, which display a formatted result string to the console. -- Some overloads of the method, which write the formatted result string to a stream or file. The classes derived from , such as and , also share this functionality. +- Some overloads of the method, which write the formatted result string to a stream or file. The classes derived from , such as and , also share this functionality. -- , which outputs a formatted message to trace listeners. +- , which outputs a formatted message to trace listeners. -- The , , and methods, which output formatted messages to trace listeners. +- The , , and methods, which output formatted messages to trace listeners. -- The method, which writes an informational method to trace listeners. +- The method, which writes an informational method to trace listeners. ## Composite Format String A composite format string and object list are used as arguments of methods that support the composite formatting feature. A composite format string consists of zero or more runs of fixed text intermixed with one or more format items. The fixed text is any string that you choose, and each format item corresponds to an object or boxed structure in the list. The composite formatting feature returns a new result string where each format item is replaced by the string representation of the corresponding object in the list. @@ -86,9 +86,9 @@ The .NET Framework composite formatting feature takes a list of objects and a co |Type or type category|See| |---------------------------|---------| |Date and time types (, )|[Standard Date and Time Format Strings](../../../docs/standard/base-types/standard-date-and-time-format-strings.md)

[Custom Date and Time Format Strings](../../../docs/standard/base-types/custom-date-and-time-format-strings.md)| -|Enumeration types (all types derived from )|[Enumeration Format Strings](../../../docs/standard/base-types/enumeration-format-strings.md)| +|Enumeration types (all types derived from )|[Enumeration Format Strings](../../../docs/standard/base-types/enumeration-format-strings.md)| |Numeric types (, , , , , , , , , , , )|[Standard Numeric Format Strings](../../../docs/standard/base-types/standard-numeric-format-strings.md)

[Custom Numeric Format Strings](../../../docs/standard/base-types/custom-numeric-format-strings.md)| -||| +||| ||[Standard TimeSpan Format Strings](../../../docs/standard/base-types/standard-timespan-format-strings.md)

[Custom TimeSpan Format Strings](../../../docs/standard/base-types/custom-timespan-format-strings.md)| ### Escaping Braces @@ -112,7 +112,7 @@ The .NET Framework composite formatting feature takes a list of objects and a co [!code-vb[Formatting.Composite#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Composite/vb/Escaping1.vb#2)] ### Processing Order - If the call to the composite formatting method includes an argument whose value is not `null`, the runtime calls its method to request an implementation. If the method is able to return an implementation, it is cached for later use. + If the call to the composite formatting method includes an argument whose value is not `null`, the runtime calls its method to request an implementation. If the method is able to return an implementation, it is cached for later use. Each value in the parameter list that corresponds to a format item is converted to a string by performing the following steps. If any condition in the first three steps is true, the string representation of the value is returned in that step, and subsequent steps are not executed. @@ -122,13 +122,13 @@ The .NET Framework composite formatting feature takes a list of objects and a co 3. If the value implements the interface, the interface's method is called. The method is passed the *formatString* value, if one is present in the format item, or `null` if it is not. The argument is determined as follows: - - For a numeric value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. If it is unable to supply one, if the value of the argument is `null`, or if the composite formatting method does not have an parameter, the object for the current thread culture is used. + - For a numeric value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. If it is unable to supply one, if the value of the argument is `null`, or if the composite formatting method does not have an parameter, the object for the current thread culture is used. - - For a date and time value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. If it is unable to supply one, if the value of the argument is `null`, or if the composite formatting method does not have an parameter, the object for the current thread culture is used. + - For a date and time value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. If it is unable to supply one, if the value of the argument is `null`, or if the composite formatting method does not have an parameter, the object for the current thread culture is used. - - For objects of other types, if a composite formatting is called with an argument, its value (including a `null`, if no object is supplied) is passed directly to the implementation. Otherwise, a object that represents the current thread culture is passed to the implementation. + - For objects of other types, if a composite formatting is called with an argument, its value (including a `null`, if no object is supplied) is passed directly to the implementation. Otherwise, a object that represents the current thread culture is passed to the implementation. -4. The type's parameterless `ToString` method, which either overrides or inherits the behavior of its base class, is called. In this case, the format string specified by the *formatString* component in the format item, if it is present, is ignored. +4. The type's parameterless `ToString` method, which either overrides or inherits the behavior of its base class, is called. In this case, the format string specified by the *formatString* component in the format item, if it is present, is ignored. Alignment is applied after the preceding steps have been performed. @@ -140,7 +140,7 @@ The .NET Framework composite formatting feature takes a list of objects and a co Assuming that the current day is a Thursday in May, the value of both strings in the preceding example is `Thursday May` in the U.S. English culture. - exposes the same functionality as . The only difference between the two methods is that returns its result as a string, while writes the result to the output stream associated with the object. The following example uses the method to format the value of `MyInt` to a currency value. + exposes the same functionality as . The only difference between the two methods is that returns its result as a string, while writes the result to the output stream associated with the object. The following example uses the method to format the value of `MyInt` to a currency value. [!code-csharp[Formatting.Composite#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Composite/cs/Composite1.cs#4)] [!code-vb[Formatting.Composite#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Composite/vb/Composite1.vb#4)] @@ -157,7 +157,7 @@ The .NET Framework composite formatting feature takes a list of objects and a co ## See Also - + [Formatting Types](../../../docs/standard/base-types/formatting-types.md) [Standard Numeric Format Strings](../../../docs/standard/base-types/standard-numeric-format-strings.md) [Custom Numeric Format Strings](../../../docs/standard/base-types/custom-numeric-format-strings.md) diff --git a/docs/standard/base-types/conversion-tables.md b/docs/standard/base-types/conversion-tables.md index bd49006ccc57c..fb1083230fde4 100644 --- a/docs/standard/base-types/conversion-tables.md +++ b/docs/standard/base-types/conversion-tables.md @@ -55,9 +55,9 @@ Widening conversion occurs when a value of one type is converted to another type ## Narrowing Conversions A narrowing conversion to or can cause a loss of information. If the target type cannot properly express the magnitude of the source, the resulting type is set to the constant `PositiveInfinity` or `NegativeInfinity`. `PositiveInfinity` results from dividing a positive number by zero and is also returned when the value of a or exceeds the value of the `MaxValue` field. `NegativeInfinity` results from dividing a negative number by zero and is also returned when the value of a or falls below the value of the `MinValue` field. A conversion from a to a might result in `PositiveInfinity` or `NegativeInfinity`. - A narrowing conversion can also result in a loss of information for other data types. However, an is thrown if the value of a type that is being converted falls outside of the range specified by the target type's `MaxValue` and `MinValue` fields, and the conversion is checked by the runtime to ensure that the value of the target type does not exceed its `MaxValue` or `MinValue`. Conversions that are performed with the class are always checked in this manner. + A narrowing conversion can also result in a loss of information for other data types. However, an is thrown if the value of a type that is being converted falls outside of the range specified by the target type's `MaxValue` and `MinValue` fields, and the conversion is checked by the runtime to ensure that the value of the target type does not exceed its `MaxValue` or `MinValue`. Conversions that are performed with the class are always checked in this manner. - The following table lists conversions that throw an using or any checked conversion if the value of the type being converted is outside the defined range of the resulting type. + The following table lists conversions that throw an using or any checked conversion if the value of the type being converted is outside the defined range of the resulting type. |Type|Can be converted to| |----------|-------------------------| @@ -74,5 +74,5 @@ Widening conversion occurs when a value of one type is converted to another type ||, , , , , , , | ## See Also - + [Type Conversion in .NET](../../../docs/standard/base-types/type-conversion.md) diff --git a/docs/standard/base-types/creating-new.md b/docs/standard/base-types/creating-new.md index 40c9fb059874c..d99ef4af94443 100644 --- a/docs/standard/base-types/creating-new.md +++ b/docs/standard/base-types/creating-new.md @@ -22,7 +22,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Creating New Strings in .NET -The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. +The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. ## Creating Strings Using Assignment The easiest way to create a new object is simply to assign a string literal to a object. @@ -35,11 +35,11 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] allows strings |Method name|Use| |-----------------|---------| -||Builds a formatted string from a set of input objects.| -||Builds strings from two or more strings.| -||Builds a new string by combining an array of strings.| -||Builds a new string by inserting a string into the specified index of an existing string.| -||Copies specified characters in a string into a specified position in an array of characters.| +||Builds a formatted string from a set of input objects.| +||Builds strings from two or more strings.| +||Builds a new string by combining an array of strings.| +||Builds a new string by inserting a string into the specified index of an existing string.| +||Copies specified characters in a string into a specified position in an array of characters.| ### Format You can use the **String.Format** method to create formatted strings and concatenate strings representing multiple objects. This method automatically converts any passed object into a string. For example, if your application must display an **Int32** value and a **DateTime** value to the user, you can easily construct a string to represent these values using the **Format** method. For information about formatting conventions used with this method, see the section on [composite formatting](../../../docs/standard/base-types/composite-formatting.md). @@ -49,7 +49,7 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] allows strings [!code-csharp[Strings.Creating#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#1)] [!code-vb[Strings.Creating#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#1)] - In this example, displays the current date and time in a manner specified by the culture associated with the current thread. + In this example, displays the current date and time in a manner specified by the culture associated with the current thread. ### Concat The **String.Concat** method can be used to easily create a new string object from two or more existing objects. It provides a language-independent way to concatenate strings. This method accepts any class that derives from **System.Object**. The following example creates a string from two existing string objects and a separating character. diff --git a/docs/standard/base-types/custom-date-and-time-format-strings.md b/docs/standard/base-types/custom-date-and-time-format-strings.md index ecfb94e2fc9ee..8e463921962ac 100644 --- a/docs/standard/base-types/custom-date-and-time-format-strings.md +++ b/docs/standard/base-types/custom-date-and-time-format-strings.md @@ -35,7 +35,7 @@ A date and time format string defines the text representation of a , , , and methods. These methods require that an input string conform exactly to a particular pattern for the parse operation to succeed. The following example illustrates a call to the method to parse a date that must include a day, a month, and a two-digit year. + In parsing operations, custom date and time format strings can be used with the , , , and methods. These methods require that an input string conform exactly to a particular pattern for the parse operation to succeed. The following example illustrates a call to the method to parse a date that must include a day, a month, and a two-digit year. [!code-csharp[Formatting.DateAndTime.Custom#18](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/custandparsing1.cs#18)] [!code-vb[Formatting.DateAndTime.Custom#18](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/custandparsing1.vb#18)] @@ -121,7 +121,7 @@ A date and time format string defines the text representation of a ## The "ddd" custom format specifier - The "ddd" custom format specifier represents the abbreviated name of the day of the week. The localized abbreviated name of the day of the week is retrieved from the property of the current or specified culture. + The "ddd" custom format specifier represents the abbreviated name of the day of the week. The localized abbreviated name of the day of the week is retrieved from the property of the current or specified culture. The following example includes the "ddd" custom format specifier in a custom format string. @@ -132,7 +132,7 @@ A date and time format string defines the text representation of a ## The "dddd" custom format specifier - The "dddd" custom format specifier (plus any number of additional "d" specifiers) represents the full name of the day of the week. The localized name of the day of the week is retrieved from the property of the current or specified culture. + The "dddd" custom format specifier (plus any number of additional "d" specifiers) represents the full name of the day of the week. The localized name of the day of the week is retrieved from the property of the current or specified culture. The following example includes the "dddd" custom format specifier in a custom format string. @@ -342,13 +342,13 @@ A date and time format string defines the text representation of a ## The "K" custom format specifier - The "K" custom format specifier represents the time zone information of a date and time value. When this format specifier is used with values, the result string is defined by the value of the property: + The "K" custom format specifier represents the time zone information of a date and time value. When this format specifier is used with values, the result string is defined by the value of the property: -- For the local time zone (a property value of ), this specifier is equivalent to the "zzz" specifier and produces a result string containing the local offset from Coordinated Universal Time (UTC); for example, "-07:00". +- For the local time zone (a property value of ), this specifier is equivalent to the "zzz" specifier and produces a result string containing the local offset from Coordinated Universal Time (UTC); for example, "-07:00". -- For a UTC time (a property value of ), the result string includes a "Z" character to represent a UTC date. +- For a UTC time (a property value of ), the result string includes a "Z" character to represent a UTC date. -- For a time from an unspecified time zone (a time whose property equals ), the result is equivalent to . +- For a time from an unspecified time zone (a time whose property equals ), the result is equivalent to . For values, the "K" format specifier is equivalent to the "zzz" format specifier, and produces a result string containing the value's offset from UTC. @@ -411,7 +411,7 @@ A date and time format string defines the text representation of a ## The "MMM" custom format specifier - The "MMM" custom format specifier represents the abbreviated name of the month. The localized abbreviated name of the month is retrieved from the property of the current or specified culture. + The "MMM" custom format specifier represents the abbreviated name of the month. The localized abbreviated name of the month is retrieved from the property of the current or specified culture. The following example includes the "MMM" custom format specifier in a custom format string. @@ -422,7 +422,7 @@ A date and time format string defines the text representation of a ## The "MMMM" custom format specifier - The "MMMM" custom format specifier represents the full name of the month. The localized name of the month is retrieved from the property of the current or specified culture. + The "MMMM" custom format specifier represents the full name of the month. The localized name of the month is retrieved from the property of the current or specified culture. The following example includes the "MMMM" custom format specifier in a custom format string. @@ -457,7 +457,7 @@ A date and time format string defines the text representation of a ## The "t" custom format specifier - The "t" custom format specifier represents the first character of the AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. + The "t" custom format specifier represents the first character of the AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. If the "t" format specifier is used without other custom format specifiers, it is interpreted as the "t" standard date and time format specifier. For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. @@ -470,7 +470,7 @@ A date and time format string defines the text representation of a ## The "tt" custom format specifier - The "tt" custom format specifier (plus any number of additional "t" specifiers) represents the entire AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. + The "tt" custom format specifier (plus any number of additional "t" specifiers) represents the entire AM/PM designator. The appropriate localized designator is retrieved from the or property of the current or specific culture. The AM designator is used for all times from 0:00:00 (midnight) to 11:59:59.999. The PM designator is used for all times from 12:00:00 (noon) to 23:59:59.999. Make sure to use the "tt" specifier for languages for which it is necessary to maintain the distinction between AM and PM. An example is Japanese, for which the AM and PM designators differ in the second character instead of the first character. @@ -498,7 +498,7 @@ A date and time format string defines the text representation of a property of the format provider's current calendar. The following example parses the string representation of a date that has a two-digit year by using the default Gregorian calendar of the en-US culture, which, in this case, is the current culture. It then changes the current culture's object to use a object whose property has been modified. + In a parsing operation, a two-digit year that is parsed using the "yy" custom format specifier is interpreted based on the property of the format provider's current calendar. The following example parses the string representation of a date that has a two-digit year by using the default Gregorian calendar of the en-US culture, which, in this case, is the current culture. It then changes the current culture's object to use a object whose property has been modified. [!code-csharp[Formatting.DateAndTime.Custom#19](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Custom/cs/parseexact2digityear1.cs#19)] [!code-vb[Formatting.DateAndTime.Custom#19](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Custom/vb/parseexact2digityear1.vb#19)] @@ -553,7 +553,7 @@ A date and time format string defines the text representation of a ## The "z" custom format specifier - With values, the "z" custom format specifier represents the signed offset of the local operating system's time zone from Coordinated Universal Time (UTC), measured in hours. It does not reflect the value of an instance's property. For this reason, the "z" format specifier is not recommended for use with values. + With values, the "z" custom format specifier represents the signed offset of the local operating system's time zone from Coordinated Universal Time (UTC), measured in hours. It does not reflect the value of an instance's property. For this reason, the "z" format specifier is not recommended for use with values. With values, this format specifier represents the value's offset from UTC in hours. @@ -570,7 +570,7 @@ A date and time format string defines the text representation of a ## The "zz" custom format specifier - With values, the "zz" custom format specifier represents the signed offset of the local operating system's time zone from UTC, measured in hours. It does not reflect the value of an instance's property. For this reason, the "zz" format specifier is not recommended for use with values. + With values, the "zz" custom format specifier represents the signed offset of the local operating system's time zone from UTC, measured in hours. It does not reflect the value of an instance's property. For this reason, the "zz" format specifier is not recommended for use with values. With values, this format specifier represents the value's offset from UTC in hours. @@ -585,7 +585,7 @@ A date and time format string defines the text representation of a ## The "zzz" custom format specifier - With values, the "zzz" custom format specifier represents the signed offset of the local operating system's time zone from UTC, measured in hours and minutes. It does not reflect the value of an instance's property. For this reason, the "zzz" format specifier is not recommended for use with values. + With values, the "zzz" custom format specifier represents the signed offset of the local operating system's time zone from UTC, measured in hours and minutes. It does not reflect the value of an instance's property. For this reason, the "zzz" format specifier is not recommended for use with values. With values, this format specifier represents the value's offset from UTC in hours and minutes. @@ -600,10 +600,10 @@ A date and time format string defines the text representation of a ## The ":" custom format specifier - The ":" custom format specifier represents the time separator, which is used to differentiate hours, minutes, and seconds. The appropriate localized time separator is retrieved from the property of the current or specified culture. + The ":" custom format specifier represents the time separator, which is used to differentiate hours, minutes, and seconds. The appropriate localized time separator is retrieved from the property of the current or specified culture. > [!NOTE] -> To change the time separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `hh'_'dd'_'ss` produces a result string in which "_" (an underscore) is always used as the time separator. To change the time separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. +> To change the time separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `hh'_'dd'_'ss` produces a result string in which "_" (an underscore) is always used as the time separator. To change the time separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. If the ":" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. @@ -611,10 +611,10 @@ A date and time format string defines the text representation of a ## The "/" custom format specifier - The "/" custom format specifier represents the date separator, which is used to differentiate years, months, and days. The appropriate localized date separator is retrieved from the property of the current or specified culture. + The "/" custom format specifier represents the date separator, which is used to differentiate years, months, and days. The appropriate localized date separator is retrieved from the property of the current or specified culture. > [!NOTE] -> To change the date separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `mm'/'dd'/'yyyy` produces a result string in which "/" is always used as the date separator. To change the date separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. +> To change the date separator for a particular date and time string, specify the separator character within a literal string delimiter. For example, the custom format string `mm'/'dd'/'yyyy` produces a result string in which "/" is always used as the date separator. To change the date separator for all dates for a culture, either change the value of the property of the current culture, or instantiate a object, assign the character to its property, and call an overload of the formatting method that includes an parameter. If the "/" format specifier is used without other custom format specifiers, it is interpreted as a standard date and time format specifier and throws a . For more information about using a single format specifier, see [Using Single Custom Format Specifiers](#UsingSingleSpecifiers) later in this topic. @@ -683,7 +683,7 @@ A date and time format string defines the text representation of a object associated with the current thread culture, which provides values used to govern formatting. Computers that use different settings generate different result strings. - In addition, if you use the constructor to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructo to create a object that does not reflect a system's customizations. + In addition, if you use the constructor to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructo to create a object that does not reflect a system's customizations. ### DateTimeFormatInfo properties Formatting is influenced by properties of the current object, which is provided implicitly by the current thread culture or explicitly by the parameter of the method that invokes formatting. For the parameter, you should specify a object, which represents a culture, or a object. @@ -691,8 +691,8 @@ A date and time format string defines the text representation of a object. Your application can change the result produced by some custom date and time format specifiers by changing the corresponding property. For example, the "ddd" format specifier adds an abbreviated weekday name found in the string array to the result string. Similarly, the "MMMM" format specifier adds a full month name found in the string array to the result string. ## See Also - - + + [Formatting Types](../../../docs/standard/base-types/formatting-types.md) [Standard Date and Time Format Strings](../../../docs/standard/base-types/standard-date-and-time-format-strings.md) [Sample: .NET Framework 4 Formatting Utility](http://code.msdn.microsoft.com/NET-Framework-4-Formatting-9c4dae8d) diff --git a/docs/standard/base-types/custom-numeric-format-strings.md b/docs/standard/base-types/custom-numeric-format-strings.md index 8d115dc3badc4..2b26fbeb2bbd3 100644 --- a/docs/standard/base-types/custom-numeric-format-strings.md +++ b/docs/standard/base-types/custom-numeric-format-strings.md @@ -26,7 +26,7 @@ manager: "wpickett" # Custom Numeric Format Strings You can create a custom numeric format string, which consists of one or more custom numeric specifiers, to define how to format numeric data. A custom numeric format string is any format string that is not a [standard numeric format string](../../../docs/standard/base-types/standard-numeric-format-strings.md). - Custom numeric format strings are supported by some overloads of the `ToString` method of all numeric types. For example, you can supply a numeric format string to the and methods of the type. Custom numeric format strings are also supported by the .NET [composite formatting feature](../../../docs/standard/base-types/composite-formatting.md), which is used by some `Write` and `WriteLine` methods of the and classes, the method, and the method. + Custom numeric format strings are supported by some overloads of the `ToString` method of all numeric types. For example, you can supply a numeric format string to the and methods of the type. Custom numeric format strings are also supported by the .NET [composite formatting feature](../../../docs/standard/base-types/composite-formatting.md), which is used by some `Write` and `WriteLine` methods of the and classes, the method, and the method. > [!TIP] > You can download the [Formatting Utility](http://code.msdn.microsoft.com/NET-Framework-4-Formatting-9c4dae8d), an application that enables you to apply format strings to either numeric or date and time values and displays the result string. @@ -139,7 +139,7 @@ You can create a custom numeric format string, which consists of one or more cus ## The "‰" Custom Specifier - A per mille character (‰ or \u2030) in a format string causes a number to be multiplied by 1000 before it is formatted. The appropriate per mille symbol is inserted in the returned string at the location where the ‰ symbol appears in the format string. The per mille character used is defined by the property of the object that provides culture-specific formatting information. + A per mille character (‰ or \u2030) in a format string causes a number to be multiplied by 1000 before it is formatted. The appropriate per mille symbol is inserted in the returned string at the location where the ‰ symbol appears in the format string. The per mille character used is defined by the property of the object that provides culture-specific formatting information. The following example defines a custom format string that includes the "‰" custom specifier. @@ -209,7 +209,7 @@ You can create a custom numeric format string, which consists of one or more cus ### Control Panel Settings The settings in the **Regional and Language Options** item in Control Panel influence the result string produced by a formatting operation. Those settings are used to initialize the object associated with the current thread culture, and the current thread culture provides values used to govern formatting. Computers that use different settings generate different result strings. - In addition, if you use the constructor to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructor to create a object that does not reflect a system's customizations. + In addition, if you use the constructor to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructor to create a object that does not reflect a system's customizations. ### Rounding and Fixed-Point Format Strings For fixed-point format strings (that is, format strings that do not contain scientific notation format characters), numbers are rounded to as many decimal places as there are digit placeholders to the right of the decimal point. If the format string does not contain a decimal point, the number is rounded to the nearest integer. If the number has more digits than there are digit placeholders to the left of the decimal point, the extra digits are copied to the result string immediately before the first digit placeholder. diff --git a/docs/standard/base-types/custom-timespan-format-strings.md b/docs/standard/base-types/custom-timespan-format-strings.md index d980fc84abdd4..736f4bfbbe403 100644 --- a/docs/standard/base-types/custom-timespan-format-strings.md +++ b/docs/standard/base-types/custom-timespan-format-strings.md @@ -29,12 +29,12 @@ A format string defines the string representation of a > Custom format specifiers also do not include a sign symbol that enables you to differentiate between negative and positive time intervals. To include a sign symbol, you have to construct a format string by using conditional logic. The [Other Characters](#Other) section includes an example. - The string representations of values are produced by calls to the overloads of the method, and by methods that support composite formatting, such as . For more information, see [Formatting Types](../../../docs/standard/base-types/formatting-types.md) and [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). The following example illustrates the use of custom format strings in formatting operations. + The string representations of values are produced by calls to the overloads of the method, and by methods that support composite formatting, such as . For more information, see [Formatting Types](../../../docs/standard/base-types/formatting-types.md) and [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). The following example illustrates the use of custom format strings in formatting operations. [!code-csharp[Conceptual.TimeSpan.Custom#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customformatexample1.cs#1)] [!code-vb[Conceptual.TimeSpan.Custom#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customformatexample1.vb#1)] - Custom format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. + Custom format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. [!code-csharp[Conceptual.TimeSpan.Custom#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.custom/cs/customparseexample1.cs#2)] [!code-vb[Conceptual.TimeSpan.Custom#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.custom/vb/customparseexample1.vb#2)] @@ -71,7 +71,7 @@ A format string defines the string representation of a ## The "d" Custom Format Specifier - The "d" custom format specifier outputs the value of the property, which represents the number of whole days in the time interval. It outputs the full number of days in a value, even if the value has more than one digit. If the value of the property is zero, the specifier outputs "0". + The "d" custom format specifier outputs the value of the property, which represents the number of whole days in the time interval. It outputs the full number of days in a value, even if the value has more than one digit. If the value of the property is zero, the specifier outputs "0". If the "d" custom format specifier is used alone, specify "%d" so that it is not misinterpreted as a standard format string. The following example provides an illustration. @@ -87,7 +87,7 @@ A format string defines the string representation of a ## The "dd"-"dddddddd" Custom Format Specifiers - The "dd", "ddd", "dddd", "ddddd", "dddddd", "ddddddd", and "dddddddd" custom format specifiers output the value of the property, which represents the number of whole days in the time interval. + The "dd", "ddd", "dddd", "ddddd", "dddddd", "ddddddd", and "dddddddd" custom format specifiers output the value of the property, which represents the number of whole days in the time interval. The output string includes a minimum number of digits specified by the number of "d" characters in the format specifier, and it is padded with leading zeros as needed. If the digits in the number of days exceed the number of "d" characters in the format specifier, the full number of days is output in the result string. @@ -100,7 +100,7 @@ A format string defines the string representation of a ## The "h" Custom Format Specifier - The "h" custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 23. + The "h" custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 23. If the "h" custom format specifier is used alone, specify "%h" so that it is not misinterpreted as a standard format string. The following example provides an illustration. @@ -121,7 +121,7 @@ A format string defines the string representation of a ## The "hh" Custom Format Specifier - The "hh" custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that is not counted as part of its day component. For values from 0 through 9, the output string includes a leading zero. + The "hh" custom format specifier outputs the value of the property, which represents the number of whole hours in the time interval that is not counted as part of its day component. For values from 0 through 9, the output string includes a leading zero. Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "hh" custom format specifier instead to interpret the numeric string as the number of hours. The following example provides an illustration. @@ -137,7 +137,7 @@ A format string defines the string representation of a ## The "m" Custom Format Specifier - The "m" custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. + The "m" custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that is not counted as part of its day component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. If the "m" custom format specifier is used alone, specify "%m" so that it is not misinterpreted as a standard format string. The following example provides an illustration. @@ -158,7 +158,7 @@ A format string defines the string representation of a ## The "mm" Custom Format Specifier - The "mm" custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that is not included as part of its hours or days component. For values from 0 through 9, the output string includes a leading zero. + The "mm" custom format specifier outputs the value of the property, which represents the number of whole minutes in the time interval that is not included as part of its hours or days component. For values from 0 through 9, the output string includes a leading zero. Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "mm" custom format specifier instead to interpret the numeric string as the number of minutes. The following example provides an illustration. @@ -174,7 +174,7 @@ A format string defines the string representation of a ## The "s" Custom Format Specifier - The "s" custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. + The "s" custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. It returns a one-digit string value if the value of the property is 0 through 9, and it returns a two-digit string value if the value of the property ranges from 10 to 59. If the "s" custom format specifier is used alone, specify "%s" so that it is not misinterpreted as a standard format string. The following example provides an illustration. @@ -195,7 +195,7 @@ A format string defines the string representation of a ## The "ss" Custom Format Specifier - The "ss" custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. For values from 0 through 9, the output string includes a leading zero. + The "ss" custom format specifier outputs the value of the property, which represents the number of whole seconds in the time interval that is not included as part of its hours, days, or minutes component. For values from 0 through 9, the output string includes a leading zero. Ordinarily, in a parsing operation, an input string that includes only a single number is interpreted as the number of days. You can use the "ss" custom format specifier instead to interpret the numeric string as the number of seconds. The following example provides an illustration. @@ -211,7 +211,7 @@ A format string defines the string representation of a ## The"f" Custom Format Specifier - The "f" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly one fractional digit. + The "f" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly one fractional digit. If the "f" custom format specifier is used alone, specify "%f" so that it is not misinterpreted as a standard format string. @@ -224,7 +224,7 @@ A format string defines the string representation of a ## The "ff" Custom Format Specifier - The "ff" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly two fractional digits. + The "ff" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly two fractional digits. The following example uses the "ff" custom format specifier to display the hundredths of a second in a value. "ff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. @@ -235,7 +235,7 @@ A format string defines the string representation of a ## The "fff" Custom Format Specifier - The "fff" custom format specifier (with three "f" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly three fractional digits. + The "fff" custom format specifier (with three "f" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly three fractional digits. The following example uses the "fff" custom format specifier to display the milliseconds in a value. "fff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. @@ -246,7 +246,7 @@ A format string defines the string representation of a ## The "ffff" Custom Format Specifier - The "ffff" custom format specifier (with four "f" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly four fractional digits. + The "ffff" custom format specifier (with four "f" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly four fractional digits. The following example uses the "ffff" custom format specifier to display the ten-thousandths of a second in a value. "ffff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. @@ -257,7 +257,7 @@ A format string defines the string representation of a ## The "fffff" Custom Format Specifier - The "fffff" custom format specifier (with five "f" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly five fractional digits. + The "fffff" custom format specifier (with five "f" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly five fractional digits. The following example uses the "fffff" custom format specifier to display the hundred-thousandths of a second in a value. "fffff" is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. @@ -268,7 +268,7 @@ A format string defines the string representation of a ## The "ffffff" Custom Format Specifier - The "ffffff" custom format specifier (with six "f" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly six fractional digits. + The "ffffff" custom format specifier (with six "f" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. In a parsing operation that calls the or method, the input string must contain exactly six fractional digits. The following example uses the "ffffff" custom format specifier to display the millionths of a second in a value. It is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. @@ -279,7 +279,7 @@ A format string defines the string representation of a ## The "fffffff" Custom Format Specifier - The "fffffff" custom format specifier (with seven "f" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. In a parsing operation that calls the or method, the input string must contain exactly seven fractional digits. + The "fffffff" custom format specifier (with seven "f" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. In a parsing operation that calls the or method, the input string must contain exactly seven fractional digits. The following example uses the "fffffff" custom format specifier to display the fractional number of ticks in a value. It is used first as the only format specifier, and then combined with the "s" specifier in a custom format string. @@ -290,7 +290,7 @@ A format string defines the string representation of a ## The "F" Custom Format Specifier - The "F" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If the value of the time interval's tenths of a second is zero, it is not included in the result string. In a parsing operation that calls the or method, the presence of the tenths of a second digit is optional. + The "F" custom format specifier outputs the tenths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If the value of the time interval's tenths of a second is zero, it is not included in the result string. In a parsing operation that calls the or method, the presence of the tenths of a second digit is optional. If the "F" custom format specifier is used alone, specify "%F" so that it is not misinterpreted as a standard format string. @@ -303,7 +303,7 @@ A format string defines the string representation of a ## The "FF" Custom Format Specifier - The "FF" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths and hundredths of a second digit is optional. + The "FF" custom format specifier outputs the hundredths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths and hundredths of a second digit is optional. The following example uses the "FF" custom format specifier to display the hundredths of a second in a value. It also uses this custom format specifier in a parsing operation. @@ -314,7 +314,7 @@ A format string defines the string representation of a ## The "FFF" Custom Format Specifier - The "FFF" custom format specifier (with three "F" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, and thousandths of a second digit is optional. + The "FFF" custom format specifier (with three "F" characters) outputs the milliseconds in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, and thousandths of a second digit is optional. The following example uses the "FFF" custom format specifier to display the thousandths of a second in a value. It also uses this custom format specifier in a parsing operation. @@ -325,7 +325,7 @@ A format string defines the string representation of a ## The "FFFF" Custom Format Specifier - The "FFFF" custom format specifier (with four "F" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, and ten-thousandths of a second digit is optional. + The "FFFF" custom format specifier (with four "F" characters) outputs the ten-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, and ten-thousandths of a second digit is optional. The following example uses the "FFFF" custom format specifier to display the ten-thousandths of a second in a value. It also uses the "FFFF" custom format specifier in a parsing operation. @@ -336,7 +336,7 @@ A format string defines the string representation of a ## The "FFFFF" Custom Format Specifier - The "FFFFF" custom format specifier (with five "F" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, and hundred-thousandths of a second digit is optional. + The "FFFFF" custom format specifier (with five "F" characters) outputs the hundred-thousandths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, and hundred-thousandths of a second digit is optional. The following example uses the "FFFFF" custom format specifier to display the hundred-thousandths of a second in a value. It also uses the "FFFFF" custom format specifier in a parsing operation. @@ -347,7 +347,7 @@ A format string defines the string representation of a ## The "FFFFFF" Custom Format Specifier - The "FFFFFF" custom format specifier (with six "F" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, hundred-thousandths, and millionths of a second digit is optional. + The "FFFFFF" custom format specifier (with six "F" characters) outputs the millionths of a second in a time interval. In a formatting operation, any remaining fractional digits are truncated. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the tenths, hundredths, thousandths, ten-thousandths, hundred-thousandths, and millionths of a second digit is optional. The following example uses the "FFFFFF" custom format specifier to display the millionths of a second in a value. It also uses this custom format specifier in a parsing operation. @@ -358,7 +358,7 @@ A format string defines the string representation of a ## The "FFFFFFF" Custom Format Specifier - The "FFFFFFF" custom format specifier (with seven "F" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the seven fractional digits in the input string is optional. + The "FFFFFFF" custom format specifier (with seven "F" characters) outputs the ten-millionths of a second (or the fractional number of ticks) in a time interval. If there are any trailing fractional zeros, they are not included in the result string. In a parsing operation that calls the or method, the presence of the seven fractional digits in the input string is optional. The following example uses the "FFFFFFF" custom format specifier to display the fractional parts of a second in a value. It also uses this custom format specifier in a parsing operation. diff --git a/docs/standard/base-types/details-of-regular-expression-behavior.md b/docs/standard/base-types/details-of-regular-expression-behavior.md index bc763cf6e98e6..7111275ec12d0 100644 --- a/docs/standard/base-types/details-of-regular-expression-behavior.md +++ b/docs/standard/base-types/details-of-regular-expression-behavior.md @@ -63,7 +63,7 @@ The .NET Framework regular expression engine is a backtracking regular expressio |Pattern|Description| |-------------|-----------------| |`\b`|Begin the match at a word boundary.| - |`[A-Z]+`|Match any alphabetic character one or more times. Because the method is called with the option, the comparison is case-insensitive.| + |`[A-Z]+`|Match any alphabetic character one or more times. Because the method is called with the option, the comparison is case-insensitive.| |`\b`|End the match at a word boundary.| |`(?=\P{P})`|Look ahead to determine whether the next character is a punctuation symbol. If it is not, the match succeeds.| @@ -116,7 +116,7 @@ The .NET Framework regular expression engine is a backtracking regular expressio For more information about nonbacktracking subexpressions, see [Grouping Constructs](../../../docs/standard/base-types/grouping-constructs-in-regular-expressions.md). -- Right-to-left matching, which is specified by supplying the option to a class constructor or static instance matching method. This feature is useful when searching from right to left instead of from left to right, or in cases where it is more efficient to begin a match at the right part of the pattern instead of the left. As the following example illustrates, using right-to-left matching can change the behavior of greedy quantifiers. The example conducts two searches for a sentence that ends in a number. The left-to-right search that uses the greedy quantifier `+` matches one of the six digits in the sentence, whereas the right-to-left search matches all six digits. For an description of the regular expression pattern, see the example that illustrates lazy quantifiers earlier in this section. +- Right-to-left matching, which is specified by supplying the option to a class constructor or static instance matching method. This feature is useful when searching from right to left instead of from left to right, or in cases where it is more efficient to begin a match at the right part of the pattern instead of the left. As the following example illustrates, using right-to-left matching can change the behavior of greedy quantifiers. The example conducts two searches for a sentence that ends in a number. The left-to-right search that uses the greedy quantifier `+` matches one of the six digits in the sentence, whereas the right-to-left search matches all six digits. For an description of the regular expression pattern, see the example that illustrates lazy quantifiers earlier in this section. [!code-csharp[Conceptual.RegularExpressions.Design#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.design/cs/rtl1.cs#6)] [!code-vb[Conceptual.RegularExpressions.Design#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.design/vb/rtl1.vb#6)] @@ -153,4 +153,4 @@ The .NET Framework regular expression engine is a backtracking regular expressio |[Regular Expression Language - Quick Reference](../../../docs/standard/base-types/regular-expression-language-quick-reference.md)|Provides information about the set of characters, operators, and constructs that you can use to define regular expressions.| ## Reference - + diff --git a/docs/standard/base-types/enumeration-format-strings.md b/docs/standard/base-types/enumeration-format-strings.md index bf96274321ae4..fe564e1c2d74f 100644 --- a/docs/standard/base-types/enumeration-format-strings.md +++ b/docs/standard/base-types/enumeration-format-strings.md @@ -19,7 +19,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Enumeration Format Strings -You can use the method to create a new string object that represents the numeric, hexadecimal, or string value of an enumeration member. This method takes one of the enumeration formatting strings to specify the value that you want returned. +You can use the method to create a new string object that represents the numeric, hexadecimal, or string value of an enumeration member. This method takes one of the enumeration formatting strings to specify the value that you want returned. The following table lists the enumeration formatting strings and the values they return. These format specifiers are not case-sensitive. diff --git a/docs/standard/base-types/formatting-types.md b/docs/standard/base-types/formatting-types.md index 6116a9ad0ff09..1aeb53bb01ad1 100644 --- a/docs/standard/base-types/formatting-types.md +++ b/docs/standard/base-types/formatting-types.md @@ -83,9 +83,9 @@ manager: "wpickett" ## Formatting in .NET - The basic mechanism for formatting is the default implementation of the method, which is discussed in the [Default Formatting Using the ToString Method](#DefaultToString) section later in this topic. However, .NET provides several ways to modify and extend its default formatting support. These include the following: + The basic mechanism for formatting is the default implementation of the method, which is discussed in the [Default Formatting Using the ToString Method](#DefaultToString) section later in this topic. However, .NET provides several ways to modify and extend its default formatting support. These include the following: -- Overriding the method to define a custom string representation of an object’s value. For more information, see the [Overriding the ToString Method](#OverrideToString) section later in this topic. +- Overriding the method to define a custom string representation of an object’s value. For more information, see the [Overriding the ToString Method](#OverrideToString) section later in this topic. - Defining format specifiers that enable the string representation of an object’s value to take multiple forms. For example, the "X" format specifier in the following statement converts an integer to the string representation of a hexadecimal value. @@ -113,18 +113,18 @@ manager: "wpickett" ## Default Formatting Using the ToString Method - Every type that is derived from automatically inherits a parameterless `ToString` method, which returns the name of the type by default. The following example illustrates the default `ToString` method. It defines a class named `Automobile` that has no implementation. When the class is instantiated and its `ToString` method is called, it displays its type name. Note that the `ToString` method is not explicitly called in the example. The method implicitly calls the `ToString` method of the object passed to it as an argument. + Every type that is derived from automatically inherits a parameterless `ToString` method, which returns the name of the type by default. The following example illustrates the default `ToString` method. It defines a class named `Automobile` that has no implementation. When the class is instantiated and its `ToString` method is called, it displays its type name. Note that the `ToString` method is not explicitly called in the example. The method implicitly calls the `ToString` method of the object passed to it as an argument. [!code-csharp[Conceptual.Formatting.Overview#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/default1.cs#1)] [!code-vb[Conceptual.Formatting.Overview#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/default1.vb#1)] > [!WARNING] -> Starting with [!INCLUDE[win81](../../../includes/win81-md.md)], the [!INCLUDE[wrt](../../../includes/wrt-md.md)] includes an [IStringable](http://msdn.microsoft.com/library/windows/apps/windows.foundation.istringable.aspx) interface with a single method, [IStringable.ToString](http://msdn.microsoft.com/library/windows/apps/windows.foundation.istringable.tostring.aspx), which provides default formatting support. However, we recommend that managed types do not implement the `IStringable` interface. For more information, see "The [!INCLUDE[wrt](../../../includes/wrt-md.md)] and the `IStringable` Interface" section on the reference page. +> Starting with [!INCLUDE[win81](../../../includes/win81-md.md)], the [!INCLUDE[wrt](../../../includes/wrt-md.md)] includes an [IStringable](http://msdn.microsoft.com/library/windows/apps/windows.foundation.istringable.aspx) interface with a single method, [IStringable.ToString](http://msdn.microsoft.com/library/windows/apps/windows.foundation.istringable.tostring.aspx), which provides default formatting support. However, we recommend that managed types do not implement the `IStringable` interface. For more information, see "The [!INCLUDE[wrt](../../../includes/wrt-md.md)] and the `IStringable` Interface" section on the reference page. Because all types other than interfaces are derived from , this functionality is automatically provided to your custom classes or structures. However, the functionality offered by the default `ToString` method, is limited: Although it identifies the type, it fails to provide any information about an instance of the type. To provide a string representation of an object that provides information about that object, you must override the `ToString` method. > [!NOTE] -> Structures inherit from , which in turn is derived from . Although overrides , its implementation is identical. +> Structures inherit from , which in turn is derived from . Although overrides , its implementation is identical. [Back to top](#Introduction) @@ -139,7 +139,7 @@ manager: "wpickett" |Type|ToString override| |----------|-----------------------| -||Returns either or .| +||Returns either or .| ||Calls `Byte.ToString("G", NumberFormatInfo.CurrentInfo)` to format the value for the current culture.| ||Returns the character as a string.| ||Calls `DateTime.ToString("G", DatetimeFormatInfo.CurrentInfo)` to format the date and time value for the current culture.| @@ -206,7 +206,7 @@ manager: "wpickett" For more information about standard numeric formatting strings, see [Standard Numeric Format Strings](../../../docs/standard/base-types/standard-numeric-format-strings.md). - Standard format strings for date and time values are aliases for custom format strings stored by a particular property. For example, calling the `ToString` method of a date and time value with the "D" format specifier displays the date and time by using the custom format string stored in the current culture’s property. (For more information about custom format strings, see the [next section](#customStrings).) The following example illustrates this relationship. + Standard format strings for date and time values are aliases for custom format strings stored by a particular property. For example, calling the `ToString` method of a date and time value with the "D" format specifier displays the date and time by using the custom format string stored in the current culture’s property. (For more information about custom format strings, see the [next section](#customStrings).) The following example illustrates this relationship. [!code-csharp[Conceptual.Formatting.Overview#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/alias1.cs#5)] [!code-vb[Conceptual.Formatting.Overview#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/alias1.vb#5)] @@ -264,7 +264,7 @@ manager: "wpickett" |[Standard TimeSpan Format Strings](../../../docs/standard/base-types/standard-timespan-format-strings.md)|Describes standard format strings that create commonly used string representations of time intervals.| |[Custom TimeSpan Format Strings](../../../docs/standard/base-types/custom-timespan-format-strings.md)|Describes custom format strings that create application-specific formats for time intervals.| |[Enumeration Format Strings](../../../docs/standard/base-types/enumeration-format-strings.md)|Describes standard format strings that are used to create string representations of enumeration values.| -||Describes standard format strings for values.| +||Describes standard format strings for values.| ## Culture-Sensitive Formatting with Format Providers and the IFormatProvider Interface @@ -275,27 +275,27 @@ manager: "wpickett" The interface includes one method, , which has a single parameter that specifies the type of object that provides formatting information. If the method can provide an object of that type, it returns it. Otherwise, it returns a null reference (`Nothing` in Visual Basic). - is a callback method. When you call a `ToString` method overload that includes an parameter, it calls the method of that object. The method is responsible for returning an object that provides the necessary formatting information, as specified by its `formatType` parameter, to the `ToString` method. + is a callback method. When you call a `ToString` method overload that includes an parameter, it calls the method of that object. The method is responsible for returning an object that provides the necessary formatting information, as specified by its `formatType` parameter, to the `ToString` method. - A number of formatting or string conversion methods include a parameter of type , but in many cases the value of the parameter is ignored when the method is called. The following table lists some of the formatting methods that use the parameter and the type of the object that they pass to the method. + A number of formatting or string conversion methods include a parameter of type , but in many cases the value of the parameter is ignored when the method is called. The following table lists some of the formatting methods that use the parameter and the type of the object that they pass to the method. |Method|Type of `formatType` parameter| |------------|------------------------------------| -|`ToString` method of numeric types|| -|`ToString` method of date and time types|| -||| -||| +|`ToString` method of numeric types|| +|`ToString` method of date and time types|| +||| +||| > [!NOTE] -> The `ToString` methods of the numeric types and date and time types are overloaded, and only some of the overloads include an parameter. If a method does not have a parameter of type , the object that is returned by the property is passed instead. For example, a call to the default method ultimately results in a method call such as the following: `Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture)`. +> The `ToString` methods of the numeric types and date and time types are overloaded, and only some of the overloads include an parameter. If a method does not have a parameter of type , the object that is returned by the property is passed instead. For example, a call to the default method ultimately results in a method call such as the following: `Int32.ToString("G", System.Globalization.CultureInfo.CurrentCulture)`. .NET provides three classes that implement : -- , a class that provides formatting information for date and time values for a specific culture. Its implementation returns an instance of itself. +- , a class that provides formatting information for date and time values for a specific culture. Its implementation returns an instance of itself. -- , a class that provides numeric formatting information for a specific culture. Its implementation returns an instance of itself. +- , a class that provides numeric formatting information for a specific culture. Its implementation returns an instance of itself. -- . Its implementation can return either a object to provide numeric formatting information or a object to provide formatting information for date and time values. +- . Its implementation can return either a object to provide numeric formatting information or a object to provide formatting information for date and time values. You can also implement your own format provider to replace any one of these classes. However, your implementation’s method must return an object of the type listed in the previous table if it has to provide formatting information to the `ToString` method. @@ -303,14 +303,14 @@ manager: "wpickett" ### Culture-Sensitive Formatting of Numeric Values - By default, the formatting of numeric values is culture-sensitive. If you do not specify a culture when you call a formatting method, the formatting conventions of the current thread culture are used. This is illustrated in the following example, which changes the current thread culture four times and then calls the method. In each case, the result string reflects the formatting conventions of the current culture. This is because the `ToString` and `ToString(String)` methods wrap calls to each numeric type's `ToString(String, IFormatProvider)` method. + By default, the formatting of numeric values is culture-sensitive. If you do not specify a culture when you call a formatting method, the formatting conventions of the current thread culture are used. This is illustrated in the following example, which changes the current thread culture four times and then calls the method. In each case, the result string reflects the formatting conventions of the current culture. This is because the `ToString` and `ToString(String)` methods wrap calls to each numeric type's `ToString(String, IFormatProvider)` method. [!code-csharp[Conceptual.Formatting.Overview#19](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/culturespecific3.cs#19)] [!code-vb[Conceptual.Formatting.Overview#19](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/culturespecific3.vb#19)] You can also format a numeric value for a specific culture by calling a `ToString` overload that has a `provider` parameter and passing it either of the following: -- A object that represents the culture whose formatting conventions are to be used. Its method returns the value of the property, which is the object that provides culture-specific formatting information for numeric values. +- A object that represents the culture whose formatting conventions are to be used. Its method returns the value of the property, which is the object that provides culture-specific formatting information for numeric values. - A object that defines the culture-specific formatting conventions to be used. Its method returns an instance of itself. @@ -321,14 +321,14 @@ manager: "wpickett" ### Culture-Sensitive Formatting of Date and Time Values - By default, the formatting of date and time values is culture-sensitive. If you do not specify a culture when you call a formatting method, the formatting conventions of the current thread culture are used. This is illustrated in the following example, which changes the current thread culture four times and then calls the method. In each case, the result string reflects the formatting conventions of the current culture. This is because the , , , and methods wrap calls to the and methods. + By default, the formatting of date and time values is culture-sensitive. If you do not specify a culture when you call a formatting method, the formatting conventions of the current thread culture are used. This is illustrated in the following example, which changes the current thread culture four times and then calls the method. In each case, the result string reflects the formatting conventions of the current culture. This is because the , , , and methods wrap calls to the and methods. [!code-csharp[Conceptual.Formatting.Overview#17](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/culturespecific1.cs#17)] [!code-vb[Conceptual.Formatting.Overview#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/culturespecific1.vb#17)] - You can also format a date and time value for a specific culture by calling a or overload that has a `provider` parameter and passing it either of the following: + You can also format a date and time value for a specific culture by calling a or overload that has a `provider` parameter and passing it either of the following: -- A object that represents the culture whose formatting conventions are to be used. Its method returns the value of the property, which is the object that provides culture-specific formatting information for date and time values. +- A object that represents the culture whose formatting conventions are to be used. Its method returns the value of the property, which is the object that provides culture-specific formatting information for date and time values. - A object that defines the culture-specific formatting conventions to be used. Its method returns an instance of itself. @@ -339,13 +339,13 @@ manager: "wpickett" ## The IFormattable Interface - Typically, types that overload the `ToString` method with a format string and an parameter also implement the interface. This interface has a single member, , that includes both a format string and a format provider as parameters. + Typically, types that overload the `ToString` method with a format string and an parameter also implement the interface. This interface has a single member, , that includes both a format string and a format provider as parameters. Implementing the interface for your application-defined class offers two advantages: -- Support for string conversion by the class. Calls to the and methods call your implementation automatically. +- Support for string conversion by the class. Calls to the and methods call your implementation automatically. -- Support for composite formatting. If a format item that includes a format string is used to format your custom type, the common language runtime automatically calls your implementation and passes it the format string. For more information about composite formatting with methods such as or , see the [Composite Formatting](#CompositeFormatting) section. +- Support for composite formatting. If a format item that includes a format string is used to format your custom type, the common language runtime automatically calls your implementation and passes it the format string. For more information about composite formatting with methods such as or , see the [Composite Formatting](#CompositeFormatting) section. The following example defines a `Temperature` class that implements the interface. It supports the "C" or "G" format specifiers to display the temperature in Celsius, the "F" format specifier to display the temperature in Fahrenheit, and the "K" format specifier to display the temperature in Kelvin. @@ -361,7 +361,7 @@ manager: "wpickett" ## Composite Formatting - Some methods, such as and , support composite formatting. A composite format string is a kind of template that returns a single string that incorporates the string representation of zero, one, or more objects. Each object is represented in the composite format string by an indexed format item. The index of the format item corresponds to the position of the object that it represents in the method's parameter list. Indexes are zero-based. For example, in the following call to the method, the first format item, `{0:D}`, is replaced by the string representation of `thatDate`; the second format item, `{1}`, is replaced by the string representation of `item1`; and the third format item, `{2:C2}`, is replaced by the string representation of `item1.Value`. + Some methods, such as and , support composite formatting. A composite format string is a kind of template that returns a single string that incorporates the string representation of zero, one, or more objects. Each object is represented in the composite format string by an indexed format item. The index of the format item corresponds to the position of the object that it represents in the method's parameter list. Indexes are zero-based. For example, in the following call to the method, the first format item, `{0:D}`, is replaced by the string representation of `thatDate`; the second format item, `{1}`, is replaced by the string representation of `item1`; and the third format item, `{2:C2}`, is replaced by the string representation of `item1.Value`. [!code-csharp[Conceptual.Formatting.Overview#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/composite1.cs#14)] [!code-vb[Conceptual.Formatting.Overview#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/composite1.vb#14)] @@ -383,7 +383,7 @@ manager: "wpickett" ## Custom Formatting with ICustomFormatter - Two composite formatting methods, and , include a format provider parameter that supports custom formatting. When either of these formatting methods is called, it passes a object that represents an interface to the format provider’s method. The method is then responsible for returning the implementation that provides custom formatting. + Two composite formatting methods, and , include a format provider parameter that supports custom formatting. When either of these formatting methods is called, it passes a object that represents an interface to the format provider’s method. The method is then responsible for returning the implementation that provides custom formatting. The interface has a single method, , that is called automatically by a composite formatting method, once for each format item in a composite format string. The method has three parameters: a format string, which represents the `formatString` argument in a format item, an object to format, and an object that provides formatting services. Typically, the class that implements also implements , so this last parameter is a reference to the custom formatting class itself. The method returns a custom formatted string representation of the object to be formatted. If the method cannot format the object, it should return a null reference (`Nothing` in Visual Basic). @@ -392,7 +392,7 @@ manager: "wpickett" [!code-csharp[Conceptual.Formatting.Overview#15](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/icustomformatter1.cs#15)] [!code-vb[Conceptual.Formatting.Overview#15](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/icustomformatter1.vb#15)] - The following example uses the `ByteByByteFormatter` class to format integer values. Note that the method is called more than once in the second method call, and that the default provider is used in the third method call because the .`ByteByByteFormatter.Format` method does not recognize the "N0" format string and returns a null reference (`Nothing` in Visual Basic). + The following example uses the `ByteByByteFormatter` class to format integer values. Note that the method is called more than once in the second method call, and that the default provider is used in the third method call because the .`ByteByByteFormatter.Format` method does not recognize the "N0" format string and returns a null reference (`Nothing` in Visual Basic). [!code-csharp[Conceptual.Formatting.Overview#16](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/icustomformatter1.cs#16)] [!code-vb[Conceptual.Formatting.Overview#16](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/icustomformatter1.vb#16)] @@ -419,8 +419,8 @@ manager: "wpickett" ## Reference - + - + - + diff --git a/docs/standard/base-types/grouping-constructs-in-regular-expressions.md b/docs/standard/base-types/grouping-constructs-in-regular-expressions.md index d463b7f11f4f6..1085cd113816c 100644 --- a/docs/standard/base-types/grouping-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/grouping-constructs-in-regular-expressions.md @@ -28,9 +28,9 @@ Grouping constructs delineate the subexpressions of a regular expression and cap - Apply a quantifier to a subexpression that has multiple regular expression language elements. For more information about quantifiers, see [Quantifiers](../../../docs/standard/base-types/quantifiers-in-regular-expressions.md). -- Include a subexpression in the string that is returned by the and methods. +- Include a subexpression in the string that is returned by the and methods. -- Retrieve individual subexpressions from the property and process them separately from the matched text as a whole. +- Retrieve individual subexpressions from the property and process them separately from the matched text as a whole. The following table lists the grouping constructs supported by the .NET regular expression engine and indicates whether they are capturing or non-capturing. @@ -58,7 +58,7 @@ Grouping constructs delineate the subexpressions of a regular expression and cap where *subexpression* is any valid regular expression pattern. Captures that use parentheses are numbered automatically from left to right based on the order of the opening parentheses in the regular expression, starting from one. The capture that is numbered zero is the text matched by the entire regular expression pattern. > [!NOTE] -> By default, the `(`*subexpression*`)` language element captures the matched subexpression. But if the parameter of a regular expression pattern matching method includes the flag, or if the `n` option is applied to this subexpression (see [Group options](#group_options) later in this topic), the matched subexpression is not captured. +> By default, the `(`*subexpression*`)` language element captures the matched subexpression. But if the parameter of a regular expression pattern matching method includes the flag, or if the `n` option is applied to this subexpression (see [Group options](#group_options) later in this topic), the matched subexpression is not captured. You can access captured groups in four ways: @@ -66,9 +66,9 @@ Grouping constructs delineate the subexpressions of a regular expression and cap - By using the named backreference construct within the regular expression. The matched subexpression is referenced in the same regular expression by using the syntax `\k<`*name*`>`, where *name* is the name of a capturing group, or `\k<`*number*`>`, where *number* is the ordinal number of a capturing group. A capturing group has a default name that is identical to its ordinal number. For more information, see [Named matched subexpressions](#named_matched_subexpression) later in this topic. -- By using the `$`*number* replacement sequence in a or method call, where *number* is the ordinal number of the captured subexpression. +- By using the `$`*number* replacement sequence in a or method call, where *number* is the ordinal number of the captured subexpression. -- Programmatically, by using the object returned by the property. The member at position zero in the collection represents the entire regular expression match. Each subsequent member represents a matched subexpression. For more information, see the [Grouping Constructs and Regular Expression Objects](#Objects) section. +- Programmatically, by using the object returned by the property. The member at position zero in the collection represents the entire regular expression match. Each subsequent member represents a matched subexpression. For more information, see the [Grouping Constructs and Regular Expression Objects](#Objects) section. The following example illustrates a regular expression that identifies duplicated words in text. The regular expression pattern's two capturing groups represent the two instances of the duplicated word. The second instance is captured to report its starting position in the input string. @@ -107,7 +107,7 @@ Grouping constructs delineate the subexpressions of a regular expression and cap where *name* is a valid group name, and *subexpression* is any valid regular expression pattern. *name* must not contain any punctuation characters and cannot begin with a number. > [!NOTE] -> If the parameter of a regular expression pattern matching method includes the flag, or if the `n` option is applied to this subexpression (see [Group options](#group_options) later in this topic), the only way to capture a subexpression is to explicitly name capturing groups. +> If the parameter of a regular expression pattern matching method includes the flag, or if the `n` option is applied to this subexpression (see [Group options](#group_options) later in this topic), the only way to capture a subexpression is to explicitly name capturing groups. You can access named captured groups in the following ways: @@ -115,11 +115,11 @@ Grouping constructs delineate the subexpressions of a regular expression and cap - By using the backreference construct within the regular expression. The matched subexpression is referenced in the same regular expression by using the syntax `\`*number*, where *number* is the ordinal number of the captured subexpression. Named matched subexpressions are numbered consecutively from left to right after matched subexpressions. -- By using the `${`*name*`}` replacement sequence in a or method call, where *name* is the name of the captured subexpression. +- By using the `${`*name*`}` replacement sequence in a or method call, where *name* is the name of the captured subexpression. -- By using the `$`*number* replacement sequence in a or method call, where *number* is the ordinal number of the captured subexpression. +- By using the `$`*number* replacement sequence in a or method call, where *number* is the ordinal number of the captured subexpression. -- Programmatically, by using the object returned by the property. The member at position zero in the collection represents the entire regular expression match. Each subsequent member represents a matched subexpression. Named captured groups are stored in the collection after numbered captured groups. +- Programmatically, by using the object returned by the property. The member at position zero in the collection represents the entire regular expression match. Each subsequent member represents a matched subexpression. Named captured groups are stored in the collection after numbered captured groups. - Programmatically, by providing the subexpression name to the object's indexer (in C#) or to its property (in Visual Basic). @@ -186,7 +186,7 @@ Grouping constructs delineate the subexpressions of a regular expression and cap where *name1* is the current group (optional), *name2* is a previously defined group, and *subexpression* is any valid regular expression pattern. The balancing group definition deletes the definition of *name2* and stores the interval between *name2* and *name1* in *name1*. If no *name2* group is defined, the match backtracks. Because deleting the last definition of *name2* reveals the previous definition of *name2*, this construct lets you use the stack of captures for group *name2* as a counter for keeping track of nested constructs such as parentheses or opening and closing brackets. - The balancing group definition uses *name2* as a stack. The beginning character of each nested construct is placed in the group and in its collection. When the closing character is matched, its corresponding opening character is removed from the group, and the collection is decreased by one. After the opening and closing characters of all nested constructs have been matched, *name1* is empty. + The balancing group definition uses *name2* as a stack. The beginning character of each nested construct is placed in the group and in its collection. When the closing character is matched, its corresponding opening character is removed from the group, and the collection is decreased by one. After the opening and closing characters of all nested constructs have been matched, *name1* is empty. > [!NOTE] > After you modify the regular expression in the following example to use the appropriate opening and closing character of a nested construct, you can use it to handle most nested constructs, such as mathematical expressions or lines of program code that include multiple nested method calls. @@ -233,10 +233,10 @@ Grouping constructs delineate the subexpressions of a regular expression and cap |7|`[^<>]*`|Looks for non-angle bracket characters after the right angle bracket; finds no matches.| |8|`)+`|The value of the third captured group is ">".

The next character in the input string is not a right angle bracket, so the regular expression engine does not loop back to the `((?'Close-Open'>)[^<>]*)` subpattern.| |9|`)*`|The value of the first captured group is "\".

The next character in the input string is a left angle bracket, so the regular expression engine loops back to the `(((?'Open'<)` subpattern.| -|10|`(((?'Open'<)`|Matches the left angle bracket in "\" and assigns it to the `Open` group. Its collection now has a single value, "<".| +|10|`(((?'Open'<)`|Matches the left angle bracket in "\" and assigns it to the `Open` group. Its collection now has a single value, "<".| |11|`[^<>]*`|Matches "mno".| |12|`)+`|"
The next character in the input string is an left angle bracket, so the regular expression engine loops back to the `(?'Open'<)[^<>]*)` subpattern.| -|13|`(((?'Open'<)`|Matches the left angle bracket in "\" and assigns it to the `Open` group. The collection of the `Open` group now includes two captures: the left angle bracket from "\", and the left angle bracket from "\".| +|13|`(((?'Open'<)`|Matches the left angle bracket in "\" and assigns it to the `Open` group. The collection of the `Open` group now includes two captures: the left angle bracket from "\", and the left angle bracket from "\".| |14|`[^<>]*`|Matches "xyz".| |15|`)+`|"
The next character in the input string is not a left angle bracket, so the regular expression engine does not loop back to the `(?'Open'<)[^<>]*)` subpattern.| |16|`((?'Close-Open'>)`|Matches the right angle bracket in "\". "xyz", assigns the substring between the `Open` group and the right angle bracket to the `Close` group, and deletes the current value of the `Open` group. The value of the previous capture (the left angle bracket in "\") becomes the current value of the `Open` group. The collection of the `Open` group now includes a single capture, the left angle bracket from "\".| @@ -286,7 +286,7 @@ Grouping constructs delineate the subexpressions of a regular expression and cap where *subexpression* is any valid regular expression pattern. For example, `(?i-s:)` turns on case insensitivity and disables single-line mode. For more information about the inline options you can specify, see [Regular Expression Options](../../../docs/standard/base-types/regular-expression-options.md). > [!NOTE] -> You can specify options that apply to an entire regular expression rather than a subexpression by using a class constructor or a static method. You can also specify inline options that apply after a specific point in a regular expression by using the `(?imnsx-imnsx)` language construct. +> You can specify options that apply to an entire regular expression rather than a subexpression by using a class constructor or a static method. You can also specify inline options that apply after a specific point in a regular expression by using the `(?imnsx-imnsx)` language construct. The group options construct is not a capturing group. That is, although any portion of a string that is captured by *subexpression* is included in the match, it is not included in a captured group nor used to populate the object. @@ -443,7 +443,7 @@ Grouping constructs delineate the subexpressions of a regular expression and cap ## Grouping Constructs and Regular Expression Objects - Substrings that are matched by a regular expression capturing group are represented by objects, which can be retrieved from the object that is returned by the property. The object is populated as follows: + Substrings that are matched by a regular expression capturing group are represented by objects, which can be retrieved from the object that is returned by the property. The object is populated as follows: - The first object in the collection (the object at index zero) represents the entire match. @@ -451,7 +451,7 @@ Grouping constructs delineate the subexpressions of a regular expression and cap - The final set of objects represent named capturing groups. They appear in the order in which they are defined in the regular expression, from left to right. The index value of the first named capturing group is one greater than the index of the last unnamed capturing group. If there are no unnamed capturing groups in the regular expression, the index value of the first named capturing group is one. - If you apply a quantifier to a capturing group, the corresponding object's , , and properties reflect the last substring that is captured by a capturing group. You can retrieve a complete set of substrings that are captured by groups that have quantifiers from the object that is returned by the property. + If you apply a quantifier to a capturing group, the corresponding object's , , and properties reflect the last substring that is captured by a capturing group. You can retrieve a complete set of substrings that are captured by groups that have quantifiers from the object that is returned by the property. The following example clarifies the relationship between the and objects. @@ -467,7 +467,7 @@ Grouping constructs delineate the subexpressions of a regular expression and cap |`\W+`|Match one or more non-word characters.| |`(\w+)\W+)+`|Match the pattern of one or more word characters followed by one or more non-word characters one or more times. This is the first capturing group.| - The first capturing group matches each word of the sentence. The second capturing group matches each word along with the punctuation and white space that follow the word. The object whose index is 2 provides information about the text matched by the second capturing group. The complete set of words captured by the capturing group are available from the object returned by the property. + The first capturing group matches each word of the sentence. The second capturing group matches each word along with the punctuation and white space that follow the word. The object whose index is 2 provides information about the text matched by the second capturing group. The complete set of words captured by the capturing group are available from the object returned by the property. ## See Also [Regular Expression Language - Quick Reference](../../../docs/standard/base-types/regular-expression-language-quick-reference.md) diff --git a/docs/standard/base-types/how-to-convert-numeric-user-input-in-web-controls-to-numbers.md b/docs/standard/base-types/how-to-convert-numeric-user-input-in-web-controls-to-numbers.md index ec7ce2e7cca3c..c03372bd1a85e 100644 --- a/docs/standard/base-types/how-to-convert-numeric-user-input-in-web-controls-to-numbers.md +++ b/docs/standard/base-types/how-to-convert-numeric-user-input-in-web-controls-to-numbers.md @@ -26,11 +26,11 @@ Because a Web page can be displayed anywhere in the world, users can input numer ### To convert numeric input from a Web TextBox control to a number -1. Determine whether the string array returned by the property is populated. If it is not, continue to step 6. +1. Determine whether the string array returned by the property is populated. If it is not, continue to step 6. 2. If the string array returned by the property is populated, retrieve its first element. The first element indicates the user's default or preferred language and region. -3. Instantiate a object that represents the user's preferred culture by calling the constructor. +3. Instantiate a object that represents the user's preferred culture by calling the constructor. 4. Call either the `TryParse` or the `Parse` method of the numeric type that you want to convert the user's input to. Use an overload of the `TryParse` or the `Parse` method with a `provider` parameter, and pass it either of the following: @@ -40,7 +40,7 @@ Because a Web page can be displayed anywhere in the world, users can input numer 5. If the conversion fails, repeat steps 2 through 4 for each remaining element in the string array returned by the property. -6. If the conversion still fails or if the string array returned by the property is empty, parse the string by using the invariant culture, which is returned by the property. +6. If the conversion still fails or if the string array returned by the property is empty, parse the string by using the invariant culture, which is returned by the property. ## Example The following example is the complete code-behind page for a Web form that asks the user to enter a numeric value in a control and converts it to a number. That number is then doubled and displayed by using the same formatting rules as the original input. @@ -48,9 +48,9 @@ Because a Web page can be displayed anywhere in the world, users can input numer [!code-csharp[Formatting.HowTo.ParseNumericInput#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.ParseNumericInput/cs/NumericUserInput1.aspx.cs#1)] [!code-vb[Formatting.HowTo.ParseNumericInput#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.ParseNumericInput/vb/NumericUserInput1.aspx.vb#1)] - The property is populated from the culture names that are contained in `Accept-Language` headers included in an HTTP request. However, not all browsers include `Accept-Language` headers in their requests, and users can also suppress the headers completely. This makes it important to have a fallback culture when parsing user input. Typically, the fallback culture is the invariant culture returned by . Users can also provide Internet Explorer with culture names that they input in a text box, which creates the possibility that the culture names may not be valid. This makes it important to use exception handling when instantiating a object. + The property is populated from the culture names that are contained in `Accept-Language` headers included in an HTTP request. However, not all browsers include `Accept-Language` headers in their requests, and users can also suppress the headers completely. This makes it important to have a fallback culture when parsing user input. Typically, the fallback culture is the invariant culture returned by . Users can also provide Internet Explorer with culture names that they input in a text box, which creates the possibility that the culture names may not be valid. This makes it important to use exception handling when instantiating a object. - When retrieved from an HTTP request submitted by Internet Explorer, the array is populated in order of user preference. The first element in the array contains the name of the user's primary culture/region. If the array contains any additional items, Internet Explorer arbitrarily assigns them a quality specifier, which is delimited from the culture name by a semicolon. For example, an entry for the fr-FR culture might take the form `fr-FR;q=0.7`. + When retrieved from an HTTP request submitted by Internet Explorer, the array is populated in order of user preference. The first element in the array contains the name of the user's primary culture/region. If the array contains any additional items, Internet Explorer arbitrarily assigns them a quality specifier, which is delimited from the culture name by a semicolon. For example, an entry for the fr-FR culture might take the form `fr-FR;q=0.7`. The example calls the constructor with its `useUserOverride` parameter set to `false` to create a new object. This ensures that, if the culture name is the default culture name on the server, the new object created by the class constructor contains a culture's default settings and does not reflect any settings overridden by using the server's **Regional and Language Options** application. The values from any overridden settings on the server are unlikely to exist on the user's system or to be reflected in the user's input. @@ -68,7 +68,7 @@ Because a Web page can be displayed anywhere in the world, users can input numer Change the name of the class from `NumericUserInput` to the name of the class that is defined by the `Inherits` attribute of the [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)] page's `Page` directive. Change the name of the `NumericInput` object reference to the name defined by the `id` attribute of the [!INCLUDE[vstecasp](../../../includes/vstecasp-md.md)] page's `form` tag. ## .NET Framework Security - To prevent a user from injecting script into the HTML stream, user input should never be directly echoed back in the server response. Instead, it should be encoded by using the method. + To prevent a user from injecting script into the HTML stream, user input should never be directly echoed back in the server response. Instead, it should be encoded by using the method. ## See Also [Performing Formatting Operations](../../../docs/standard/base-types/performing-formatting-operations.md) diff --git a/docs/standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md b/docs/standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md index cceb16f6cc345..fd8d8738cd886 100644 --- a/docs/standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md +++ b/docs/standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md @@ -26,9 +26,9 @@ manager: "wpickett" # How to: Define and Use Custom Numeric Format Providers The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] gives you extensive control over the string representation of numeric values. It supports the following features for customizing the format of numeric values: -- Standard numeric format strings, which provide a predefined set of formats for converting numbers to their string representation. You can use them with any numeric formatting method, such as , that has a `format` parameter. For details, see [Standard Numeric Format Strings](../../../docs/standard/base-types/standard-numeric-format-strings.md). +- Standard numeric format strings, which provide a predefined set of formats for converting numbers to their string representation. You can use them with any numeric formatting method, such as , that has a `format` parameter. For details, see [Standard Numeric Format Strings](../../../docs/standard/base-types/standard-numeric-format-strings.md). -- Custom numeric format strings, which provide a set of symbols that can be combined to define custom numeric format specifiers. They can also be used with any numeric formatting method, such as , that has a `format` parameter. For details, see [Custom Numeric Format Strings](../../../docs/standard/base-types/custom-numeric-format-strings.md). +- Custom numeric format strings, which provide a set of symbols that can be combined to define custom numeric format specifiers. They can also be used with any numeric formatting method, such as , that has a `format` parameter. For details, see [Custom Numeric Format Strings](../../../docs/standard/base-types/custom-numeric-format-strings.md). - Custom or objects, which define the symbols and format patterns used in displaying the string representations of numeric values. You can use them with any numeric formatting method, such as , that has a `provider` parameter. Typically, the `provider` parameter is used to specify culture-specific formatting. @@ -38,7 +38,7 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] gives you exten 1. Define a class that implements the and interfaces. -2. Implement the method. is a callback method that the formatting method (such as the method) invokes to retrieve the object that is actually responsible for performing custom formatting. A typical implementation of does the following: +2. Implement the method. is a callback method that the formatting method (such as the method) invokes to retrieve the object that is actually responsible for performing custom formatting. A typical implementation of does the following: 1. Determines whether the object passed as a method parameter represents an interface. @@ -46,11 +46,11 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] gives you exten 3. If the parameter does not represent the interface, returns `null`. -3. Implement the method. This method is called by the method and is responsible for returning the string representation of a number. Implementing the method typically involves the following: +3. Implement the method. This method is called by the method and is responsible for returning the string representation of a number. Implementing the method typically involves the following: 1. Optionally, make sure that the method is legitimately intended to provide formatting services by examining the `provider` parameter. For formatting objects that implement both and , this involves testing the `provider` parameter for equality with the current formatting object. - 2. Determine whether the formatting object should support custom format specifiers. (For example, an "N" format specifier might indicate that a U.S. telephone number should be output in NANP format, and an "I" might indicate output in ITU-T Recommendation E.123 format.) If format specifiers are used, the method should handle the specific format specifier. It is passed to the method in the `format` parameter. If no specifier is present, the value of the `format` parameter is . + 2. Determine whether the formatting object should support custom format specifiers. (For example, an "N" format specifier might indicate that a U.S. telephone number should be output in NANP format, and an "I" might indicate output in ITU-T Recommendation E.123 format.) If format specifiers are used, the method should handle the specific format specifier. It is passed to the method in the `format` parameter. If no specifier is present, the value of the `format` parameter is . 3. Retrieve the numeric value passed to the method as the `arg` parameter. Perform whatever manipulations are required to convert it to its string representation. @@ -60,7 +60,7 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] gives you exten 1. Create a new instance of the custom formatting class. -2. Call the formatting method, passing it the custom formatting object, the formatting specifier (or , if one is not used), and the numeric value to be formatted. +2. Call the formatting method, passing it the custom formatting object, the formatting specifier (or , if one is not used), and the numeric value to be formatted. ## Example The following example defines a custom numeric format provider named `TelephoneFormatter` that converts a number that represents a U.S. telephone number to its NANP or E.123 format. The method handles two format specifiers, "N" (which outputs the NANP format) and "I" (which outputs the international E.123 format). @@ -68,9 +68,9 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] gives you exten [!code-csharp[Formatting.HowTo.NumericValue#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.NumericValue/cs/Telephone1.cs#1)] [!code-vb[Formatting.HowTo.NumericValue#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#1)] - The custom numeric format provider can be used only with the method. The other overloads of numeric formatting methods (such as `ToString`) that have a parameter of type all pass the implementation a object that represents the type. In return, they expect the method to return a object. If it does not, the custom numeric format provider is ignored, and the object for the current culture is used in its place. In the example, the `TelephoneFormatter.GetFormat` method handles the possibility that it may be inappropriately passed to a numeric formatting method by examining the method parameter and returning `null` if it represents a type other than . + The custom numeric format provider can be used only with the method. The other overloads of numeric formatting methods (such as `ToString`) that have a parameter of type all pass the implementation a object that represents the type. In return, they expect the method to return a object. If it does not, the custom numeric format provider is ignored, and the object for the current culture is used in its place. In the example, the `TelephoneFormatter.GetFormat` method handles the possibility that it may be inappropriately passed to a numeric formatting method by examining the method parameter and returning `null` if it represents a type other than . - If a custom numeric format provider supports a set of format specifiers, make sure you provide a default behavior if no format specifier is supplied in the format item used in the method call. In the example, "N" is the default format specifier. This allows for a number to be converted to a formatted telephone number by providing an explicit format specifier. The following example illustrates such a method call. + If a custom numeric format provider supports a set of format specifiers, make sure you provide a default behavior if no format specifier is supplied in the format item used in the method call. In the example, "N" is the default format specifier. This allows for a number to be converted to a formatted telephone number by providing an explicit format specifier. The following example illustrates such a method call. [!code-csharp[Formatting.HowTo.NumericValue#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.NumericValue/cs/Telephone1.cs#2)] [!code-vb[Formatting.HowTo.NumericValue#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#2)] @@ -80,12 +80,12 @@ The [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] gives you exten [!code-csharp[Formatting.HowTo.NumericValue#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.NumericValue/cs/Telephone1.cs#3)] [!code-vb[Formatting.HowTo.NumericValue#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.NumericValue/vb/Telephone1.vb#3)] - If no default format specifier is defined, your implementation of the method should include code such as the following so that .NET can provide formatting that your code does not support. + If no default format specifier is defined, your implementation of the method should include code such as the following so that .NET can provide formatting that your code does not support. [!code-csharp[System.ICustomFormatter.Format#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.ICustomFormatter.Format/cs/format.cs#1)] [!code-vb[System.ICustomFormatter.Format#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.ICustomFormatter.Format/vb/Format.vb#1)] - In the case of this example, the method that implements is intended to serve as a callback method for the method. Therefore, it examines the `formatProvider` parameter to determine whether it contains a reference to the current `TelephoneFormatter` object. However, the method can also be called directly from code. In that case, you can use the `formatProvider` parameter to provide a or object that supplies culture-specific formatting information. + In the case of this example, the method that implements is intended to serve as a callback method for the method. Therefore, it examines the `formatProvider` parameter to determine whether it contains a reference to the current `TelephoneFormatter` object. However, the method can also be called directly from code. In that case, you can use the `formatProvider` parameter to provide a or object that supplies culture-specific formatting information. ## Compiling the Code Compile the code at the command line using csc.exe or vb.exe. To compile the code in [!INCLUDE[vsprvs](../../../includes/vsprvs-md.md)], put it in a console application project template. diff --git a/docs/standard/base-types/how-to-display-dates-in-non-gregorian-calendars.md b/docs/standard/base-types/how-to-display-dates-in-non-gregorian-calendars.md index 54b320981fd6e..ca2f69dba7df6 100644 --- a/docs/standard/base-types/how-to-display-dates-in-non-gregorian-calendars.md +++ b/docs/standard/base-types/how-to-display-dates-in-non-gregorian-calendars.md @@ -33,12 +33,12 @@ The and types use the Gregor 2. Instantiate a object representing the culture whose formatting will be used to display the date. -3. Call the method to determine whether the calendar object is a member of the array returned by the property. This indicates that the calendar can serve as the default calendar for the object. If it is not a member of the array, follow the instructions in the "To Display the Date in Any Calendar" section. +3. Call the method to determine whether the calendar object is a member of the array returned by the property. This indicates that the calendar can serve as the default calendar for the object. If it is not a member of the array, follow the instructions in the "To Display the Date in Any Calendar" section. -4. Assign the calendar object to the property of the object returned by the property. +4. Assign the calendar object to the property of the object returned by the property. > [!NOTE] - > The class also has a property. However, it is read-only and constant; it does not change to reflect the new default calendar assigned to the property. + > The class also has a property. However, it is read-only and constant; it does not change to reflect the new default calendar assigned to the property. 5. Call either the or the method, and pass it the object whose default calendar was modified in the previous step. @@ -70,15 +70,15 @@ The and types use the Gregor [!code-csharp[Formatting.HowTo.Calendar#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.Calendar/cs/Calendar1.cs#2)] [!code-vb[Formatting.HowTo.Calendar#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.Calendar/vb/Calendar1.vb#2)] - Each object can support one or more calendars, which are indicated by the property. One of these is designated as the culture's default calendar and is returned by the read-only property. Another of the optional calendars can be designated as the default by assigning a object that represents that calendar to the property returned by the property. However, some calendars, such as the Persian calendar represented by the class, do not serve as optional calendars for any culture. + Each object can support one or more calendars, which are indicated by the property. One of these is designated as the culture's default calendar and is returned by the read-only property. Another of the optional calendars can be designated as the default by assigning a object that represents that calendar to the property returned by the property. However, some calendars, such as the Persian calendar represented by the class, do not serve as optional calendars for any culture. The example defines a reusable calendar utility class, `CalendarUtility`, to handle many of the details of generating the string representation of a date using a particular calendar. The `CalendarUtility` class has the following members: - A parameterized constructor whose single parameter is a object in which a date is to be represented. This is assigned to a private field of the class. -- `CalendarExists`, a private method that returns a Boolean value indicating whether the calendar represented by the `CalendarUtility` object is supported by the object that is passed to the method as a parameter. The method wraps a call to the method, to which it passes the array. +- `CalendarExists`, a private method that returns a Boolean value indicating whether the calendar represented by the `CalendarUtility` object is supported by the object that is passed to the method as a parameter. The method wraps a call to the method, to which it passes the array. -- `HasSameName`, a private method assigned to the delegate that is passed as a parameter to the method. Each member of the array is passed to the method until the method returns `true`. The method determines whether the name of an optional calendar is the same as the calendar represented by the `CalendarUtility` object. +- `HasSameName`, a private method assigned to the delegate that is passed as a parameter to the method. Each member of the array is passed to the method until the method returns `true`. The method determines whether the name of an optional calendar is the same as the calendar represented by the `CalendarUtility` object. - `DisplayDate`, an overloaded public method that is passed two parameters: either a or value to express in the calendar represented by the `CalendarUtility` object; and the culture whose formatting rules are to be used. Its behavior in returning the string representation of a date depends on whether the target calendar is supported by the culture whose formatting rules are to be used. diff --git a/docs/standard/base-types/how-to-display-localized-date-and-time-information-to-web-users.md b/docs/standard/base-types/how-to-display-localized-date-and-time-information-to-web-users.md index bc96131f48338..750e9e81e8381 100644 --- a/docs/standard/base-types/how-to-display-localized-date-and-time-information-to-web-users.md +++ b/docs/standard/base-types/how-to-display-localized-date-and-time-information-to-web-users.md @@ -26,11 +26,11 @@ Because a Web page can be displayed anywhere in the world, operations that parse ### To parse date and time strings input by the user -1. Determine whether the string array returned by the property is populated. If it is not, continue to step 6. +1. Determine whether the string array returned by the property is populated. If it is not, continue to step 6. 2. If the string array returned by the property is populated, retrieve its first element. The first element indicates the user's default or preferred language and region. -3. Instantiate a object that represents the user's preferred culture by calling the constructor. +3. Instantiate a object that represents the user's preferred culture by calling the constructor. 4. Call either the `TryParse` or the `Parse` method of the or type to try the conversion. Use an overload of the `TryParse` or the `Parse` method with a `provider` parameter, and pass it either of the following: @@ -40,7 +40,7 @@ Because a Web page can be displayed anywhere in the world, operations that parse 5. If the conversion fails, repeat steps 2 through 4 for each remaining element in the string array returned by the property. -6. If the conversion still fails or if the string array returned by the property is empty, parse the string by using the invariant culture, which is returned by the property. +6. If the conversion still fails or if the string array returned by the property is empty, parse the string by using the invariant culture, which is returned by the property. ### To parse the local date and time of the user's request @@ -48,35 +48,35 @@ Because a Web page can be displayed anywhere in the world, operations that parse 2. Create a JavaScript function that handles the `onClick` event of a `Submit` button by writing the current date and time and the local time zone's offset from Coordinated Universal Time (UTC) to the property. Use a delimiter (such as a semicolon) to separate the two components of the string. -3. Use the Web form's event to inject the function into the HTML output stream by passing the text of the script to the method. +3. Use the Web form's event to inject the function into the HTML output stream by passing the text of the script to the method. 4. Connect the event handler to the `Submit` button's `onClick` event by providing the name of the JavaScript function to the `OnClientClick` attribute of the `Submit` button. 5. Create a handler for the `Submit` button's event. -6. In the event handler, determine whether the string array returned by the property is populated. If it is not, continue to step 14. +6. In the event handler, determine whether the string array returned by the property is populated. If it is not, continue to step 14. 7. If the string array returned by the property is populated, retrieve its first element. The first element indicates the user's default or preferred language and region. -8. Instantiate a object that represents the user's preferred culture by calling the constructor. +8. Instantiate a object that represents the user's preferred culture by calling the constructor. 9. Pass the string assigned to the property to the method to store the string representation of the user's local date and time and the string representation of the user's local time zone offset in separate array elements. -10. Call either the or method to convert the date and time of the user's request to a value. Use an overload of the method with a `provider` parameter, and pass it either of the following: +10. Call either the or method to convert the date and time of the user's request to a value. Use an overload of the method with a `provider` parameter, and pass it either of the following: - The object created in step 8. - The object that is returned by the property of the object created in step 8. -11. If the parse operation in step 10 fails, go to step 13. Otherwise, call the method to convert the string representation of the user's time zone offset to an integer. +11. If the parse operation in step 10 fails, go to step 13. Otherwise, call the method to convert the string representation of the user's time zone offset to an integer. -12. Instantiate a that represents the user's local time by calling the constructor. +12. Instantiate a that represents the user's local time by calling the constructor. 13. If the conversion in step 10 fails, repeat steps 7 through 12 for each remaining element in the string array returned by the property. -14. If the conversion still fails or if the string array returned by the property is empty, parse the string by using the invariant culture, which is returned by the property. Then repeat steps 7 through 12. +14. If the conversion still fails or if the string array returned by the property is empty, parse the string by using the invariant culture, which is returned by the property. Then repeat steps 7 through 12. - The result is a object that represents the local time of the user of your Web page. You can then determine the equivalent UTC by calling the method. You can also determine the equivalent date and time on your Web server by calling the method and passing a value of as the time zone to convert the time to. + The result is a object that represents the local time of the user of your Web page. You can then determine the equivalent UTC by calling the method. You can also determine the equivalent date and time on your Web server by calling the method and passing a value of as the time zone to convert the time to. ## Example The following example contains both the HTML source and the code for an ASP.NET Web form that asks the user to input a date and time value. A client-side script also writes information on the local date and time of the user's request and the offset of the user's time zone from UTC to a hidden field. This information is then parsed by the server, which returns a Web page that displays the user's input. It also displays the date and time of the user's request using the user's local time, the time on the server, and UTC. @@ -86,13 +86,13 @@ Because a Web page can be displayed anywhere in the world, operations that parse The client-side script calls the JavaScript `toLocaleString` method. This produces a string that follows the formatting conventions of the user's locale, which is more likely to be successfully parsed on the server. - The property is populated from the culture names that are contained in `Accept-Language` headers included in an HTTP request. However, not all browsers include `Accept-Language` headers in their requests, and users can also suppress the headers completely. This makes it important to have a fallback culture when parsing user input. Typically the fallback culture is the invariant culture returned by . Users can also provide Internet Explorer with culture names that they input in a text box, which creates the possibility that the culture names may not be valid. This makes it important to use exception handling when instantiating a object. + The property is populated from the culture names that are contained in `Accept-Language` headers included in an HTTP request. However, not all browsers include `Accept-Language` headers in their requests, and users can also suppress the headers completely. This makes it important to have a fallback culture when parsing user input. Typically the fallback culture is the invariant culture returned by . Users can also provide Internet Explorer with culture names that they input in a text box, which creates the possibility that the culture names may not be valid. This makes it important to use exception handling when instantiating a object. - When retrieved from an HTTP request submitted by Internet Explorer, the array is populated in order of user preference. The first element in the array contains the name of the user's primary culture/region. If the array contains any additional items, Internet Explorer arbitrarily assigns them a quality specifier, which is delimited from the culture name by a semicolon. For example, an entry for the fr-FR culture might take the form `fr-FR;q=0.7`. + When retrieved from an HTTP request submitted by Internet Explorer, the array is populated in order of user preference. The first element in the array contains the name of the user's primary culture/region. If the array contains any additional items, Internet Explorer arbitrarily assigns them a quality specifier, which is delimited from the culture name by a semicolon. For example, an entry for the fr-FR culture might take the form `fr-FR;q=0.7`. The example calls the constructor with its `useUserOverride` parameter set to `false` to create a new object. This ensures that, if the culture name is the default culture name on the server, the new object created by the class constructor contains a culture's default settings and does not reflect any settings overridden by using the server's **Regional and Language Options** application. The values from any overridden settings on the server are unlikely to exist on the user's system or to be reflected in the user's input. - Because this example parses two string representations of a date and time (one input by the user, the other stored to the hidden field), it defines the possible objects that may be required in advance. It creates an array of objects that is one greater than the number of elements returned by the property. It then instantiates a object for each language/region string, and also instantiates a object that represents . + Because this example parses two string representations of a date and time (one input by the user, the other stored to the hidden field), it defines the possible objects that may be required in advance. It creates an array of objects that is one greater than the number of elements returned by the property. It then instantiates a object for each language/region string, and also instantiates a object that represents . Your code can call either the or the method to convert the user's string representation of a date and time to a value. Repeated calls to a parse method may be required for a single parsing operation. As a result, the method is better because it returns `false` if a parse operation fails. In contrast, handling the repeated exceptions that may be thrown by the method can be a very expensive proposition in a Web application. @@ -108,7 +108,7 @@ Because a Web page can be displayed anywhere in the world, operations that parse - A control named `DateInfo`. ## .NET Framework Security - To prevent a user from injecting script into the HTML stream, user input should never be directly echoed back in the server response. Instead, it should be encoded by using the method. + To prevent a user from injecting script into the HTML stream, user input should never be directly echoed back in the server response. Instead, it should be encoded by using the method. ## See Also [Performing Formatting Operations](../../../docs/standard/base-types/performing-formatting-operations.md) diff --git a/docs/standard/base-types/how-to-display-milliseconds-in-date-and-time-values.md b/docs/standard/base-types/how-to-display-milliseconds-in-date-and-time-values.md index da59c0a7da3f2..b51d66c645b5d 100644 --- a/docs/standard/base-types/how-to-display-milliseconds-in-date-and-time-values.md +++ b/docs/standard/base-types/how-to-display-milliseconds-in-date-and-time-values.md @@ -21,13 +21,13 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Display Milliseconds in Date and Time Values -The default date and time formatting methods, such as , include the hours, minutes, and seconds of a time value but exclude its milliseconds component. This topic shows how to include a date and time's millisecond component in formatted date and time strings. +The default date and time formatting methods, such as , include the hours, minutes, and seconds of a time value but exclude its milliseconds component. This topic shows how to include a date and time's millisecond component in formatted date and time strings. ### To display the millisecond component of a DateTime value -1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. +1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. -2. To extract the string representation of a time's millisecond component, call the date and time value's or method, and pass the `fff` or `FFF` custom format pattern either alone or with other custom format specifiers as the `format` parameter. +2. To extract the string representation of a time's millisecond component, call the date and time value's or method, and pass the `fff` or `FFF` custom format pattern either alone or with other custom format specifiers as the `format` parameter. ## Example The example displays the millisecond component of a and a value to the console, both alone and included in a longer date and time string. @@ -40,7 +40,7 @@ The default date and time formatting methods, such as object and modify it to include milliseconds. The example also illustrates this approach. It retrieves the current culture's full date and time pattern from the property, and then inserts the custom pattern `.ffff` after its seconds pattern. Note that the example uses a regular expression to perform this operation in a single method call. + A problem with defining a complete custom format specifier that includes the millisecond component of a date and time is that it defines a hard-coded format that may not correspond to the arrangement of time elements in the application's current culture. A better alternative is to retrieve one of the date and time display patterns defined by the current culture's object and modify it to include milliseconds. The example also illustrates this approach. It retrieves the current culture's full date and time pattern from the property, and then inserts the custom pattern `.ffff` after its seconds pattern. Note that the example uses a regular expression to perform this operation in a single method call. You can also use a custom format specifier to display a fractional part of seconds other than milliseconds. For example, the `f` or `F` custom format specifier displays tenths of a second, the `ff` or `FF` custom format specifier displays hundredths of a second, and the `ffff` or `FFFF` custom format specifier displays ten thousandths of a second. Fractional parts of a millisecond are truncated instead of rounded in the returned string. These format specifiers are used in the following example. diff --git a/docs/standard/base-types/how-to-extract-a-protocol-and-port-number-from-a-url.md b/docs/standard/base-types/how-to-extract-a-protocol-and-port-number-from-a-url.md index a4a4289ef8624..c116a9c518f1b 100644 --- a/docs/standard/base-types/how-to-extract-a-protocol-and-port-number-from-a-url.md +++ b/docs/standard/base-types/how-to-extract-a-protocol-and-port-number-from-a-url.md @@ -25,7 +25,7 @@ manager: "wpickett" The following example extracts a protocol and port number from a URL. ## Example - The example uses the method to return the protocol followed by a colon followed by the port number. + The example uses the method to return the protocol followed by a colon followed by the port number. [!code-csharp[RegularExpressions.Examples.Protocol#1](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/cs/Example.cs#1)] [!code-vb[RegularExpressions.Examples.Protocol#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/vb/Example.vb#1)] @@ -41,9 +41,9 @@ The following example extracts a protocol and port number from a URL. |`(?:\d+)?`|Match zero or one occurrence of a colon followed by one or more digit characters. Name this group `port`.| |`/`|Match a slash mark.| - The method expands the `${proto}${port}` replacement sequence, which concatenates the value of the two named groups captured in the regular expression pattern. It is a convenient alternative to explicitly concatenating the strings retrieved from the collection object returned by the property. + The method expands the `${proto}${port}` replacement sequence, which concatenates the value of the two named groups captured in the regular expression pattern. It is a convenient alternative to explicitly concatenating the strings retrieved from the collection object returned by the property. - The example uses the method with two substitutions, `${proto}` and `${port}`, to include the captured groups in the output string. You can retrieve the captured groups from the match's object instead, as the following code shows. + The example uses the method with two substitutions, `${proto}` and `${port}`, to include the captured groups in the output string. You can retrieve the captured groups from the match's object instead, as the following code shows. [!code-csharp[RegularExpressions.Examples.Protocol#2](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/cs/example2.cs#2)] [!code-vb[RegularExpressions.Examples.Protocol#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.Protocol/vb/example2.vb#2)] diff --git a/docs/standard/base-types/how-to-extract-the-day-of-the-week-from-a-specific-date.md b/docs/standard/base-types/how-to-extract-the-day-of-the-week-from-a-specific-date.md index fdc6e98ed1204..bb7937d6230ec 100644 --- a/docs/standard/base-types/how-to-extract-the-day-of-the-week-from-a-specific-date.md +++ b/docs/standard/base-types/how-to-extract-the-day-of-the-week-from-a-specific-date.md @@ -31,13 +31,13 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Extract the Day of the Week from a Specific Date -The .NET Framework makes it easy to determine the ordinal day of the week for a particular date, and to display the localized weekday name for a particular date. An enumerated value that indicates the day of the week corresponding to a particular date is available from the or property. In contrast, retrieving the weekday name is a formatting operation that can be performed by calling a formatting method, such as a date and time value's `ToString` method or the method. This topic shows how to perform these formatting operations. +The .NET Framework makes it easy to determine the ordinal day of the week for a particular date, and to display the localized weekday name for a particular date. An enumerated value that indicates the day of the week corresponding to a particular date is available from the or property. In contrast, retrieving the weekday name is a formatting operation that can be performed by calling a formatting method, such as a date and time value's `ToString` method or the method. This topic shows how to perform these formatting operations. ### To extract a number indicating the day of the week from a specific date -1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. +1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. -2. Use the or property to retrieve a value that indicates the day of the week. +2. Use the or property to retrieve a value that indicates the day of the week. 3. If necessary, cast (in C#) or convert (in Visual Basic) the value to an integer. @@ -48,45 +48,45 @@ The .NET Framework makes it easy to determine the ordinal day of the week for a ### To extract the abbreviated weekday name from a specific date -1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. +1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. 2. You can extract the abbreviated weekday name of the current culture or of a specific culture: - 1. To extract the abbreviated weekday name for the current culture, call the date and time value's or instance method, and pass the string "ddd" as the `format` parameter. The following example illustrates the call to the method. + 1. To extract the abbreviated weekday name for the current culture, call the date and time value's or instance method, and pass the string "ddd" as the `format` parameter. The following example illustrates the call to the method. [!code-csharp[Formatting.Howto.WeekdayName#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/abbrname1.cs#1)] [!code-vb[Formatting.Howto.WeekdayName#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/abbrname1.vb#1)] - 2. To extract the abbreviated weekday name for a specific culture, call the date and time value’s or instance method. Pass the string "ddd" as the `format` parameter. Pass either a or a object that represents the culture whose weekday name you want to retrieve as the `provider` parameter. The following code illustrates a call to the method using a object that represents the fr-FR culture. + 2. To extract the abbreviated weekday name for a specific culture, call the date and time value’s or instance method. Pass the string "ddd" as the `format` parameter. Pass either a or a object that represents the culture whose weekday name you want to retrieve as the `provider` parameter. The following code illustrates a call to the method using a object that represents the fr-FR culture. [!code-csharp[Formatting.Howto.WeekdayName#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/abbrname2.cs#2)] [!code-vb[Formatting.Howto.WeekdayName#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/abbrname2.vb#2)] ### To extract the full weekday name from a specific date -1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. +1. If you are working with the string representation of a date, convert it to a or a value by using the static or method. 2. You can extract the full weekday name of the current culture or of a specific culture: - 1. To extract the weekday name for the current culture, call the date and time value’s or instance method, and pass the string "dddd" as the `format` parameter. The following example illustrates the call to the method. + 1. To extract the weekday name for the current culture, call the date and time value’s or instance method, and pass the string "dddd" as the `format` parameter. The following example illustrates the call to the method. [!code-csharp[Formatting.Howto.WeekdayName#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/fullname4.cs#4)] [!code-vb[Formatting.Howto.WeekdayName#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/fullname4.vb#4)] - 2. To extract the weekday name for a specific culture, call the date and time value’s or instance method. Pass the string "dddd" as the `format` parameter. Pass either a or a object that represents the culture whose weekday name you want to retrieve as the `provider` parameter. The following code illustrates a call to the method using a object that represents the es-ES culture. + 2. To extract the weekday name for a specific culture, call the date and time value’s or instance method. Pass the string "dddd" as the `format` parameter. Pass either a or a object that represents the culture whose weekday name you want to retrieve as the `provider` parameter. The following code illustrates a call to the method using a object that represents the es-ES culture. [!code-csharp[Formatting.Howto.WeekdayName#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/fullname5.cs#5)] [!code-vb[Formatting.Howto.WeekdayName#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/fullname5.vb#5)] ## Example - The example illustrates calls to the and properties and the and methods to retrieve the number that represents the day of the week, the abbreviated weekday name, and the full weekday name for a particular date. + The example illustrates calls to the and properties and the and methods to retrieve the number that represents the day of the week, the abbreviated weekday name, and the full weekday name for a particular date. [!code-csharp[Formatting.Howto.WeekdayName#6](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/example6.cs#6)] [!code-vb[Formatting.Howto.WeekdayName#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/example6.vb#6)] Individual languages may provide functionality that duplicates or supplements the functionality provided by the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)]. For example, Visual Basic includes two such functions: -- `Weekday`, which returns a number that indicates the day of the week of a particular date. It considers the ordinal value of the first day of the week to be one, whereas the property considers it to be zero. +- `Weekday`, which returns a number that indicates the day of the week of a particular date. It considers the ordinal value of the first day of the week to be one, whereas the property considers it to be zero. - `WeekdayName`, which returns the name of the week in the current culture that corresponds to a particular weekday number. @@ -94,7 +94,7 @@ The .NET Framework makes it easy to determine the ordinal day of the week for a [!code-vb[Formatting.HowTo.WeekdayName#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/example9.vb#9)] - You can also use the value returned by the property to retrieve the weekday name of a particular date. This requires only a call to the method on the value returned by the property. However, this technique does not produce a localized weekday name for the current culture, as the following example illustrates. + You can also use the value returned by the property to retrieve the weekday name of a particular date. This requires only a call to the method on the value returned by the property. However, this technique does not produce a localized weekday name for the current culture, as the following example illustrates. [!code-csharp[Formatting.HowTo.WeekdayName#8](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/cs/Howto1.cs#8)] [!code-vb[Formatting.HowTo.WeekdayName#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.WeekdayName/vb/Howto1.vb#8)] diff --git a/docs/standard/base-types/how-to-round-trip-date-and-time-values.md b/docs/standard/base-types/how-to-round-trip-date-and-time-values.md index 9d9c3bbd5fc5f..e71407e37e49c 100644 --- a/docs/standard/base-types/how-to-round-trip-date-and-time-values.md +++ b/docs/standard/base-types/how-to-round-trip-date-and-time-values.md @@ -25,13 +25,13 @@ In many applications, a date and time value is intended to unambiguously identif ### To round-trip a DateTime value -1. Convert the value to its string representation by calling the method with the "o" format specifier. +1. Convert the value to its string representation by calling the method with the "o" format specifier. 2. Save the string representation of the value to a file, or pass it across a process, application domain, or machine boundary. 3. Retrieve the string that represents the value. -4. Call the method, and pass as the value of the `styles` parameter. +4. Call the method, and pass as the value of the `styles` parameter. The following example illustrates how to round-trip a value. @@ -42,20 +42,20 @@ In many applications, a date and time value is intended to unambiguously identif ### To round-trip a DateTimeOffset value -1. Convert the value to its string representation by calling the method with the "o" format specifier. +1. Convert the value to its string representation by calling the method with the "o" format specifier. 2. Save the string representation of the value to a file, or pass it across a process, application domain, or machine boundary. 3. Retrieve the string that represents the value. -4. Call the method, and pass as the value of the `styles` parameter. +4. Call the method, and pass as the value of the `styles` parameter. The following example illustrates how to round-trip a value. [!code-csharp[Formatting.HowTo.RoundTrip#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.HowTo.RoundTrip/cs/RoundTrip.cs#2)] [!code-vb[Formatting.HowTo.RoundTrip#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.HowTo.RoundTrip/vb/RoundTrip.vb#2)] - This technique always unambiguously identifies a value as a single point in time. The value can then be converted to Coordinated Universal Time (UTC) by calling the method, or it can be converted to the time in a particular time zone by calling the or method. The major limitation of this technique is that date and time arithmetic, when performed on a value that represents the time in a particular time zone, may not produce accurate results for that time zone. This is because when a value is instantiated, it is disassociated from its time zone. Therefore, that time zone's adjustment rules can no longer be applied when you perform date and time calculations. You can work around this problem by defining a custom type that includes both a date and time value and its accompanying time zone. + This technique always unambiguously identifies a value as a single point in time. The value can then be converted to Coordinated Universal Time (UTC) by calling the method, or it can be converted to the time in a particular time zone by calling the or method. The major limitation of this technique is that date and time arithmetic, when performed on a value that represents the time in a particular time zone, may not produce accurate results for that time zone. This is because when a value is instantiated, it is disassociated from its time zone. Therefore, that time zone's adjustment rules can no longer be applied when you perform date and time calculations. You can work around this problem by defining a custom type that includes both a date and time value and its accompanying time zone. ### To round-trip a date and time value with its time zone @@ -66,7 +66,7 @@ In many applications, a date and time value is intended to unambiguously identif 2. Mark the class with the attribute. -3. Serialize the object using the method. +3. Serialize the object using the method. 4. Restore the object using the method. @@ -86,13 +86,13 @@ In many applications, a date and time value is intended to unambiguously identif - (C# only). - - . + - . - - . + - . - - . + - . - - . + - . - A reference to System.Core.dll. diff --git a/docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md b/docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md index 2e34e27f2c4a4..92978e08e751b 100644 --- a/docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md +++ b/docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md @@ -25,7 +25,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Strip Invalid Characters from a String -The following example uses the static method to strip invalid characters from a string. +The following example uses the static method to strip invalid characters from a string. ## Example You can use the `CleanInput` method defined in this example to strip potentially harmful characters that have been entered into a text field that accepts user input. In this case, `CleanInput` strips out all nonalphanumeric characters except periods (.), at symbols (@), and hyphens (-), and returns the remaining string. However, you can modify the regular expression pattern so that it strips out any characters that should not be included in an input string. @@ -33,7 +33,7 @@ The following example uses the static , which is the string defined by the replacement pattern. To allow additional characters in user input, add those characters to the character class in the regular expression pattern. For example, the regular expression pattern `[^\w\.@-\\%]` also allows a percentage symbol and a backslash in an input string. + The regular expression pattern `[^\w\.@-]` matches any character that is not a word character, a period, an @ symbol, or a hyphen. A word character is any letter, decimal digit, or punctuation connector such as an underscore. Any character that matches this pattern is replaced by , which is the string defined by the replacement pattern. To allow additional characters in user input, add those characters to the character class in the regular expression pattern. For example, the regular expression pattern `[^\w\.@-\\%]` also allows a percentage symbol and a backslash in an input string. ## See Also [.NET Regular Expressions](../../../docs/standard/base-types/regular-expressions.md) diff --git a/docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md b/docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md index 8863a2870e38e..d0f4a1ae042a9 100644 --- a/docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md +++ b/docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md @@ -32,7 +32,7 @@ The following example uses a regular expression to verify that a string is in va ## Example The example defines an `IsValidEmail` method, which returns `true` if the string contains a valid email address and `false` if it does not, but takes no other action. - To verify that the email address is valid, the `IsValidEmail` method calls the method with the `(@)(.+)$` regular expression pattern to separate the domain name from the email address. The third parameter is a delegate that represents the method that processes and replaces the matched text. The regular expression pattern is interpreted as follows. + To verify that the email address is valid, the `IsValidEmail` method calls the method with the `(@)(.+)$` regular expression pattern to separate the domain name from the email address. The third parameter is a delegate that represents the method that processes and replaces the matched text. The regular expression pattern is interpreted as follows. |Pattern|Description| |-------------|-----------------| @@ -40,16 +40,16 @@ The following example uses a regular expression to verify that a string is in va |`(.+)`|Match one or more occurrences of any character. This is the second capturing group.| |`$`|End the match at the end of the string.| - The domain name along with the @ character is passed to the `DomainMapper` method, which uses the class to translate Unicode characters that are outside the US-ASCII character range to Punycode. The method also sets the `invalid` flag to `True` if the method detects any invalid characters in the domain name. The method returns the Punycode domain name preceded by the @ symbol to the `IsValidEmail` method. + The domain name along with the @ character is passed to the `DomainMapper` method, which uses the class to translate Unicode characters that are outside the US-ASCII character range to Punycode. The method also sets the `invalid` flag to `True` if the method detects any invalid characters in the domain name. The method returns the Punycode domain name preceded by the @ symbol to the `IsValidEmail` method. - The `IsValidEmail` method then calls the method to verify that the address conforms to a regular expression pattern. + The `IsValidEmail` method then calls the method to verify that the address conforms to a regular expression pattern. Note that the `IsValidEmail` method does not perform authentication to validate the email address. It merely determines whether its format is valid for an email address. In addition, the `IsValidEmail` method does not verify that the top-level domain name is a valid domain name listed at the [IANA Root Zone Database](https://www.iana.org/domains/root/db), which would require a look-up operation. Instead, the regular expression merely verifies that the top-level domain name consists of between two and twenty-four ASCII characters, with alphanumeric first and last characters and the remaining characters being either alphanumeric or a hyphen (-). [!code-csharp[RegularExpressions.Examples.Email#7](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.Email/cs/example4.cs#7)] [!code-vb[RegularExpressions.Examples.Email#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.Email/vb/example4.vb#7)] - In this example, the regular expression pattern ``^(?(")(".+?(? flag. + In this example, the regular expression pattern ``^(?(")(".+?(? flag. |Pattern|Description| |-------------|-----------------| @@ -69,7 +69,7 @@ The following example uses a regular expression to verify that a string is in va |`$`|End the match at the end of the string.| > [!NOTE] -> Instead of using a regular expression to validate an email address, you can use the class. To determine whether an email address is valid, pass the email address to the class constructor. +> Instead of using a regular expression to validate an email address, you can use the class. To determine whether an email address is valid, pass the email address to the class constructor. ## Compiling the Code The `IsValidEmail` and `DomainMapper` methods can be included in a library of regular expression utility methods, or they can be included as private static or instance methods in the application class. @@ -84,7 +84,7 @@ csc /t:library RegexUtilities.cs vbc /t:library RegexUtilities.vb ``` - You can also use the method to include this regular expression in a regular expression library. + You can also use the method to include this regular expression in a regular expression library. If they are used in a regular expression library, you can call them by using code such as the following: diff --git a/docs/standard/base-types/manipulating-strings.md b/docs/standard/base-types/manipulating-strings.md index 37e2e1e033a16..477ea94e42940 100644 --- a/docs/standard/base-types/manipulating-strings.md +++ b/docs/standard/base-types/manipulating-strings.md @@ -28,7 +28,7 @@ manager: "wpickett" Provides detailed information about .NET regular expressions, including language elements, regular expression behavior, and examples. [Basic String Operations](../../../docs/standard/base-types/basic-string-operations.md) - Describes string operations provided by the and classes, including creating new strings from arrays of bytes, comparing string values, and modifying existing strings. + Describes string operations provided by the and classes, including creating new strings from arrays of bytes, comparing string values, and modifying existing strings. ## Related Sections [Type Conversion in .NET](../../../docs/standard/base-types/type-conversion.md) diff --git a/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md b/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md index aa727dc9c5c5d..e079d88a42ac7 100644 --- a/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md @@ -60,7 +60,7 @@ Regular expressions in .NET include three miscellaneous language constructs. One |`\b`|Match a word boundary.| ## Inline Comment - The `(?#` *comment*`)` construct lets you include an inline comment in a regular expression. The regular expression engine does not use any part of the comment in pattern matching, although the comment is included in the string that is returned by the method. The comment ends at the first closing parenthesis. + The `(?#` *comment*`)` construct lets you include an inline comment in a regular expression. The regular expression engine does not use any part of the comment in pattern matching, although the comment is included in the string that is returned by the method. The comment ends at the first closing parenthesis. The following example repeats the first regular expression pattern from the example in the previous section. It adds two inline comments to the regular expression to indicate whether the comparison is case-sensitive. The regular expression pattern, `\b((?# case-sensitive comparison)D\w+)\s((?#case-insensitive comparison)d\w+)\b`, is defined as follows. @@ -79,7 +79,7 @@ Regular expressions in .NET include three miscellaneous language constructs. One [!code-vb[RegularExpressions.Language.Miscellaneous#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.miscellaneous/vb/miscellaneous2.vb#2)] ## End-of-Line Comment - A number sign (`#`)marks an x-mode comment, which starts at the unescaped # character at the end of the regular expression pattern and continues until the end of the line. To use this construct, you must either enable the `x` option (through inline options) or supply the value to the `option` parameter when instantiating the object or calling a static method. + A number sign (`#`)marks an x-mode comment, which starts at the unescaped # character at the end of the regular expression pattern and continues until the end of the line. To use this construct, you must either enable the `x` option (through inline options) or supply the value to the `option` parameter when instantiating the object or calling a static method. The following example illustrates the end-of-line comment construct. It determines whether a string is a composite format string that includes at least one format item. The following table describes the constructs in the regular expression pattern: @@ -99,7 +99,7 @@ Regular expressions in .NET include three miscellaneous language constructs. One [!code-csharp[RegularExpressions.Language.Miscellaneous#3](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.miscellaneous/cs/miscellaneous3.cs#3)] [!code-vb[RegularExpressions.Language.Miscellaneous#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.miscellaneous/vb/miscellaneous3.vb#3)] - Note that, instead of providing the `(?x)` construct in the regular expression, the comment could also have been recognized by calling the method and passing it the enumeration value. + Note that, instead of providing the `(?x)` construct in the regular expression, the comment could also have been recognized by calling the method and passing it the enumeration value. ## See Also [Regular Expression Language - Quick Reference](../../../docs/standard/base-types/regular-expression-language-quick-reference.md) diff --git a/docs/standard/base-types/padding.md b/docs/standard/base-types/padding.md index 9068c06b09e0e..368e0001d5755 100644 --- a/docs/standard/base-types/padding.md +++ b/docs/standard/base-types/padding.md @@ -25,11 +25,11 @@ Use one of the following methods to create a new string tha |Method name|Use| |-----------------|---------| -||Pads a string with leading characters to a specified total length.| -||Pads a string with trailing characters to a specified total length.| +||Pads a string with leading characters to a specified total length.| +||Pads a string with trailing characters to a specified total length.| ## PadLeft - The method creates a new string by concatenating enough leading pad characters to an original string to achieve a specified total length. The method uses white space as the padding character and the method enables you to specify your own padding character. + The method creates a new string by concatenating enough leading pad characters to an original string to achieve a specified total length. The method uses white space as the padding character and the method enables you to specify your own padding character. The following code example uses the method to create a new string that is twenty characters long. The example displays "`--------Hello World!`" to the console. @@ -38,7 +38,7 @@ Use one of the following methods to create a new string tha [!code-vb[Conceptual.String.BasicOps#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/padding.vb#3)] ## PadRight - The method creates a new string by concatenating enough trailing pad characters to an original string to achieve a specified total length. The method uses white space as the padding character and the method enables you to specify your own padding character. + The method creates a new string by concatenating enough trailing pad characters to an original string to achieve a specified total length. The method uses white space as the padding character and the method enables you to specify your own padding character. The following code example uses the method to create a new string that is twenty characters long. The example displays "`Hello World!--------`" to the console. diff --git a/docs/standard/base-types/parsing-datetime.md b/docs/standard/base-types/parsing-datetime.md index 0fcaa5cb25eac..27ed27b7c5cc6 100644 --- a/docs/standard/base-types/parsing-datetime.md +++ b/docs/standard/base-types/parsing-datetime.md @@ -31,7 +31,7 @@ Parsing methods convert the string representation of a date and time to an equiv If the string representation specifies only a time, parsing returns a object with its , , and properties set to the corresponding values of the property. However, if the constant is specified in the parsing method, the resulting year, month, and day properties are set to the value `1`. - In addition to a date and a time component, the string representation of a date and time can include an offset that indicates how much the time differs from Coordinated Universal Time (UTC). For example, the string "2/14/2007 5:32:00 -7:00" defines a time that is seven hours earlier than UTC. If an offset is omitted from the string representation of a time, parsing returns a object with its property set to . If an offset is specified, parsing returns a object with its property set to and its value adjusted to the local time zone of your machine. You can modify this behavior by using a constant with the parsing method. + In addition to a date and a time component, the string representation of a date and time can include an offset that indicates how much the time differs from Coordinated Universal Time (UTC). For example, the string "2/14/2007 5:32:00 -7:00" defines a time that is seven hours earlier than UTC. If an offset is omitted from the string representation of a time, parsing returns a object with its property set to . If an offset is specified, parsing returns a object with its property set to and its value adjusted to the local time zone of your machine. You can modify this behavior by using a constant with the parsing method. The format provider is also used to interpret an ambiguous numeric date. For example, it is not clear which components of the date represented by the string "02/03/04" are the month, day, and year. In this case, the components are interpreted according to the order of similar date formats in the format provider. @@ -41,7 +41,7 @@ Parsing methods convert the string representation of a date and time to an equiv [!code-csharp[Parsing.DateAndTime#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Parsing.DateAndTime/cs/Example.cs#1)] [!code-vb[Parsing.DateAndTime#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Parsing.DateAndTime/vb/Example.vb#1)] - You can also specify a **CultureInfo** set to one of the cultures defined by that object, or you can specify one of the standard objects returned by the property. The following code example uses a format provider to parse a German string into a **DateTime**. A **CultureInfo** representing the de-DE culture is defined and passed with the string being parsed to ensure successful parsing of this particular string. This precludes whatever setting is in the **CurrentCulture** of the **CurrentThread**. + You can also specify a **CultureInfo** set to one of the cultures defined by that object, or you can specify one of the standard objects returned by the property. The following code example uses a format provider to parse a German string into a **DateTime**. A **CultureInfo** representing the de-DE culture is defined and passed with the string being parsed to ensure successful parsing of this particular string. This precludes whatever setting is in the **CurrentCulture** of the **CurrentThread**. [!code-csharp[Parsing.DateAndTime#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Parsing.DateAndTime/cs/Example2.cs#2)] [!code-vb[Parsing.DateAndTime#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Parsing.DateAndTime/vb/Example2.vb#2)] @@ -54,9 +54,9 @@ Parsing methods convert the string representation of a date and time to an equiv [!code-vb[Parsing.DateAndTime#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Parsing.DateAndTime/vb/Example3.vb#3)] ## ParseExact - The method converts a string that conforms to a specified string pattern to a **DateTime** object. When a string that is not of the form specified is passed to this method, a is thrown. You can specify one of the standard date and time format specifiers or a limited combination of the custom date and time format specifiers. Using the custom format specifiers, it is possible for you to construct a custom recognition string. For an explanation of the specifiers, see the topics on [standard date and time format strings](../../../docs/standard/base-types/standard-date-and-time-format-strings.md) and [custom date and time format strings](../../../docs/standard/base-types/custom-date-and-time-format-strings.md). + The method converts a string that conforms to a specified string pattern to a **DateTime** object. When a string that is not of the form specified is passed to this method, a is thrown. You can specify one of the standard date and time format specifiers or a limited combination of the custom date and time format specifiers. Using the custom format specifiers, it is possible for you to construct a custom recognition string. For an explanation of the specifiers, see the topics on [standard date and time format strings](../../../docs/standard/base-types/standard-date-and-time-format-strings.md) and [custom date and time format strings](../../../docs/standard/base-types/custom-date-and-time-format-strings.md). - Each overload of the method also has an parameter that typically provides culture-specific information about the formatting of the string. Typically, this object is a object that represents a standard culture or a object that is returned by the property. However, unlike the other date and time parsing functions, this method also supports an that defines a non-standard date and time format. + Each overload of the method also has an parameter that typically provides culture-specific information about the formatting of the string. Typically, this object is a object that represents a standard culture or a object that is returned by the property. However, unlike the other date and time parsing functions, this method also supports an that defines a non-standard date and time format. In the following code example, the **ParseExact** method is passed a string object to parse, followed by a format specifier, followed by a **CultureInfo** object. This **ParseExact** method can only parse strings that exhibit the long date pattern in the en-US culture. diff --git a/docs/standard/base-types/parsing-numeric.md b/docs/standard/base-types/parsing-numeric.md index f99015f7cf20d..f6a373744709c 100644 --- a/docs/standard/base-types/parsing-numeric.md +++ b/docs/standard/base-types/parsing-numeric.md @@ -23,13 +23,13 @@ manager: "wpickett" All numeric types have two static parsing methods, `Parse` and `TryParse`, that you can use to convert the string representation of a number into a numeric type. These methods enable you to parse strings that were produced by using the format strings documented in [Standard Numeric Format Strings](../../../docs/standard/base-types/standard-numeric-format-strings.md) and [Custom Numeric Format Strings](../../../docs/standard/base-types/custom-numeric-format-strings.md). By default, the `Parse` and `TryParse` methods can successfully convert strings that contain integral decimal digits only to integer values. They can successfully convert strings that contain integral and fractional decimal digits, group separators, and a decimal separator to floating-point values. The `Parse` method throws an exception if the operation fails, whereas the `TryParse` method returns `false`. ## Parsing and Format Providers - Typically, the string representations of numeric values differ by culture. Elements of numeric strings such as currency symbols, group (or thousands) separators, and decimal separators all vary by culture. Parsing methods either implicitly or explicitly use a format provider that recognizes these culture-specific variations. If no format provider is specified in a call to the `Parse` or `TryParse` method, the format provider associated with the current thread culture (the object returned by the property) is used. + Typically, the string representations of numeric values differ by culture. Elements of numeric strings such as currency symbols, group (or thousands) separators, and decimal separators all vary by culture. Parsing methods either implicitly or explicitly use a format provider that recognizes these culture-specific variations. If no format provider is specified in a call to the `Parse` or `TryParse` method, the format provider associated with the current thread culture (the object returned by the property) is used. A format provider is represented by an implementation. This interface has a single member, the method, whose single parameter is a object that represents the type to be formatted. This method returns the object that provides formatting information. .NET supports the following two implementations for parsing numeric strings: -- A object whose method returns a object that provides culture-specific formatting information. +- A object whose method returns a object that provides culture-specific formatting information. -- A object whose method returns itself. +- A object whose method returns itself. The following example tries to convert each string in an array to a value. It first tries to parse the string by using a format provider that reflects the conventions of the English (United States) culture. If this operation throws a , it tries to parse the string by using a format provider that reflects the conventions of the French (France) culture. @@ -37,9 +37,9 @@ All numeric types have two static parsing methods, `Parse` and `TryParse`, that [!code-vb[Parsing.Numbers#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/parsing.numbers/vb/formatproviders1.vb#1)] ## Parsing and NumberStyles Values - The style elements (such as white space, group separators, and decimal separator) that the parse operation can handle are defined by a enumeration value. By default, strings that represent integer values are parsed by using the value, which permits only numeric digits, leading and trailing white space, and a leading sign. Strings that represent floating-point values are parsed using a combination of the and values; this composite style permits decimal digits along with leading and trailing white space, a leading sign, a decimal separator, a group separator, and an exponent. By calling an overload of the `Parse` or `TryParse` method that includes a parameter of type and setting one or more flags, you can control the style elements that can be present in the string for the parse operation to succeed. + The style elements (such as white space, group separators, and decimal separator) that the parse operation can handle are defined by a enumeration value. By default, strings that represent integer values are parsed by using the value, which permits only numeric digits, leading and trailing white space, and a leading sign. Strings that represent floating-point values are parsed using a combination of the and values; this composite style permits decimal digits along with leading and trailing white space, a leading sign, a decimal separator, a group separator, and an exponent. By calling an overload of the `Parse` or `TryParse` method that includes a parameter of type and setting one or more flags, you can control the style elements that can be present in the string for the parse operation to succeed. - For example, a string that contains a group separator cannot be converted to an value by using the method. However, the conversion succeeds if you use the flag, as the following example illustrates. + For example, a string that contains a group separator cannot be converted to an value by using the method. However, the conversion succeeds if you use the flag, as the following example illustrates. [!code-csharp[Parsing.Numbers#2](../../../samples/snippets/csharp/VS_Snippets_CLR/parsing.numbers/cs/styles1.cs#2)] [!code-vb[Parsing.Numbers#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/parsing.numbers/vb/styles1.vb#2)] @@ -51,33 +51,33 @@ All numeric types have two static parsing methods, `Parse` and `TryParse`, that |NumberStyles value|Effect on the string to be parsed| |------------------------|---------------------------------------| -||Only numeric digits are permitted.| -||The decimal separator and fractional digits are permitted. For integer values, only zero is permitted as a fractional digit. Valid decimal separators are determined by the or property.| -||The "e" or "E" character can be used to indicate exponential notation. See for additional information.| -||Leading white space is permitted.| -||Trailing white space is permitted.| -||A positive or negative sign can precede numeric digits.| -||A positive or negative sign can follow numeric digits.| -||Parentheses can be used to indicate negative values.| -||The group separator is permitted. The group separator character is determined by the or property.| -||The currency symbol is permitted. The currency symbol is defined by the property.| -||The string to be parsed is interpreted as a hexadecimal number. It can include the hexadecimal digits 0-9, A-F, and a-f. This flag can be used only to parse integer values.| +||Only numeric digits are permitted.| +||The decimal separator and fractional digits are permitted. For integer values, only zero is permitted as a fractional digit. Valid decimal separators are determined by the or property.| +||The "e" or "E" character can be used to indicate exponential notation. See for additional information.| +||Leading white space is permitted.| +||Trailing white space is permitted.| +||A positive or negative sign can precede numeric digits.| +||A positive or negative sign can follow numeric digits.| +||Parentheses can be used to indicate negative values.| +||The group separator is permitted. The group separator character is determined by the or property.| +||The currency symbol is permitted. The currency symbol is defined by the property.| +||The string to be parsed is interpreted as a hexadecimal number. It can include the hexadecimal digits 0-9, A-F, and a-f. This flag can be used only to parse integer values.| In addition, the enumeration provides the following composite styles, which include multiple flags. |Composite NumberStyles value|Includes members| |----------------------------------|----------------------| -||Includes the , , and styles. This is the default style used to parse integer values.| -||Includes the , , , , , and styles.| -||Includes the , , , , and styles.| -||Includes all styles except and .| -||Includes all styles except .| -||Includes the , , and styles.| +||Includes the , , and styles. This is the default style used to parse integer values.| +||Includes the , , , , , and styles.| +||Includes the , , , , and styles.| +||Includes all styles except and .| +||Includes all styles except .| +||Includes the , , and styles.| ## Parsing and Unicode Digits The Unicode standard defines code points for digits in various writing systems. For example, code points from U+0030 to U+0039 represent the basic Latin digits 0 through 9, code points from U+09E6 to U+09EF represent the Bangla digits 0 through 9, and code points from U+FF10 to U+FF19 represent the Fullwidth digits 0 through 9. However, the only numeric digits recognized by parsing methods are the basic Latin digits 0-9 with code points from U+0030 to U+0039. If a numeric parsing method is passed a string that contains any other digits, the method throws a . - The following example uses the method to parse strings that consist of digits in different writing systems. As the output from the example shows, the attempt to parse the basic Latin digits succeeds, but the attempt to parse the Fullwidth, Arabic-Indic, and Bangla digits fails. + The following example uses the method to parse strings that consist of digits in different writing systems. As the output from the example shows, the attempt to parse the basic Latin digits succeeds, but the attempt to parse the Fullwidth, Arabic-Indic, and Bangla digits fails. [!code-csharp[Parsing.Numbers#3](../../../samples/snippets/csharp/VS_Snippets_CLR/parsing.numbers/cs/unicode1.cs#3)] [!code-vb[Parsing.Numbers#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/parsing.numbers/vb/unicode1.vb#3)] diff --git a/docs/standard/base-types/quantifiers-in-regular-expressions.md b/docs/standard/base-types/quantifiers-in-regular-expressions.md index ae772241a8138..02e9e122b56f5 100644 --- a/docs/standard/base-types/quantifiers-in-regular-expressions.md +++ b/docs/standard/base-types/quantifiers-in-regular-expressions.md @@ -252,7 +252,7 @@ Quantifiers specify how many instances of a character, group, or character class ## Quantifiers and Empty Matches The quantifiers `*`, `+`, and `{`*n*`,`*m*`}` and their lazy counterparts never repeat after an empty match when the minimum number of captures has been found. This rule prevents quantifiers from entering infinite loops on empty subexpression matches when the maximum number of possible group captures is infinite or near infinite. - For example, the following code shows the result of a call to the method with the regular expression pattern `(a?)*`, which matches zero or one "a" character zero or more times. Note that the single capturing group captures each "a" as well as , but that there is no second empty match, because the first empty match causes the quantifier to stop repeating. + For example, the following code shows the result of a call to the method with the regular expression pattern `(a?)*`, which matches zero or one "a" character zero or more times. Note that the single capturing group captures each "a" as well as , but that there is no second empty match, because the first empty match causes the quantifier to stop repeating. [!code-csharp[RegularExpressions.Quantifiers.EmptyMatch#1](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/cs/emptymatch1.cs#1)] [!code-vb[RegularExpressions.Quantifiers.EmptyMatch#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/vb/emptymatch1.vb#1)] @@ -263,9 +263,9 @@ Quantifiers specify how many instances of a character, group, or character class |-------------|-----------------| |`(a\1`|Either match "a" along with the value of the first captured group …| |`|(?(1)`|… or test whether the first captured group has been defined. (Note that the `(?(1)` construct does not define a capturing group.)| -|`\1))`|If the first captured group exists, match its value. If the group does not exist, the group will match .| +|`\1))`|If the first captured group exists, match its value. If the group does not exist, the group will match .| - The first regular expression tries to match this pattern between zero and two times; the second, exactly two times. Because the first pattern reaches its minimum number of captures with its first capture of , it never repeats to try to match `a\1`; the `{0,2}` quantifier allows only empty matches in the last iteration. In contrast, the second regular expression does match "a" because it evaluates `a\1` a second time; the minimum number of iterations, 2, forces the engine to repeat after an empty match. + The first regular expression tries to match this pattern between zero and two times; the second, exactly two times. Because the first pattern reaches its minimum number of captures with its first capture of , it never repeats to try to match `a\1`; the `{0,2}` quantifier allows only empty matches in the last iteration. In contrast, the second regular expression does match "a" because it evaluates `a\1` a second time; the minimum number of iterations, 2, forces the engine to repeat after an empty match. [!code-csharp[RegularExpressions.Quantifiers.EmptyMatch#2](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/cs/emptymatch4.cs#2)] [!code-vb[RegularExpressions.Quantifiers.EmptyMatch#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.quantifiers.emptymatch/vb/emptymatch4.vb#2)] diff --git a/docs/standard/base-types/regular-expression-example-changing-date-formats.md b/docs/standard/base-types/regular-expression-example-changing-date-formats.md index d34c63808f47c..01c46afb1b219 100644 --- a/docs/standard/base-types/regular-expression-example-changing-date-formats.md +++ b/docs/standard/base-types/regular-expression-example-changing-date-formats.md @@ -22,7 +22,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Regular Expression Example: Changing Date Formats -The following code example uses the method to replace dates that have the form *mm*/*dd*/*yy* with dates that have the form *dd*-*mm*-*yy*. +The following code example uses the method to replace dates that have the form *mm*/*dd*/*yy* with dates that have the form *dd*-*mm*-*yy*. ## Example [!code-csharp[RegularExpressions.Examples.ChangeDateFormats#1](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.ChangeDateFormats/cs/Example_ChangeDateFormats1.cs#1)] diff --git a/docs/standard/base-types/regular-expression-example-scanning-for-hrefs.md b/docs/standard/base-types/regular-expression-example-scanning-for-hrefs.md index f9b4ae3dc5cb6..62f60f72d0930 100644 --- a/docs/standard/base-types/regular-expression-example-scanning-for-hrefs.md +++ b/docs/standard/base-types/regular-expression-example-scanning-for-hrefs.md @@ -25,7 +25,7 @@ manager: "wpickett" The following example searches an input string and displays all the href="…" values and their locations in the string. ## The Regex Object - Because the `DumpHRefs` method can be called multiple times from user code, it uses the `static` (`Shared` in Visual Basic) method. This enables the regular expression engine to cache the regular expression and avoids the overhead of instantiating a new object each time the method is called. A object is then used to iterate through all matches in the string. + Because the `DumpHRefs` method can be called multiple times from user code, it uses the `static` (`Shared` in Visual Basic) method. This enables the regular expression engine to cache the regular expression and avoids the overhead of instantiating a new object each time the method is called. A object is then used to iterate through all matches in the string. [!code-csharp[RegularExpressions.Examples.HREF#1](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Examples.HREF/cs/example.cs#1)] [!code-vb[RegularExpressions.Examples.HREF#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Examples.HREF/vb/example.vb#1)] @@ -48,12 +48,12 @@ The following example searches an input string and displays all the href="…" v |`"(?<1>\S+)`|Assign one or more non-white-space characters to the capturing group named `1`.| ## Match Result Class - The results of a search are stored in the class, which provides access to all the substrings extracted by the search. It also remembers the string being searched and the regular expression being used, so it can call the method to perform another search starting where the last one ended. + The results of a search are stored in the class, which provides access to all the substrings extracted by the search. It also remembers the string being searched and the regular expression being used, so it can call the method to perform another search starting where the last one ended. ## Explicitly Named Captures In traditional regular expressions, capturing parentheses are automatically numbered sequentially. This leads to two problems. First, if a regular expression is modified by inserting or removing a set of parentheses, all code that refers to the numbered captures must be rewritten to reflect the new numbering. Second, because different sets of parentheses often are used to provide two alternative expressions for an acceptable match, it might be difficult to determine which of the two expressions actually returned a result. - To address these problems, the class supports the syntax `(?…)` for capturing a match into a specified slot (the slot can be named using a string or an integer; integers can be recalled more quickly). Thus, alternative matches for the same string all can be directed to the same place. In case of a conflict, the last match dropped into a slot is the successful match. (However, a complete list of multiple matches for a single slot is available. See the collection for details.) + To address these problems, the class supports the syntax `(?…)` for capturing a match into a specified slot (the slot can be named using a string or an integer; integers can be recalled more quickly). Thus, alternative matches for the same string all can be directed to the same place. In case of a conflict, the last match dropped into a slot is the successful match. (However, a complete list of multiple matches for a single slot is available. See the collection for details.) ## See Also [.NET Regular Expressions](../../../docs/standard/base-types/regular-expressions.md) diff --git a/docs/standard/base-types/regular-expression-language-quick-reference.md b/docs/standard/base-types/regular-expression-language-quick-reference.md index ad5b1ade4b979..3122e3326de5a 100644 --- a/docs/standard/base-types/regular-expression-language-quick-reference.md +++ b/docs/standard/base-types/regular-expression-language-quick-reference.md @@ -219,7 +219,7 @@ manager: "wpickett" |`#` [to end of line]|X-mode comment. The comment starts at an unescaped `#` and continues to the end of the line.|`(?x)\bA\w+\b#Matches words starting with A`| ## See Also - + [Regular Expressions](regular-expressions.md) [Regular Expression Classes](the-regular-expression-object-model.md) diff --git a/docs/standard/base-types/regular-expression-options.md b/docs/standard/base-types/regular-expression-options.md index 11c4c57cdd9b1..eb425d0824476 100644 --- a/docs/standard/base-types/regular-expression-options.md +++ b/docs/standard/base-types/regular-expression-options.md @@ -21,7 +21,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Regular Expression Options - By default, the comparison of an input string with any literal characters in a regular expression pattern is case sensitive, white space in a regular expression pattern is interpreted as literal white-space characters, and capturing groups in a regular expression are named implicitly as well as explicitly. You can modify these and several other aspects of default regular expression behavior by specifying regular expression options. These options, which are listed in the following table, can be included inline as part of the regular expression pattern, or they can be supplied to a class constructor or static pattern matching method as a enumeration value. + By default, the comparison of an input string with any literal characters in a regular expression pattern is case sensitive, white space in a regular expression pattern is interpreted as literal white-space characters, and capturing groups in a regular expression are named implicitly as well as explicitly. You can modify these and several other aspects of default regular expression behavior by specifying regular expression options. These options, which are listed in the following table, can be included inline as part of the regular expression pattern, or they can be supplied to a class constructor or static pattern matching method as a enumeration value. |RegexOptions member|Inline character|Effect| |-------------------------|----------------------|------------| @@ -39,16 +39,16 @@ manager: "wpickett" ## Specifying the Options You can specify options for regular expressions in one of three ways: -- In the `options` parameter of a class constructor or static (`Shared` in Visual Basic) pattern-matching method, such as or . The `options` parameter is a bitwise OR combination of enumerated values. +- In the `options` parameter of a class constructor or static (`Shared` in Visual Basic) pattern-matching method, such as or . The `options` parameter is a bitwise OR combination of enumerated values. - When options are supplied to a instance by using the `options` parameter of a class constructor, the options are are assigned to the property. However, the property does not reflect inline options in the regular expression pattern itself. + When options are supplied to a instance by using the `options` parameter of a class constructor, the options are are assigned to the property. However, the property does not reflect inline options in the regular expression pattern itself. - The following example provides an illustration. It uses the `options` parameter of the method to enable case-insensitive matching and to ignore pattern white space when identifying words that begin with the letter "d". + The following example provides an illustration. It uses the `options` parameter of the method to enable case-insensitive matching and to ignore pattern white space when identifying words that begin with the letter "d". [!code-csharp[Conceptual.Regex.Language.Options#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/example1.cs#6)] [!code-vb[Conceptual.Regex.Language.Options#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/example1.vb#6)] -- By applying inline options in a regular expression pattern with the syntax `(?imnsx-imnsx)`. The option applies to the pattern from the point that the option is defined to either the end of the pattern or to the point at which the option is undefined by another inline option. Note that the property of a instance does not reflect these inline options. For more information, see the [Miscellaneous Constructs](../../../docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md) topic. +- By applying inline options in a regular expression pattern with the syntax `(?imnsx-imnsx)`. The option applies to the pattern from the point that the option is defined to either the end of the pattern or to the point at which the option is undefined by another inline option. Note that the property of a instance does not reflect these inline options. For more information, see the [Miscellaneous Constructs](../../../docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md) topic. The following example provides an illustration. It uses inline options to enable case-insensitive matching and to ignore pattern white space when identifying words that begin with the letter "d". @@ -62,44 +62,44 @@ manager: "wpickett" [!code-csharp[Conceptual.Regex.Language.Options#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/example1.cs#8)] [!code-vb[Conceptual.Regex.Language.Options#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/example1.vb#8)] - If options are specified inline, a minus sign (`-`) before an option or set of options turns off those options. For example, the inline construct `(?ix-ms)` turns on the and options and turns off the and options. All regular expression options are turned off by default. + If options are specified inline, a minus sign (`-`) before an option or set of options turns off those options. For example, the inline construct `(?ix-ms)` turns on the and options and turns off the and options. All regular expression options are turned off by default. > [!NOTE] > If the regular expression options specified in the `options` parameter of a constructor or method call conflict with the options specified inline in a regular expression pattern, the inline options are used. The following five regular expression options can be set both with the options parameter and inline: -- +- -- +- -- +- -- +- -- +- The following five regular expression options can be set using the `options` parameter but cannot be set inline: -- +- -- +- -- +- -- +- -- +- ## Determining the Options - You can determine which options were provided to a object when it was instantiated by retrieving the value of the read-only property. This property is particularly useful for determining the options that are defined for a compiled regular expression created by the method. + You can determine which options were provided to a object when it was instantiated by retrieving the value of the read-only property. This property is particularly useful for determining the options that are defined for a compiled regular expression created by the method. - To test for the presence of any option except , perform an AND operation with the value of the property and the value in which you are interested. Then test whether the result equals that value. The following example tests whether the option has been set. + To test for the presence of any option except , perform an AND operation with the value of the property and the value in which you are interested. Then test whether the result equals that value. The following example tests whether the option has been set. [!code-csharp[Conceptual.Regex.Language.Options#19](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/determine1.cs#19)] [!code-vb[Conceptual.Regex.Language.Options#19](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/determine1.vb#19)] - To test for , determine whether the value of the property is equal to , as the following example illustrates. + To test for , determine whether the value of the property is equal to , as the following example illustrates. [!code-csharp[Conceptual.Regex.Language.Options#20](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/determine1.cs#20)] [!code-vb[Conceptual.Regex.Language.Options#20](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/determine1.vb#20)] @@ -108,7 +108,7 @@ manager: "wpickett" ## Default Options - The option indicates that no options have been specified, and the regular expression engine uses its default behavior. This includes the following: + The option indicates that no options have been specified, and the regular expression engine uses its default behavior. This includes the following: - The pattern is interpreted as a canonical rather than an ECMAScript regular expression. @@ -127,9 +127,9 @@ manager: "wpickett" - Capturing groups in the regular expression pattern are implicit as well as explicit. > [!NOTE] -> The option has no inline equivalent. When regular expression options are applied inline, the default behavior is restored on an option-by-option basis, by turning a particular option off. For example, `(?i)` turns on case-insensitive comparison, and `(?-i)` restores the default case-sensitive comparison. +> The option has no inline equivalent. When regular expression options are applied inline, the default behavior is restored on an option-by-option basis, by turning a particular option off. For example, `(?i)` turns on case-insensitive comparison, and `(?-i)` restores the default case-sensitive comparison. - Because the option represents the default behavior of the regular expression engine, it is rarely explicitly specified in a method call. A constructor or static pattern-matching method without an `options` parameter is called instead. + Because the option represents the default behavior of the regular expression engine, it is rarely explicitly specified in a method call. A constructor or static pattern-matching method without an `options` parameter is called instead. [Back to Top](#Top) @@ -151,11 +151,11 @@ manager: "wpickett" ## Multiline Mode - The option, or the `m` inline option, enables the regular expression engine to handle an input string that consists of multiple lines. It changes the interpretation of the `^` and `$` language elements so that they match the beginning and end of a line, instead of the beginning and end of the input string. + The option, or the `m` inline option, enables the regular expression engine to handle an input string that consists of multiple lines. It changes the interpretation of the `^` and `$` language elements so that they match the beginning and end of a line, instead of the beginning and end of the input string. - By default, `$` matches only the end of the input string. If you specify the option, it matches either the newline character (`\n`) or the end of the input string. It does not, however, match the carriage return/line feed character combination. To successfully match them, use the subexpression `\r?$` instead of just `$`. + By default, `$` matches only the end of the input string. If you specify the option, it matches either the newline character (`\n`) or the end of the input string. It does not, however, match the carriage return/line feed character combination. To successfully match them, use the subexpression `\r?$` instead of just `$`. - The following example extracts bowlers' names and scores and adds them to a collection that sorts them in descending order. The method is called twice. In the first method call, the regular expression is `^(\w+)\s(\d+)$` and no options are set. As the output shows, because the regular expression engine cannot match the input pattern along with the beginning and end of the input string, no matches are found. In the second method call, the regular expression is changed to `^(\w+)\s(\d+)\r?$` and the options are set to . As the output shows, the names and scores are successfully matched, and the scores are displayed in descending order. + The following example extracts bowlers' names and scores and adds them to a collection that sorts them in descending order. The method is called twice. In the first method call, the regular expression is `^(\w+)\s(\d+)$` and no options are set. As the output shows, because the regular expression engine cannot match the input pattern along with the beginning and end of the input string, no matches are found. In the second method call, the regular expression is changed to `^(\w+)\s(\d+)\r?$` and the options are set to . As the output shows, the names and scores are successfully matched, and the scores are displayed in descending order. [!code-csharp[Conceptual.Regex.Language.Options#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/multiline1.cs#3)] [!code-vb[Conceptual.Regex.Language.Options#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/multiline1.vb#3)] @@ -180,9 +180,9 @@ manager: "wpickett" ## Single-line Mode - The option, or the `s` inline option, causes the regular expression engine to treat the input string as if it consists of a single line. It does this by changing the behavior of the period (`.`) language element so that it matches every character, instead of matching every character except for the newline character `\n` or \u000A. + The option, or the `s` inline option, causes the regular expression engine to treat the input string as if it consists of a single line. It does this by changing the behavior of the period (`.`) language element so that it matches every character, instead of matching every character except for the newline character `\n` or \u000A. - The following example illustrates how the behavior of the `.` language element changes when you use the option. The regular expression `^.+` starts at the beginning of the string and matches every character. By default, the match ends at the end of the first line; the regular expression pattern matches the carriage return character, `\r` or \u000D, but it does not match `\n`. Because the option interprets the entire input string as a single line, it matches every character in the input string, including `\n`. + The following example illustrates how the behavior of the `.` language element changes when you use the option. The regular expression `^.+` starts at the beginning of the string and matches every character. By default, the match ends at the end of the first line; the regular expression pattern matches the carriage return character, `\r` or \u000D, but it does not match `\n`. Because the option interprets the entire input string as a single line, it matches every character in the input string, including `\n`. [!code-csharp[Conceptual.Regex.Language.CharacterClasses#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.characterclasses/cs/any2.cs#5)] [!code-vb[Conceptual.Regex.Language.CharacterClasses#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.characterclasses/vb/any2.vb#5)] @@ -206,9 +206,9 @@ manager: "wpickett" is intended only to extract sentences that end with a period, exclamation point, or question mark from a document, only the resulting sentence (which is represented by the object) is of interest. The individual words in the collection are not. - Capturing groups that are not subsequently used can be expensive, because the regular expression engine must populate both the and collection objects. As an alternative, you can use either the option or the `n` inline option to specify that the only valid captures are explicitly named or numbered groups that are designated by the `(?<`*name*`>` *subexpression*`)` construct. + Capturing groups that are not subsequently used can be expensive, because the regular expression engine must populate both the and collection objects. As an alternative, you can use either the option or the `n` inline option to specify that the only valid captures are explicitly named or numbered groups that are designated by the `(?<`*name*`>` *subexpression*`)` construct. - The following example displays information about the matches returned by the `\b\(?((\w+),?\s?)+[\.!?]\)?` regular expression pattern when the method is called with and without the option. As the output from the first method call shows, the regular expression engine fully populates the and collection objects with information about captured substrings. Because the second method is called with `options` set to , it does not capture information on groups. + The following example displays information about the matches returned by the `\b\(?((\w+),?\s?)+[\.!?]\)?` regular expression pattern when the method is called with and without the option. As the output from the first method call shows, the regular expression engine fully populates the and collection objects with information about captured substrings. Because the second method is called with `options` set to , it does not capture information on groups. [!code-csharp[Conceptual.Regex.Language.Options#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/explicit1.cs#9)] [!code-vb[Conceptual.Regex.Language.Options#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/explicit1.vb#9)] @@ -224,7 +224,7 @@ manager: "wpickett" |`((\w+),?\s?)+`|Match the combination of one or more word characters, zero or one commas, and zero or one white-space characters one or more times.| |`[\.!?]\)?`|Match any of the three punctuation symbols, followed by zero or one closing parentheses (")").| - You can also use the `(?n)` inline element to suppress automatic captures. The following example modifies the previous regular expression pattern to use the `(?n)` inline element instead of the option. + You can also use the `(?n)` inline element to suppress automatic captures. The following example modifies the previous regular expression pattern to use the `(?n)` inline element instead of the option. [!code-csharp[Conceptual.Regex.Language.Options#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/explicit2.cs#10)] [!code-vb[Conceptual.Regex.Language.Options#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/explicit2.vb#10)] @@ -240,12 +240,12 @@ manager: "wpickett" ## Compiled Regular Expressions By default, regular expressions in .NET are interpreted. When a object is instantiated or a static method is called, the regular expression pattern is parsed into a set of custom opcodes, and an interpreter uses these opcodes to run the regular expression. This involves a tradeoff: The cost of initializing the regular expression engine is minimized at the expense of run-time performance. - You can use compiled instead of interpreted regular expressions by using the option. In this case, when a pattern is passed to the regular expression engine, it is parsed into a set of opcodes and then converted to Microsoft intermediate language (MSIL), which can be passed directly to the common language runtime. Compiled regular expressions maximize run-time performance at the expense of initialization time. + You can use compiled instead of interpreted regular expressions by using the option. In this case, when a pattern is passed to the regular expression engine, it is parsed into a set of opcodes and then converted to Microsoft intermediate language (MSIL), which can be passed directly to the common language runtime. Compiled regular expressions maximize run-time performance at the expense of initialization time. > [!NOTE] -> A regular expression can be compiled only by supplying the value to the `options` parameter of a class constructor or a static pattern-matching method. It is not available as an inline option. +> A regular expression can be compiled only by supplying the value to the `options` parameter of a class constructor or a static pattern-matching method. It is not available as an inline option. - You can use compiled regular expressions in calls to both static and instance regular expressions. In static regular expressions, the option is passed to the `options` parameter of the regular expression pattern-matching method. In instance regular expressions, it is passed to the `options` parameter of the class constructor. In both cases, it results in enhanced performance. + You can use compiled regular expressions in calls to both static and instance regular expressions. In static regular expressions, the option is passed to the `options` parameter of the regular expression pattern-matching method. In instance regular expressions, it is passed to the `options` parameter of the class constructor. In both cases, it results in enhanced performance. However, this improvement in performance occurs only under the following conditions: @@ -256,7 +256,7 @@ manager: "wpickett" - A static regular expression is used in multiple calls to regular expression pattern-matching methods. (The performance improvement is possible because regular expressions used in static method calls are cached by the regular expression engine.) > [!NOTE] -> The option is unrelated to the method, which creates a special-purpose assembly that contains predefined compiled regular expressions. +> The option is unrelated to the method, which creates a special-purpose assembly that contains predefined compiled regular expressions. [Back to Top](#Top) @@ -264,13 +264,13 @@ manager: "wpickett" ## Ignore White Space By default, white space in a regular expression pattern is significant; it forces the regular expression engine to match a white-space character in the input string. Because of this, the regular expression "`\b\w+\s`" and "`\b\w+` " are roughly equivalent regular expressions. In addition, when the number sign (#) is encountered in a regular expression pattern, it is interpreted as a literal character to be matched. - The option, or the `x` inline option, changes this default behavior as follows: + The option, or the `x` inline option, changes this default behavior as follows: - Unescaped white space in the regular expression pattern is ignored. To be part of a regular expression pattern, white-space characters must be escaped (for example, as `\s` or "`\` "). - The number sign (#) is interpreted as the beginning of a comment, rather than as a literal character. All text in the regular expression pattern from the # character to the end of the string is interpreted as a comment. - However, in the following cases, white space characters in a regular expression aren't ignored, even if you use the option: + However, in the following cases, white space characters in a regular expression aren't ignored, even if you use the option: - White space within a character class is always interpreted literally. For example, the regular expression pattern `[ .,;:]` matches any single white-space character, period, comma, semicolon, or colon. @@ -288,7 +288,7 @@ manager: "wpickett" `\b \(? ( (?>\w+) ,?\s? )+ [\.!?] \)? # Matches an entire sentence.` - This pattern is similar to the pattern defined in the [Explicit Captures Only](#Explicit) section, except that it uses the option to ignore pattern white space. + This pattern is similar to the pattern defined in the [Explicit Captures Only](#Explicit) section, except that it uses the option to ignore pattern white space. [!code-csharp[Conceptual.Regex.Language.Options#12](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/whitespace1.cs#12)] [!code-vb[Conceptual.Regex.Language.Options#12](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/whitespace1.vb#12)] @@ -302,12 +302,12 @@ manager: "wpickett" ## Right-to-Left Mode - By default, the regular expression engine searches from left to right. You can reverse the search direction by using the option. The search automatically begins at the last character position of the string. For pattern-matching methods that include a starting position parameter, such as , the starting position is the index of the rightmost character position at which the search is to begin. + By default, the regular expression engine searches from left to right. You can reverse the search direction by using the option. The search automatically begins at the last character position of the string. For pattern-matching methods that include a starting position parameter, such as , the starting position is the index of the rightmost character position at which the search is to begin. > [!NOTE] -> Right-to-left pattern mode is available only by supplying the value to the `options` parameter of a class constructor or static pattern-matching method. It is not available as an inline option. +> Right-to-left pattern mode is available only by supplying the value to the `options` parameter of a class constructor or static pattern-matching method. It is not available as an inline option. - The option changes the search direction only; it does not interpret the regular expression pattern from right to left. For example, the regular expression `\bb\w+\s` matches words that begin with the letter "b" and are followed by a white-space character. In the following example, the input string consists of three words that include one or more "b" characters. The first word begins with "b", the second ends with "b", and the third includes two "b" characters in the middle of the word. As the output from the example shows, only the first word matches the regular expression pattern. + The option changes the search direction only; it does not interpret the regular expression pattern from right to left. For example, the regular expression `\bb\w+\s` matches words that begin with the letter "b" and are followed by a white-space character. In the following example, the input string consists of three words that include one or more "b" characters. The first word begins with "b", the second ends with "b", and the third includes two "b" characters in the middle of the word. As the output from the example shows, only the first word matches the regular expression pattern. [!code-csharp[Conceptual.Regex.Language.Options#17](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/righttoleft1.cs#17)] [!code-vb[Conceptual.Regex.Language.Options#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/righttoleft1.vb#17)] @@ -331,18 +331,18 @@ manager: "wpickett" ## ECMAScript Matching Behavior - By default, the regular expression engine uses canonical behavior when matching a regular expression pattern to input text. However, you can instruct the regular expression engine to use ECMAScript matching behavior by specifying the option. + By default, the regular expression engine uses canonical behavior when matching a regular expression pattern to input text. However, you can instruct the regular expression engine to use ECMAScript matching behavior by specifying the option. > [!NOTE] -> ECMAScript-compliant behavior is available only by supplying the value to the `options` parameter of a class constructor or static pattern-matching method. It is not available as an inline option. +> ECMAScript-compliant behavior is available only by supplying the value to the `options` parameter of a class constructor or static pattern-matching method. It is not available as an inline option. - The option can be combined only with the and options. The use of any other option in a regular expression results in an . + The option can be combined only with the and options. The use of any other option in a regular expression results in an . The behavior of ECMAScript and canonical regular expressions differs in three areas: character class syntax, self-referencing capturing groups, and octal versus backreference interpretation. - Character class syntax. Because canonical regular expressions support Unicode whereas ECMAScript does not, character classes in ECMAScript have a more limited syntax, and some character class language elements have a different meaning. For example, ECMAScript does not support language elements such as the Unicode category or block elements `\p` and `\P`. Similarly, the `\w` element, which matches a word character, is equivalent to the `[a-zA-Z_0-9]` character class when using ECMAScript and `[\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}\p{Lm}]` when using canonical behavior. For more information, see [Character Classes](../../../docs/standard/base-types/character-classes-in-regular-expressions.md). - The following example illustrates the difference between canonical and ECMAScript pattern matching. It defines a regular expression, `\b(\w+\s*)+`, that matches words followed by white-space characters. The input consists of two strings, one that uses the Latin character set and the other that uses the Cyrillic character set. As the output shows, the call to the method that uses ECMAScript matching fails to match the Cyrillic words, whereas the method call that uses canonical matching does match these words. + The following example illustrates the difference between canonical and ECMAScript pattern matching. It defines a regular expression, `\b(\w+\s*)+`, that matches words followed by white-space characters. The input consists of two strings, one that uses the Latin character set and the other that uses the Cyrillic character set. As the output shows, the call to the method that uses ECMAScript matching fails to match the Cyrillic words, whereas the method call that uses canonical matching does match these words. [!code-csharp[Conceptual.Regex.Language.Options#16](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/ecmascript1.cs#16)] [!code-vb[Conceptual.Regex.Language.Options#16](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/ecmascript1.vb#16)] @@ -375,7 +375,7 @@ manager: "wpickett" ## Comparison Using the Invariant Culture By default, when the regular expression engine performs case-insensitive comparisons, it uses the casing conventions of the current culture to determine equivalent uppercase and lowercase characters. - However, this behavior is undesirable for some types of comparisons, particularly when comparing user input to the names of system resources, such as passwords, files, or URLs. The following example illustrates such as scenario. The code is intended to block access to any resource whose URL is prefaced with **FILE://**. The regular expression attempts a case-insensitive match with the string by using the regular expression `$FILE://`. However, when the current system culture is tr-TR (Turkish-Turkey), "I" is not the uppercase equivalent of "i". As a result, the call to the method returns `false`, and access to the file is allowed. + However, this behavior is undesirable for some types of comparisons, particularly when comparing user input to the names of system resources, such as passwords, files, or URLs. The following example illustrates such as scenario. The code is intended to block access to any resource whose URL is prefaced with **FILE://**. The regular expression attempts a case-insensitive match with the string by using the regular expression `$FILE://`. However, when the current system culture is tr-TR (Turkish-Turkey), "I" is not the uppercase equivalent of "i". As a result, the call to the method returns `false`, and access to the file is allowed. [!code-csharp[Conceptual.Regex.Language.Options#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/culture1.cs#14)] [!code-vb[Conceptual.Regex.Language.Options#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/culture1.vb#14)] @@ -383,12 +383,12 @@ manager: "wpickett" > [!NOTE] > For more information about string comparisons that are case-sensitive and that use the invariant culture, see [Best Practices for Using Strings](../../../docs/standard/base-types/best-practices-strings.md). - Instead of using the case-insensitive comparisons of the current culture, you can specify the option to ignore cultural differences in language and to use the conventions of the invariant culture. + Instead of using the case-insensitive comparisons of the current culture, you can specify the option to ignore cultural differences in language and to use the conventions of the invariant culture. > [!NOTE] -> Comparison using the invariant culture is available only by supplying the value to the `options` parameter of a class constructor or static pattern-matching method. It is not available as an inline option. +> Comparison using the invariant culture is available only by supplying the value to the `options` parameter of a class constructor or static pattern-matching method. It is not available as an inline option. - The following example is identical to the previous example, except that the static method is called with options that include . Even when the current culture is set to Turkish (Turkey), the regular expression engine is able to successfully match "FILE" and "file" and block access to the file resource. + The following example is identical to the previous example, except that the static method is called with options that include . Even when the current culture is set to Turkish (Turkey), the regular expression engine is able to successfully match "FILE" and "file" and block access to the file resource. [!code-csharp[Conceptual.Regex.Language.Options#15](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.options/cs/culture1.cs#15)] [!code-vb[Conceptual.Regex.Language.Options#15](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.options/vb/culture1.vb#15)] diff --git a/docs/standard/base-types/regular-expressions.md b/docs/standard/base-types/regular-expressions.md index 6ce71e0b8f5b7..ba4a042004065 100644 --- a/docs/standard/base-types/regular-expressions.md +++ b/docs/standard/base-types/regular-expressions.md @@ -32,7 +32,7 @@ manager: "wpickett" Regular expressions provide a powerful, flexible, and efficient method for processing text. The extensive pattern-matching notation of regular expressions enables you to quickly parse large amounts of text to find specific character patterns; to validate text to ensure that it matches a predefined pattern (such as an e-mail address); to extract, edit, replace, or delete text substrings; and to add the extracted strings to a collection in order to generate a report. For many applications that deal with strings or that parse large blocks of text, regular expressions are an indispensable tool. ## How Regular Expressions Work - The centerpiece of text processing with regular expressions is the regular expression engine, which is represented by the object in .NET. At a minimum, processing text using regular expressions requires that the regular expression engine be provided with the following two items of information: + The centerpiece of text processing with regular expressions is the regular expression engine, which is represented by the object in .NET. At a minimum, processing text using regular expressions requires that the regular expression engine be provided with the following two items of information: - The regular expression pattern to identify in the text. @@ -42,11 +42,11 @@ Regular expressions provide a powerful, flexible, and efficient method for proce The methods of the class let you perform the following operations: -- Determine whether the regular expression pattern occurs in the input text by calling the method. For an example that uses the method for validating text, see [How to: Verify that Strings Are in Valid Email Format](../../../docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md). +- Determine whether the regular expression pattern occurs in the input text by calling the method. For an example that uses the method for validating text, see [How to: Verify that Strings Are in Valid Email Format](../../../docs/standard/base-types/how-to-verify-that-strings-are-in-valid-email-format.md). -- Retrieve one or all occurrences of text that matches the regular expression pattern by calling the or method. The former method returns a object that provides information about the matching text. The latter returns a object that contains one object for each match found in the parsed text. +- Retrieve one or all occurrences of text that matches the regular expression pattern by calling the or method. The former method returns a object that provides information about the matching text. The latter returns a object that contains one object for each match found in the parsed text. -- Replace text that matches the regular expression pattern by calling the method. For examples that use the method to change date formats and remove invalid characters from a string, see [How to: Strip Invalid Characters from a String](../../../docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md) and [Example: Changing Date Formats](../../../docs/standard/base-types/regular-expression-example-changing-date-formats.md). +- Replace text that matches the regular expression pattern by calling the method. For examples that use the method to change date formats and remove invalid characters from a string, see [How to: Strip Invalid Characters from a String](../../../docs/standard/base-types/how-to-strip-invalid-characters-from-a-string.md) and [Example: Changing Date Formats](../../../docs/standard/base-types/regular-expression-example-changing-date-formats.md). For an overview of the regular expression object model, see [The Regular Expression Object Model](../../../docs/standard/base-types/the-regular-expression-object-model.md). @@ -64,7 +64,7 @@ Regular expressions provide a powerful, flexible, and efficient method for proce [!code-csharp[Conceptual.Regex#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex/cs/example1.cs#2)] [!code-vb[Conceptual.Regex#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex/vb/example1.vb#2)] - The regular expression pattern`(Mr\.? |Mrs\.? |Miss |Ms\.? )` matches any occurrence of "Mr ", "Mr. ", "Mrs ", "Mrs. ", "Miss ", "Ms or "Ms. ". The call to the method replaces the matched string with ; in other words, it removes it from the original string. + The regular expression pattern`(Mr\.? |Mrs\.? |Miss |Ms\.? )` matches any occurrence of "Mr ", "Mr. ", "Mrs ", "Mrs. ", "Miss ", "Ms or "Ms. ". The call to the method replaces the matched string with ; in other words, it removes it from the original string. ### Example 2: Identifying Duplicated Words Accidentally duplicating words is a common error that writers make. A regular expression can be used to identify duplicated words, as the following example shows. @@ -82,7 +82,7 @@ Regular expressions provide a powerful, flexible, and efficient method for proce |`\1`|Match the substring that is equal to the group named `\1`.| |`\b`|Match a word boundary.| - The method is called with regular expression options set to . Therefore, the match operation is case-insensitive, and the example identifies the substring "This this" as a duplication. + The method is called with regular expression options set to . Therefore, the match operation is case-insensitive, and the example identifies the substring "This this" as a duplication. Note that the input string includes the substring "this? This". However, because of the intervening punctuation mark, it is not identified as a duplication. @@ -99,7 +99,7 @@ Regular expressions provide a powerful, flexible, and efficient method for proce |`\$`|Look for a single occurrence of the dollar symbol ($) in the input string. The regular expression pattern string includes a backslash to indicate that the dollar symbol is to be interpreted literally rather than as a regular expression anchor. (The $ symbol alone would indicate that the regular expression engine should try to begin its match at the end of a string.) To ensure that the current culture's currency symbol is not misinterpreted as a regular expression symbol, the example calls the method to escape the character.| |`\s*`|Look for zero or more occurrences of a white-space character.| |`[-+]?`|Look for zero or one occurrence of either a positive sign or a negative sign.| -|`([0-9]{0,3}(,[0-9]{3})*(\.[0-9]+)?)`|The outer parentheses around this expression define it as a capturing group or a subexpression. If a match is found, information about this part of the matching string can be retrieved from the second object in the object returned by the property. (The first element in the collection represents the entire match.)| +|`([0-9]{0,3}(,[0-9]{3})*(\.[0-9]+)?)`|The outer parentheses around this expression define it as a capturing group or a subexpression. If a match is found, information about this part of the matching string can be retrieved from the second object in the object returned by the property. (The first element in the collection represents the entire match.)| |`[0-9]{0,3}`|Look for zero to three occurrences of the decimal digits 0 through 9.| |`(,[0-9]{3})*`|Look for zero or more occurrences of a group separator followed by three decimal digits.| |`\.`|Look for a single occurrence of the decimal separator.| @@ -118,7 +118,7 @@ Regular expressions provide a powerful, flexible, and efficient method for proce |[Regular Expression Examples](../../../docs/standard/base-types/regular-expression-examples.md)|Provides code examples that illustrate typical uses of regular expressions.| ## Reference - - + + [Regular Expressions - Quick Reference (download in Word format)](http://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.docx) [Regular Expressions - Quick Reference (download in PDF format)](http://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.pdf) diff --git a/docs/standard/base-types/standard-date-and-time-format-strings.md b/docs/standard/base-types/standard-date-and-time-format-strings.md index 7bbbe1a8ca57f..b2cd2597bda00 100644 --- a/docs/standard/base-types/standard-date-and-time-format-strings.md +++ b/docs/standard/base-types/standard-date-and-time-format-strings.md @@ -87,7 +87,7 @@ A standard date and time format string uses a single format specifier to define |"s"||yyyy'-'MM'-'dd'T'HH':'mm':'ss| |"u"||yyyy'-'MM'-'dd HH':'mm':'ss'Z'| - Standard format strings can also be used in parsing operations with the or methods, which require an input string to exactly conform to a particular pattern for the parse operation to succeed. Many standard format strings map to multiple custom format strings, so a date and time value can be represented in a variety of formats and the parse operation will still succeed. You can determine the custom format string or strings that correspond to a standard format string by calling the method. The following example displays the custom format strings that map to the "d" (short date pattern) standard format string. + Standard format strings can also be used in parsing operations with the or methods, which require an input string to exactly conform to a particular pattern for the parse operation to succeed. Many standard format strings map to multiple custom format strings, so a date and time value can be represented in a variety of formats and the parse operation will still succeed. You can determine the custom format string or strings that correspond to a standard format string by calling the method. The following example displays the custom format strings that map to the "d" (short date pattern) standard format string. [!code-csharp[Formatting.DateAndTime.Standard#17](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.DateAndTime.Standard/cs/stdandparsing1.cs#17)] [!code-vb[Formatting.DateAndTime.Standard#17](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.DateAndTime.Standard/vb/stdandparsing1.vb#17)] @@ -96,7 +96,7 @@ A standard date and time format string uses a single format specifier to define ## The Short Date ("d") Format Specifier - The "d" standard format specifier represents a custom date and time format string that is defined by a specific culture's property. For example, the custom format string that is returned by the property of the invariant culture is "MM/dd/yyyy". + The "d" standard format specifier represents a custom date and time format string that is defined by a specific culture's property. For example, the custom format string that is returned by the property of the invariant culture is "MM/dd/yyyy". The following table lists the object properties that control the formatting of the returned string. @@ -114,7 +114,7 @@ A standard date and time format string uses a single format specifier to define ## The Long Date ("D") Format Specifier - The "D" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "dddd, dd MMMM yyyy". + The "D" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "dddd, dd MMMM yyyy". The following table lists the properties of the object that control the formatting of the returned string. @@ -135,7 +135,7 @@ A standard date and time format string uses a single format specifier to define ## The Full Date Short Time ("f") Format Specifier The "f" standard format specifier represents a combination of the long date ("D") and short time ("t") patterns, separated by a space. - The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier returned by the and properties of some cultures may not make use of all properties. + The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier returned by the and properties of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| @@ -156,7 +156,7 @@ A standard date and time format string uses a single format specifier to define ## The Full Date Long Time ("F") Format Specifier - The "F" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "dddd, dd MMMM yyyy HH:mm:ss". + The "F" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "dddd, dd MMMM yyyy HH:mm:ss". The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. @@ -180,7 +180,7 @@ A standard date and time format string uses a single format specifier to define ## The General Date Short Time ("g") Format Specifier The "g" standard format specifier represents a combination of the short date ("d") and short time ("t") patterns, separated by a space. - The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the and properties of some cultures may not make use of all properties. + The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the and properties of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| @@ -202,7 +202,7 @@ A standard date and time format string uses a single format specifier to define ## The General Date Long Time ("G") Format Specifier The "G" standard format specifier represents a combination of the short date ("d") and long time ("T") patterns, separated by a space. - The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the and properties of some cultures may not make use of all properties. + The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the and properties of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| @@ -222,7 +222,7 @@ A standard date and time format string uses a single format specifier to define ## The Month ("M", "m") Format Specifier - The "M" or "m" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "MMMM dd". + The "M" or "m" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "MMMM dd". The following table lists the object properties that control the formatting of the returned string. @@ -240,21 +240,21 @@ A standard date and time format string uses a single format specifier to define ## The Round-trip ("O", "o") Format Specifier - The "O" or "o" standard format specifier represents a custom date and time format string using a pattern that preserves time zone information and emits a result string that complies with ISO 8601. For values, this format specifier is designed to preserve date and time values along with the property in text. The formatted string can be parsed back by using the or method if the `styles` parameter is set to . + The "O" or "o" standard format specifier represents a custom date and time format string using a pattern that preserves time zone information and emits a result string that complies with ISO 8601. For values, this format specifier is designed to preserve date and time values along with the property in text. The formatted string can be parsed back by using the or method if the `styles` parameter is set to . The "O" or "o" standard format specifier corresponds to the "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK" custom format string for values and to the "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffzzz" custom format string for values. In this string, the pairs of single quotation marks that delimit individual characters, such as the hyphens, the colons, and the letter "T", indicate that the individual character is a literal that cannot be changed. The apostrophes do not appear in the output string. The O" or "o" standard format specifier (and the "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK" custom format string) takes advantage of the three ways that ISO 8601 represents time zone information to preserve the property of values: -- The time zone component of date and time values is an offset from UTC (for example, +01:00, -07:00). All values are also represented in this format. +- The time zone component of date and time values is an offset from UTC (for example, +01:00, -07:00). All values are also represented in this format. -- The time zone component of date and time values uses "Z" (which stands for zero offset) to represent UTC. +- The time zone component of date and time values uses "Z" (which stands for zero offset) to represent UTC. -- date and time values have no time zone information. +- date and time values have no time zone information. Because the O" or "o" standard format specifier conforms to an international standard, the formatting or parsing operation that uses the specifier always uses the invariant culture and the Gregorian calendar. - Strings that are passed to the `Parse`, `TryParse`, `ParseExact`, and `TryParseExact` methods of and can be parsed by using the "O" or "o" format specifier if they are in one of these formats. In the case of objects, the parsing overload that you call should also include a `styles` parameter with a value of . Note that if you call a parsing method with the custom format string that corresponds to the "O" or "o" format specifier, you won't get the same results as "O" or "o". This is because parsing methods that use a custom format string can't parse the string representation of date and time values that lack a time zone component or use "Z" to indicate UTC. + Strings that are passed to the `Parse`, `TryParse`, `ParseExact`, and `TryParseExact` methods of and can be parsed by using the "O" or "o" format specifier if they are in one of these formats. In the case of objects, the parsing overload that you call should also include a `styles` parameter with a value of . Note that if you call a parsing method with the custom format string that corresponds to the "O" or "o" format specifier, you won't get the same results as "O" or "o". This is because parsing methods that use a custom format string can't parse the string representation of date and time values that lack a time zone component or use "Z" to indicate UTC. The following example uses the "o" format specifier to display a series of values and a value on a system in the U.S. Pacific Time zone. @@ -270,9 +270,9 @@ A standard date and time format string uses a single format specifier to define ## The RFC1123 ("R", "r") Format Specifier - The "R" or "r" standard format specifier represents a custom date and time format string that is defined by the property. The pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "ddd, dd MMM yyyy HH':'mm':'ss 'GMT'". When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. + The "R" or "r" standard format specifier represents a custom date and time format string that is defined by the property. The pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "ddd, dd MMM yyyy HH':'mm':'ss 'GMT'". When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. - The result string is affected by the following properties of the object returned by the property that represents the invariant culture. + The result string is affected by the following properties of the object returned by the property that represents the invariant culture. |Property|Description| |--------------|-----------------| @@ -280,7 +280,7 @@ A standard date and time format string uses a single format specifier to define ||Defines the abbreviated day names that can appear in the result string.| ||Defines the abbreviated month names that can appear in the result string.| - Although the RFC 1123 standard expresses a time as Coordinated Universal Time (UTC), the formatting operation does not modify the value of the object that is being formatted. Therefore, you must convert the value to UTC by calling the method before you perform the formatting operation. In contrast, values perform this conversion automatically; there is no need to call the method before the formatting operation. + Although the RFC 1123 standard expresses a time as Coordinated Universal Time (UTC), the formatting operation does not modify the value of the object that is being formatted. Therefore, you must convert the value to UTC by calling the method before you perform the formatting operation. In contrast, values perform this conversion automatically; there is no need to call the method before the formatting operation. The following example uses the "r" format specifier to display a and a value on a system in the U.S. Pacific Time zone. @@ -291,9 +291,9 @@ A standard date and time format string uses a single format specifier to define ## The Sortable ("s") Format Specifier - The "s" standard format specifier represents a custom date and time format string that is defined by the property. The pattern reflects a defined standard (ISO 8601), and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "yyyy'-'MM'-'dd'T'HH':'mm':'ss". + The "s" standard format specifier represents a custom date and time format string that is defined by the property. The pattern reflects a defined standard (ISO 8601), and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "yyyy'-'MM'-'dd'T'HH':'mm':'ss". - The purpose of the "s" format specifier is to produce result strings that sort consistently in ascending or descending order based on date and time values. As a result, although the "s" standard format specifier represents a date and time value in a consistent format, the formatting operation does not modify the value of the date and time object that is being formatted to reflect its property or its value. For example, the result strings produced by formatting the date and time values 2014-11-15T18:32:17+00:00 and 2014-11-15T18:32:17+08:00 are identical. + The purpose of the "s" format specifier is to produce result strings that sort consistently in ascending or descending order based on date and time values. As a result, although the "s" standard format specifier represents a date and time value in a consistent format, the formatting operation does not modify the value of the date and time object that is being formatted to reflect its property or its value. For example, the result strings produced by formatting the date and time values 2014-11-15T18:32:17+00:00 and 2014-11-15T18:32:17+08:00 are identical. When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. @@ -306,9 +306,9 @@ A standard date and time format string uses a single format specifier to define ## The Short Time ("t") Format Specifier - The "t" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "HH:mm". + The "t" standard format specifier represents a custom date and time format string that is defined by the current property. For example, the custom format string for the invariant culture is "HH:mm". - The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. + The result string is affected by the formatting information of a specific object. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| @@ -326,9 +326,9 @@ A standard date and time format string uses a single format specifier to define ## The Long Time ("T") Format Specifier - The "T" standard format specifier represents a custom date and time format string that is defined by a specific culture's property. For example, the custom format string for the invariant culture is "HH:mm:ss". + The "T" standard format specifier represents a custom date and time format string that is defined by a specific culture's property. For example, the custom format string for the invariant culture is "HH:mm:ss". - The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. + The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. |Property|Description| |--------------|-----------------| @@ -346,9 +346,9 @@ A standard date and time format string uses a single format specifier to define ## The Universal Sortable ("u") Format Specifier - The "u" standard format specifier represents a custom date and time format string that is defined by the property. The pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "yyyy'-'MM'-'dd HH':'mm':'ss'Z'". When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. + The "u" standard format specifier represents a custom date and time format string that is defined by the property. The pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture used or the format provider supplied. The custom format string is "yyyy'-'MM'-'dd HH':'mm':'ss'Z'". When this standard format specifier is used, the formatting or parsing operation always uses the invariant culture. - Although the result string should express a time as Coordinated Universal Time (UTC), no conversion of the original value is performed during the formatting operation. Therefore, you must convert a value to UTC by calling the method before formatting it. In contrast, values perform this conversion automatically; there is no need to call the method before the formatting operation. + Although the result string should express a time as Coordinated Universal Time (UTC), no conversion of the original value is performed during the formatting operation. Therefore, you must convert a value to UTC by calling the method before formatting it. In contrast, values perform this conversion automatically; there is no need to call the method before the formatting operation. The following example uses the "u" format specifier to display a date and time value. @@ -359,7 +359,7 @@ A standard date and time format string uses a single format specifier to define ## The Universal Full ("U") Format Specifier - The "U" standard format specifier represents a custom date and time format string that is defined by a specified culture's property. The pattern is the same as the "F" pattern. However, the value is automatically converted to UTC before it is formatted. + The "U" standard format specifier represents a custom date and time format string that is defined by a specified culture's property. The pattern is the same as the "F" pattern. However, the value is automatically converted to UTC before it is formatted. The following table lists the object properties that may control the formatting of the returned string. The custom format specifier that is returned by the property of some cultures may not make use of all properties. @@ -383,7 +383,7 @@ A standard date and time format string uses a single format specifier to define ## The Year Month ("Y", "y") Format Specifier - The "Y" or "y" standard format specifier represents a custom date and time format string that is defined by the property of a specified culture. For example, the custom format string for the invariant culture is "yyyy MMMM". + The "Y" or "y" standard format specifier represents a custom date and time format string that is defined by the property of a specified culture. For example, the custom format string for the invariant culture is "yyyy MMMM". The following table lists the object properties that control the formatting of the returned string. @@ -405,14 +405,14 @@ A standard date and time format string uses a single format specifier to define ### Control Panel Settings The settings in the **Regional and Language Options** item in Control Panel influence the result string produced by a formatting operation. These settings are used to initialize the object associated with the current thread culture, which provides values used to govern formatting. Computers that use different settings generate different result strings. - In addition, if you use the constructor to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructor to create a object that does not reflect a system's customizations. + In addition, if you use the constructor to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructor to create a object that does not reflect a system's customizations. ### DateTimeFormatInfo Properties Formatting is influenced by properties of the current object, which is provided implicitly by the current thread culture or explicitly by the parameter of the method that invokes formatting. For the parameter, your application should specify a object, which represents a culture, or a object, which represents a particular culture's date and time formatting conventions. Many of the standard date and time format specifiers are aliases for formatting patterns defined by properties of the current object. Your application can change the result produced by some standard date and time format specifiers by changing the corresponding date and time format patterns of the corresponding property. ## See Also - - + + [Formatting Types](../../../docs/standard/base-types/formatting-types.md) [Custom Date and Time Format Strings](../../../docs/standard/base-types/custom-date-and-time-format-strings.md) [Sample: .NET Framework 4 Formatting Utility](http://code.msdn.microsoft.com/NET-Framework-4-Formatting-9c4dae8d) diff --git a/docs/standard/base-types/standard-numeric-format-strings.md b/docs/standard/base-types/standard-numeric-format-strings.md index b9073397e9d65..6bdd0ba4897e5 100644 --- a/docs/standard/base-types/standard-numeric-format-strings.md +++ b/docs/standard/base-types/standard-numeric-format-strings.md @@ -29,14 +29,14 @@ Standard numeric format strings are used to format common numeric types. A stand - `A` is a single alphabetic character called the *format specifier*. Any numeric format string that contains more than one alphabetic character, including white space, is interpreted as a custom numeric format string. For more information, see [Custom Numeric Format Strings](../../../docs/standard/base-types/custom-numeric-format-strings.md). -- `xx` is an optional integer called the *precision specifier*. The precision specifier ranges from 0 to 99 and affects the number of digits in the result. Note that the precision specifier controls the number of digits in the string representation of a number. It does not round the number itself. To perform a rounding operation, use the , , or method. +- `xx` is an optional integer called the *precision specifier*. The precision specifier ranges from 0 to 99 and affects the number of digits in the result. Note that the precision specifier controls the number of digits in the string representation of a number. It does not round the number itself. To perform a rounding operation, use the , , or method. - When *precision specifier* controls the number of fractional digits in the result string, the result strings reflect numbers that are rounded away from zero (that is, using ). + When *precision specifier* controls the number of fractional digits in the result string, the result strings reflect numbers that are rounded away from zero (that is, using ). > [!NOTE] > The precision specifier determines the number of digits in the result string. To pad a result string with leading or trailing spaces, use the [composite formatting](../../../docs/standard/base-types/composite-formatting.md) feature and define an *alignment component* in the format item. - Standard numeric format strings are supported by some overloads of the `ToString` method of all numeric types. For example, you can supply a numeric format string to the and methods of the type. Standard numeric format strings are also supported by the .NET [composite formatting feature](../../../docs/standard/base-types/composite-formatting.md), which is used by some `Write` and `WriteLine` methods of the and classes, the method, and the method. The composite format feature allows you to include the string representation of multiple data items in a single string, to specify field width, and to align numbers in a field. For more information, see [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). + Standard numeric format strings are supported by some overloads of the `ToString` method of all numeric types. For example, you can supply a numeric format string to the and methods of the type. Standard numeric format strings are also supported by the .NET [composite formatting feature](../../../docs/standard/base-types/composite-formatting.md), which is used by some `Write` and `WriteLine` methods of the and classes, the method, and the method. The composite format feature allows you to include the string representation of multiple data items in a single string, to specify field width, and to align numbers in a field. For more information, see [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). > [!TIP] > You can download the [Formatting Utility](http://code.msdn.microsoft.com/NET-Framework-4-Formatting-9c4dae8d), an application that enables you to apply format strings to either numeric or date and time values and displays the result string. @@ -45,13 +45,13 @@ Standard numeric format strings are used to format common numeric types. A stand |Format specifier|Name|Description|Examples| |----------------------|----------|-----------------|--------------| -|"C" or "c"|Currency|Result: A currency value.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Currency ("C") Format Specifier](#CFormatString).|123.456 ("C", en-US) -> $123.46

123.456 ("C", fr-FR) -> 123,46 €

123.456 ("C", ja-JP) -> ¥123

-123.456 ("C3", en-US) -> ($123.456)

-123.456 ("C3", fr-FR) -> -123,456 €

-123.456 ("C3", ja-JP) -> -¥123.456| +|"C" or "c"|Currency|Result: A currency value.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Currency ("C") Format Specifier](#CFormatString).|123.456 ("C", en-US) -> $123.46

123.456 ("C", fr-FR) -> 123,46 €

123.456 ("C", ja-JP) -> ¥123

-123.456 ("C3", en-US) -> ($123.456)

-123.456 ("C3", fr-FR) -> -123,456 €

-123.456 ("C3", ja-JP) -> -¥123.456| |"D" or "d"|Decimal|Result: Integer digits with optional negative sign.

Supported by: Integral types only.

Precision specifier: Minimum number of digits.

Default precision specifier: Minimum number of digits required.

More information: [The Decimal("D") Format Specifier](#DFormatString).|1234 ("D") -> 1234

-1234 ("D6") -> -001234| |"E" or "e"|Exponential (scientific)|Result: Exponential notation.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: 6.

More information: [The Exponential ("E") Format Specifier](#EFormatString).|1052.0329112756 ("E", en-US) -> 1.052033E+003

1052.0329112756 ("e", fr-FR) -> 1,052033e+003

-1052.0329112756 ("e2", en-US) -> -1.05e+003

-1052.0329112756 ("E2", fr_FR) -> -1,05E+003| -|"F" or "f"|Fixed-point|Result: Integral and decimal digits with optional negative sign.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Fixed-Point ("F") Format Specifier](#FFormatString).|1234.567 ("F", en-US) -> 1234.57

1234.567 ("F", de-DE) -> 1234,57

1234 ("F1", en-US) -> 1234.0

1234 ("F1", de-DE) -> 1234,0

-1234.56 ("F4", en-US) -> -1234.5600

-1234.56 ("F4", de-DE) -> -1234,5600| +|"F" or "f"|Fixed-point|Result: Integral and decimal digits with optional negative sign.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Fixed-Point ("F") Format Specifier](#FFormatString).|1234.567 ("F", en-US) -> 1234.57

1234.567 ("F", de-DE) -> 1234,57

1234 ("F1", en-US) -> 1234.0

1234 ("F1", de-DE) -> 1234,0

-1234.56 ("F4", en-US) -> -1234.5600

-1234.56 ("F4", de-DE) -> -1234,5600| |"G" or "g"|General|Result: The more compact of either fixed-point or scientific notation.

Supported by: All numeric types.

Precision specifier: Number of significant digits.

Default precision specifier: Depends on numeric type.

More information: [The General ("G") Format Specifier](#GFormatString).|-123.456 ("G", en-US) -> -123.456

-123.456 ("G", sv-SE) -> -123,456

123.4546 ("G4", en-US) -> 123.5

123.4546 ("G4", sv-SE) -> 123,5

-1.234567890e-25 ("G", en-US) -> -1.23456789E-25

-1.234567890e-25 ("G", sv-SE) -> -1,23456789E-25| -|"N" or "n"|Number|Result: Integral and decimal digits, group separators, and a decimal separator with optional negative sign.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Numeric ("N") Format Specifier](#NFormatString).|1234.567 ("N", en-US) -> 1,234.57

1234.567 ("N", ru-RU) -> 1 234,57

1234 ("N1", en-US) -> 1,234.0

1234 ("N1", ru-RU) -> 1 234,0

-1234.56 ("N3", en-US) -> -1,234.560

-1234.56 ("N3", ru-RU) -> -1 234,560| -|"P" or "p"|Percent|Result: Number multiplied by 100 and displayed with a percent symbol.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Percent ("P") Format Specifier](#PFormatString).|1 ("P", en-US) -> 100.00 %

1 ("P", fr-FR) -> 100,00 %

-0.39678 ("P1", en-US) -> -39.7 %

-0.39678 ("P1", fr-FR) -> -39,7 %| +|"N" or "n"|Number|Result: Integral and decimal digits, group separators, and a decimal separator with optional negative sign.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Numeric ("N") Format Specifier](#NFormatString).|1234.567 ("N", en-US) -> 1,234.57

1234.567 ("N", ru-RU) -> 1 234,57

1234 ("N1", en-US) -> 1,234.0

1234 ("N1", ru-RU) -> 1 234,0

-1234.56 ("N3", en-US) -> -1,234.560

-1234.56 ("N3", ru-RU) -> -1 234,560| +|"P" or "p"|Percent|Result: Number multiplied by 100 and displayed with a percent symbol.

Supported by: All numeric types.

Precision specifier: Desired number of decimal places.

Default precision specifier: Defined by .

More information: [The Percent ("P") Format Specifier](#PFormatString).|1 ("P", en-US) -> 100.00 %

1 ("P", fr-FR) -> 100,00 %

-0.39678 ("P1", en-US) -> -39.7 %

-0.39678 ("P1", fr-FR) -> -39,7 %| |"R" or "r"|Round-trip|Result: A string that can round-trip to an identical number.

Supported by: , , and .

Precision specifier: Ignored.

More information: [The Round-trip ("R") Format Specifier](#RFormatString).|123456789.12345678 ("R") -> 123456789.12345678

-1234567890.12345678 ("R") -> -1234567890.1234567| |"X" or "x"|Hexadecimal|Result: A hexadecimal string.

Supported by: Integral types only.

Precision specifier: Number of digits in the result string.

More information: [The HexaDecimal ("X") Format Specifier](#XFormatString).|255 ("X") -> FF

-1 ("x") -> ff

255 ("x4") -> 00ff

-1 ("X4") -> 00FF| |Any other single character|Unknown specifier|Result: Throws a at run time.|| @@ -66,7 +66,7 @@ Standard numeric format strings are used to format common numeric types. A stand [!code-csharp[Formatting.Numeric.Standard#10](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/standardusage1.cs#10)] [!code-vb[Formatting.Numeric.Standard#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Formatting.Numeric.Standard/vb/standardusage1.vb#10)] -- It can be supplied as the `formatString` argument in a format item used with such methods as , , and . For more information, see [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). The following example uses a format item to insert a currency value in a string. +- It can be supplied as the `formatString` argument in a format item used with such methods as , , and . For more information, see [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). The following example uses a format item to insert a currency value in a string. [!code-cpp[Formatting.Numeric.Standard#11](../../../samples/snippets/cpp/VS_Snippets_CLR/Formatting.Numeric.Standard/cpp/standardusage1.cpp#11)] [!code-csharp[Formatting.Numeric.Standard#11](../../../samples/snippets/csharp/VS_Snippets_CLR/Formatting.Numeric.Standard/cs/standardusage1.cs#11)] @@ -82,7 +82,7 @@ Standard numeric format strings are used to format common numeric types. A stand ## The Currency ("C") Format Specifier - The "C" (or currency) format specifier converts a number to a string that represents a currency amount. The precision specifier indicates the desired number of decimal places in the result string. If the precision specifier is omitted, the default precision is defined by the property. + The "C" (or currency) format specifier converts a number to a string that represents a currency amount. The precision specifier indicates the desired number of decimal places in the result string. If the precision specifier is omitted, the default precision is defined by the property. If the value to be formatted has more than the specified or default number of decimal places, the fractional value is rounded in the result string. If the value to the right of the number of specified decimal places is 5 or greater, the last digit in the result string is rounded away from zero. @@ -155,7 +155,7 @@ Standard numeric format strings are used to format common numeric types. A stand ## The Fixed-Point ("F") Format Specifier The fixed-point ("F") format specifier converts a number to a string of the form "-ddd.ddd…" where each "d" indicates a digit (0-9). The string starts with a minus sign if the number is negative. - The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the current property supplies the numeric precision. + The precision specifier indicates the desired number of decimal places. If the precision specifier is omitted, the current property supplies the numeric precision. The result string is affected by the formatting information of the current object. The following table lists the properties of the object that control the formatting of the result string. @@ -213,7 +213,7 @@ Standard numeric format strings are used to format common numeric types. A stand ## The Numeric ("N") Format Specifier - The numeric ("N") format specifier converts a number to a string of the form "-d,ddd,ddd.ddd…", where "-" indicates a negative number symbol if required, "d" indicates a digit (0-9), "," indicates a group separator, and "." indicates a decimal point symbol. The precision specifier indicates the desired number of digits after the decimal point. If the precision specifier is omitted, the number of decimal places is defined by the current property. + The numeric ("N") format specifier converts a number to a string of the form "-d,ddd,ddd.ddd…", where "-" indicates a negative number symbol if required, "d" indicates a digit (0-9), "," indicates a group separator, and "." indicates a decimal point symbol. The precision specifier indicates the desired number of digits after the decimal point. If the precision specifier is omitted, the number of decimal places is defined by the current property. The result string is affected by the formatting information of the current object. The following table lists the properties that control the formatting of the result string. @@ -313,7 +313,7 @@ Standard numeric format strings are used to format common numeric types. A stand ### Control Panel Settings The settings in the **Regional and Language Options** item in Control Panel influence the result string produced by a formatting operation. Those settings are used to initialize the object associated with the current thread culture, which provides values used to govern formatting. Computers that use different settings generate different result strings. - In addition, if the constructor is used to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructor to create a object that does not reflect a system's customizations. + In addition, if the constructor is used to instantiate a new object that represents the same culture as the current system culture, any customizations established by the **Regional and Language Options** item in Control Panel will be applied to the new object. You can use the constructor to create a object that does not reflect a system's customizations. ### NumberFormatInfo Properties Formatting is influenced by the properties of the current object, which is provided implicitly by the current thread culture or explicitly by the parameter of the method that invokes formatting. Specify a or object for that parameter. diff --git a/docs/standard/base-types/standard-timespan-format-strings.md b/docs/standard/base-types/standard-timespan-format-strings.md index 2de123775a93b..563e2e43c2ef0 100644 --- a/docs/standard/base-types/standard-timespan-format-strings.md +++ b/docs/standard/base-types/standard-timespan-format-strings.md @@ -28,12 +28,12 @@ manager: "wpickett" # Standard TimeSpan Format Strings A standard format string uses a single format specifier to define the text representation of a value that results from a formatting operation. Any format string that contains more than one character, including white space, is interpreted as a custom format string. For more information, see [Custom TimeSpan Format Strings](../../../docs/standard/base-types/custom-timespan-format-strings.md) . - The string representations of values are produced by calls to the overloads of the method, as well as by methods that support composite formatting, such as . For more information, see [Formatting Types](../../../docs/standard/base-types/formatting-types.md) and [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). The following example illustrates the use of standard format strings in formatting operations. + The string representations of values are produced by calls to the overloads of the method, as well as by methods that support composite formatting, such as . For more information, see [Formatting Types](../../../docs/standard/base-types/formatting-types.md) and [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md). The following example illustrates the use of standard format strings in formatting operations. [!code-csharp[Conceptual.TimeSpan.Standard#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.standard/cs/formatexample1.cs#2)] [!code-vb[Conceptual.TimeSpan.Standard#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/formatexample1.vb#2)] - Standard format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. + Standard format strings are also used by the and methods to define the required format of input strings for parsing operations. (Parsing converts the string representation of a value to that value.) The following example illustrates the use of standard format strings in parsing operations. [!code-csharp[Conceptual.TimeSpan.Standard#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.timespan.standard/cs/parseexample1.cs#3)] [!code-vb[Conceptual.TimeSpan.Standard#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.timespan.standard/vb/parseexample1.vb#3)] @@ -63,7 +63,7 @@ manager: "wpickett" |*ss*|The number of seconds, which ranges from "0" to "59".| |*fffffff*|The optional fractional portion of a second. Its value can range from "0000001" (one tick, or one ten-millionth of a second) to "9999999" (9,999,999 ten-millionths of a second, or one second less one tick).| - Unlike the "g" and "G" format specifiers, the "c" format specifier is not culture-sensitive. It produces the string representation of a value that is invariant and that is common to all previous versions of the .NET Framework before the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)]. "c" is the default format string; the method formats a time interval value by using the "c" format string. + Unlike the "g" and "G" format specifiers, the "c" format specifier is not culture-sensitive. It produces the string representation of a value that is invariant and that is common to all previous versions of the .NET Framework before the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)]. "c" is the default format string; the method formats a time interval value by using the "c" format string. > [!NOTE] > also supports the "t" and "T" standard format strings, which are identical in behavior to the "c" standard format string. diff --git a/docs/standard/base-types/stringbuilder.md b/docs/standard/base-types/stringbuilder.md index 94f4f5674e6d6..68295cf34636f 100644 --- a/docs/standard/base-types/stringbuilder.md +++ b/docs/standard/base-types/stringbuilder.md @@ -24,7 +24,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Using the StringBuilder Class in .NET -The object is immutable. Every time you use one of the methods in the class, you create a new string object in memory, which requires a new allocation of space for that new object. In situations where you need to perform repeated modifications to a string, the overhead associated with creating a new object can be costly. The class can be used when you want to modify a string without creating a new object. For example, using the class can boost performance when concatenating many strings together in a loop. +The object is immutable. Every time you use one of the methods in the class, you create a new string object in memory, which requires a new allocation of space for that new object. In situations where you need to perform repeated modifications to a string, the overhead associated with creating a new object can be costly. The class can be used when you want to modify a string without creating a new object. For example, using the class can boost performance when concatenating many strings together in a loop. ## Importing the System.Text Namespace The class is found in the namespace. To avoid having to provide a fully qualified type name in your code, you can import the namespace: @@ -62,11 +62,11 @@ The object is immutable. Every time you use one of the meth |Method name|Use| |-----------------|---------| -||Appends information to the end of the current **StringBuilder**.| -||Replaces a format specifier passed in a string with formatted text.| -||Inserts a string or object into the specified index of the current **StringBuilder**.| -||Removes a specified number of characters from the current **StringBuilder**.| -||Replaces a specified character at a specified index.| +||Appends information to the end of the current **StringBuilder**.| +||Replaces a format specifier passed in a string with formatted text.| +||Inserts a string or object into the specified index of the current **StringBuilder**.| +||Removes a specified number of characters from the current **StringBuilder**.| +||Replaces a specified character at a specified index.| ### Append The **Append** method can be used to add text or a string representation of an object to the end of a string represented by the current **StringBuilder**. The following example initializes a **StringBuilder** to "Hello World" and then appends some text to the end of the object. Space is allocated automatically as needed. @@ -76,7 +76,7 @@ The object is immutable. Every time you use one of the meth [!code-vb[Conceptual.StringBuilder#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#4)] ### AppendFormat - The method adds text to the end of the object. It supports the composite formatting feature (for more information, see [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md)) by calling the implementation of the object or objects to be formatted. Therefore, it accepts the standard format strings for numeric, date and time, and enumeration values, the custom format strings for numeric and date and time values, and the format strings defined for custom types. (For information about formatting, see [Formatting Types](../../../docs/standard/base-types/formatting-types.md).) You can use this method to customize the format of variables and append those values to a . The following example uses the method to place an integer value formatted as a currency value at the end of a object. + The method adds text to the end of the object. It supports the composite formatting feature (for more information, see [Composite Formatting](../../../docs/standard/base-types/composite-formatting.md)) by calling the implementation of the object or objects to be formatted. Therefore, it accepts the standard format strings for numeric, date and time, and enumeration values, the custom format strings for numeric and date and time values, and the format strings defined for custom types. (For information about formatting, see [Formatting Types](../../../docs/standard/base-types/formatting-types.md).) You can use this method to customize the format of variables and append those values to a . The following example uses the method to place an integer value formatted as a currency value at the end of a object. [!code-cpp[Conceptual.StringBuilder#5](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#5)] [!code-csharp[Conceptual.StringBuilder#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#5)] @@ -104,12 +104,12 @@ The object is immutable. Every time you use one of the meth [!code-vb[Conceptual.StringBuilder#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#8)] ## Converting a StringBuilder Object to a String - You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You do this conversion by calling the method. The following example calls a number of methods and then calls the method to display the string. + You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You do this conversion by calling the method. The following example calls a number of methods and then calls the method to display the string. [!code-csharp[Conceptual.StringBuilder#10](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/tostringexample1.cs#10)] [!code-vb[Conceptual.StringBuilder#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/tostringexample1.vb#10)] ## See Also - + [Basic String Operations](../../../docs/standard/base-types/basic-string-operations.md) [Formatting Types](../../../docs/standard/base-types/formatting-types.md) diff --git a/docs/standard/base-types/substitutions-in-regular-expressions.md b/docs/standard/base-types/substitutions-in-regular-expressions.md index dce509aceda61..7f0196700b6fc 100644 --- a/docs/standard/base-types/substitutions-in-regular-expressions.md +++ b/docs/standard/base-types/substitutions-in-regular-expressions.md @@ -22,7 +22,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Substitutions in Regular Expressions - Substitutions are language elements that are recognized only within replacement patterns. They use a regular expression pattern to define all or part of the text that is to replace matched text in the input string. The replacement pattern can consist of one or more substitutions along with literal characters. Replacement patterns are provided to overloads of the method that have a `replacement` parameter and to the method. The methods replace the matched pattern with the pattern that is defined by the `replacement` parameter. + Substitutions are language elements that are recognized only within replacement patterns. They use a regular expression pattern to define all or part of the text that is to replace matched text in the input string. The replacement pattern can consist of one or more substitutions along with literal characters. Replacement patterns are provided to overloads of the method that have a `replacement` parameter and to the method. The methods replace the matched pattern with the pattern that is defined by the `replacement` parameter. The .NET Framework defines the substitution elements listed in the following table. @@ -69,7 +69,7 @@ manager: "wpickett" |`\d+`|Match one or more decimal digits.| |`[.,]?`|Match zero or one period or comma.| |`\d*`|Match zero or more decimal digits.| -|`(\s?\d+[.,]?\d*)`|Match a white space followed by one or more decimal digits, followed by zero or one period or comma, followed by zero or more decimal digits. This is the first capturing group. Because the replacement pattern is `$1`, the call to the method replaces the entire matched substring with this captured group.| +|`(\s?\d+[.,]?\d*)`|Match a white space followed by one or more decimal digits, followed by zero or one period or comma, followed by zero or more decimal digits. This is the first capturing group. Because the replacement pattern is `$1`, the call to the method replaces the entire matched substring with this captured group.| [Back to top](#Top) @@ -95,7 +95,7 @@ manager: "wpickett" |`\d+`|Match one or more decimal digits.| |`[.,]?`|Match zero or one period or comma.| |`\d*`|Match zero or more decimal digits.| -|`(?\s?\d[.,]?\d*)`|Match a white space, followed by one or more decimal digits, followed by zero or one period or comma, followed by zero or more decimal digits. This is the capturing group named `amount`. Because the replacement pattern is `${amount}`, the call to the method replaces the entire matched substring with this captured group.| +|`(?\s?\d[.,]?\d*)`|Match a white space, followed by one or more decimal digits, followed by zero or one period or comma, followed by zero or more decimal digits. This is the capturing group named `amount`. Because the replacement pattern is `${amount}`, the call to the method replaces the entire matched substring with this captured group.| [Back to top](#Top) @@ -177,15 +177,15 @@ manager: "wpickett" |2|5|cc3dd4ee5|aabb2cc3dd4ee5bb**cc3dd4ee5**cc3dd4ee5| |3|8|dd4ee5|aabb2cc3dd4ee5bbcc3dd4ee5cc**dd4ee5**dd4ee5| |4|11|ee5|aabb2cc3dd4ee5bbcc3dd4ee5ccdd4ee5dd**ee5**ee5| -|5|14||aabb2cc3dd4ee5bbcc3dd4ee5ccdd4ee5ddee5ee| +|5|14||aabb2cc3dd4ee5bbcc3dd4ee5ccdd4ee5ddee5ee| [Back to top](#Top) ## Substituting the Last Captured Group - The `$+` substitution replaces the matched string with the last captured group. If there are no captured groups or if the value of the last captured group is , the `$+` substitution has no effect. + The `$+` substitution replaces the matched string with the last captured group. If there are no captured groups or if the value of the last captured group is , the `$+` substitution has no effect. - The following example identifies duplicate words in a string and uses the `$+` substitution to replace them with a single occurrence of the word. The option is used to ensure that words that differ in case but that are otherwise identical are considered duplicates. + The following example identifies duplicate words in a string and uses the `$+` substitution to replace them with a single occurrence of the word. The option is used to ensure that words that differ in case but that are otherwise identical are considered duplicates. [!code-csharp[Conceptual.Regex.Language.Substitutions#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regex.language.substitutions/cs/lastmatch1.cs#6)] [!code-vb[Conceptual.Regex.Language.Substitutions#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regex.language.substitutions/vb/lastmatch1.vb#6)] diff --git a/docs/standard/base-types/the-regular-expression-object-model.md b/docs/standard/base-types/the-regular-expression-object-model.md index 011800db1df3a..ca7c733b17f4b 100644 --- a/docs/standard/base-types/the-regular-expression-object-model.md +++ b/docs/standard/base-types/the-regular-expression-object-model.md @@ -83,7 +83,7 @@ manager: "wpickett" These operations are described in the following sections. ### Matching a Regular Expression Pattern - The method returns `true` if the string matches the pattern, or `false` if it does not. The method is often used to validate string input. For example, the following code ensures that a string matches a valid social security number in the United States. + The method returns `true` if the string matches the pattern, or `false` if it does not. The method is often used to validate string input. For example, the following code ensures that a string matches a valid social security number in the United States. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/validate1.cs#1)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/validate1.vb#1)] @@ -101,7 +101,7 @@ manager: "wpickett" |`$`|Match the end of the input string.| ### Extracting a Single Match or the First Match - The method returns a object that contains information about the first substring that matches a regular expression pattern. If the `Match.Success` property returns `true`, indicating that a match was found, you can retrieve information about subsequent matches by calling the method. These method calls can continue until the `Match.Success` property returns `false`. For example, the following code uses the method to find the first occurrence of a duplicated word in a string. It then calls the method to find any additional occurrences. The example examines the `Match.Success` property after each method call to determine whether the current match was successful and whether a call to the method should follow. + The method returns a object that contains information about the first substring that matches a regular expression pattern. If the `Match.Success` property returns `true`, indicating that a match was found, you can retrieve information about subsequent matches by calling the method. These method calls can continue until the `Match.Success` property returns `false`. For example, the following code uses the method to find the first occurrence of a duplicated word in a string. It then calls the method to find any additional occurrences. The example examines the `Match.Success` property after each method call to determine whether the current match was successful and whether a call to the method should follow. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/match1.cs#2)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/match1.vb#2)] @@ -117,13 +117,13 @@ manager: "wpickett" |`\b`|End the match on a word boundary.| ### Extracting All Matches - The method returns a object that contains information about all matches that the regular expression engine found in the input string. For example, the previous example could be rewritten to call the method instead of the and methods. + The method returns a object that contains information about all matches that the regular expression engine found in the input string. For example, the previous example could be rewritten to call the method instead of the and methods. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/matches1.cs#3)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/matches1.vb#3)] ### Replacing a Matched Substring - The method replaces each substring that matches the regular expression pattern with a specified string or regular expression pattern, and returns the entire input string with replacements. For example, the following code adds a U.S. currency symbol before a decimal number in a string. + The method replaces each substring that matches the regular expression pattern with a specified string or regular expression pattern, and returns the entire input string with replacements. For example, the following code adds a U.S. currency symbol before a decimal number in a string. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/replace1.cs#4)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/replace1.vb#4)] @@ -146,7 +146,7 @@ manager: "wpickett" |`$&`|The entire matched substring.| ### Splitting a Single String into an Array of Strings - The method splits the input string at the positions defined by a regular expression match. For example, the following code places the items in a numbered list into a string array. + The method splits the input string at the positions defined by a regular expression match. For example, the following code places the items in a numbered list into a string array. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/split1.cs#5)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/split1.vb#5)] @@ -166,11 +166,11 @@ manager: "wpickett" ### The Match Collection - The method returns a object that contains objects that represent all the matches that the regular expression engine found, in the order in which they occur in the input string. If there are no matches, the method returns a object with no members. The property lets you access individual members of the collection by index, from zero to one less than the value of the property. is the collection's indexer (in C#) and default property (in Visual Basic). + The method returns a object that contains objects that represent all the matches that the regular expression engine found, in the order in which they occur in the input string. If there are no matches, the method returns a object with no members. The property lets you access individual members of the collection by index, from zero to one less than the value of the property. is the collection's indexer (in C#) and default property (in Visual Basic). - By default, the call to the method uses lazy evaluation to populate the object. Access to properties that require a fully populated collection, such as the and properties, may involve a performance penalty. As a result, we recommend that you access the collection by using the object that is returned by the method. Individual languages provide constructs, such as `For``Each` in Visual Basic and `foreach` in C#, that wrap the collection's interface. + By default, the call to the method uses lazy evaluation to populate the object. Access to properties that require a fully populated collection, such as the and properties, may involve a performance penalty. As a result, we recommend that you access the collection by using the object that is returned by the method. Individual languages provide constructs, such as `For``Each` in Visual Basic and `foreach` in C#, that wrap the collection's interface. - The following example uses the method to populate a object with all the matches found in an input string. The example enumerates the collection, copies the matches to a string array, and records the character positions in an integer array. + The following example uses the method to populate a object with all the matches found in an input string. The example enumerates the collection, copies the matches to a string array, and records the character positions in an integer array. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/matchcollection1.cs#6)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/matchcollection1.vb#6)] @@ -179,23 +179,23 @@ manager: "wpickett" ### The Match The class represents the result of a single regular expression match. You can access objects in two ways: -- By retrieving them from the object that is returned by the method. To retrieve individual objects, iterate the collection by using a `foreach` (in C#) or `For Each`...`Next` (in Visual Basic) construct, or use the property to retrieve a specific object either by index or by name. You can also retrieve individual objects from the collection by iterating the collection by index, from zero to one less that the number of objects in the collection. However, this method does not take advantage of lazy evaluation, because it accesses the property. +- By retrieving them from the object that is returned by the method. To retrieve individual objects, iterate the collection by using a `foreach` (in C#) or `For Each`...`Next` (in Visual Basic) construct, or use the property to retrieve a specific object either by index or by name. You can also retrieve individual objects from the collection by iterating the collection by index, from zero to one less that the number of objects in the collection. However, this method does not take advantage of lazy evaluation, because it accesses the property. The following example retrieves individual objects from a object by iterating the collection using the `foreach` or `For Each`...`Next` construct. The regular expression simply matches the string "abc" in the input string. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/match2.cs#7)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/match2.vb#7)] -- By calling the method, which returns a object that represents the first match in a string or a portion of a string. You can determine whether the match has been found by retrieving the value of the `Match.Success` property. To retrieve objects that represent subsequent matches, call the method repeatedly, until the `Success` property of the returned object is `false`. +- By calling the method, which returns a object that represents the first match in a string or a portion of a string. You can determine whether the match has been found by retrieving the value of the `Match.Success` property. To retrieve objects that represent subsequent matches, call the method repeatedly, until the `Success` property of the returned object is `false`. - The following example uses the and methods to match the string "abc" in the input string. + The following example uses the and methods to match the string "abc" in the input string. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/match3.cs#8)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/match3.vb#8)] Two properties of the class return collection objects: -- The property returns a object that contains information about the substrings that match capturing groups in the regular expression pattern. +- The property returns a object that contains information about the substrings that match capturing groups in the regular expression pattern. - The `Match.Captures` property returns a object that is of limited use. The collection is not populated for a object whose `Success` property is `false`. Otherwise, it contains a single object that has the same information as the object. @@ -205,11 +205,11 @@ manager: "wpickett" The class also has two pattern-matching methods: -- The method finds the match after the match represented by the current object, and returns a object that represents that match. +- The method finds the match after the match represented by the current object, and returns a object that represents that match. -- The method performs a specified replacement operation on the matched string and returns the result. +- The method performs a specified replacement operation on the matched string and returns the result. - The following example uses the method to prepend a $ symbol and a space before every number that includes two fractional digits. + The following example uses the method to prepend a $ symbol and a space before every number that includes two fractional digits. [!code-csharp[Conceptual.RegularExpressions.ObjectModel#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/result1.cs#9)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/result1.vb#9)] @@ -231,11 +231,11 @@ manager: "wpickett" ## The Group Collection - The property returns a object that contains objects that represent captured groups in a single match. The first object in the collection (at index 0) represents the entire match. Each object that follows represents the results of a single capturing group. + The property returns a object that contains objects that represent captured groups in a single match. The first object in the collection (at index 0) represents the entire match. Each object that follows represents the results of a single capturing group. - You can retrieve individual objects in the collection by using the property. You can retrieve unnamed groups by their ordinal position in the collection, and retrieve named groups either by name or by ordinal position. Unnamed captures appear first in the collection, and are indexed from left to right in the order in which they appear in the regular expression pattern. Named captures are indexed after unnamed captures, from left to right in the order in which they appear in the regular expression pattern. To determine what numbered groups are available in the collection returned for a particular regular expression matching method, you can call the instance method. To determine what named groups are available in the collection, you can call the instance method. Both methods are particularly useful in general-purpose routines that analyze the matches found by any regular expression. + You can retrieve individual objects in the collection by using the property. You can retrieve unnamed groups by their ordinal position in the collection, and retrieve named groups either by name or by ordinal position. Unnamed captures appear first in the collection, and are indexed from left to right in the order in which they appear in the regular expression pattern. Named captures are indexed after unnamed captures, from left to right in the order in which they appear in the regular expression pattern. To determine what numbered groups are available in the collection returned for a particular regular expression matching method, you can call the instance method. To determine what named groups are available in the collection, you can call the instance method. Both methods are particularly useful in general-purpose routines that analyze the matches found by any regular expression. - The property is the indexer of the collection in C# and the collection object's default property in Visual Basic. This means that individual objects can be accessed by index (or by name, in the case of named groups) as follows: + The property is the indexer of the collection in C# and the collection object's default property in Visual Basic. This means that individual objects can be accessed by index (or by name, in the case of named groups) as follows: [!code-csharp[Conceptual.RegularExpressions.ObjectModel#13](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/groupsyntax1.cs#13)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/groupsyntax1.vb#13)] @@ -262,7 +262,7 @@ manager: "wpickett" ## The Captured Group - The class represents the result from a single capturing group. Group objects that represent the capturing groups defined in a regular expression are returned by the property of the object returned by the property. The property is the indexer (in C#) and the default property (in Visual Basic) of the class. You can also retrieve individual members by iterating the collection using the `foreach` or `For``Each` construct. For an example, see the previous section. + The class represents the result from a single capturing group. Group objects that represent the capturing groups defined in a regular expression are returned by the property of the object returned by the property. The property is the indexer (in C#) and the default property (in Visual Basic) of the class. You can also retrieve individual members by iterating the collection using the `foreach` or `For``Each` construct. For an example, see the previous section. The following example uses nested grouping constructs to capture substrings into groups. The regular expression pattern `(a(b))c` matches the string "abc". It assigns the substring "ab" to the first capturing group, and the substring "b" to the second capturing group. @@ -292,7 +292,7 @@ manager: "wpickett" |Group property|Value| |--------------------|-----------| |`Success`|`false`| - |`Value`|| + |`Value`|| |`Length`|0| The following example provides an illustration. In the regular expression pattern `aaa(bbb)*ccc`, the first capturing group (the substring "bbb") can be matched zero or more times. Because the input string "aaaccc" matches the pattern, the capturing group does not have a match. @@ -309,11 +309,11 @@ manager: "wpickett" ## The Capture Collection - The object contains information only about the last capture. However, the entire set of captures made by a capturing group is still available from the object that is returned by the property. Each member of the collection is a object that represents a capture made by that capturing group, in the order in which they were captured (and, therefore, in the order in which the captured strings were matched from left to right in the input string). You can retrieve individual objects from the collection in either of two ways: + The object contains information only about the last capture. However, the entire set of captures made by a capturing group is still available from the object that is returned by the property. Each member of the collection is a object that represents a capture made by that capturing group, in the order in which they were captured (and, therefore, in the order in which the captured strings were matched from left to right in the input string). You can retrieve individual objects from the collection in either of two ways: - By iterating through the collection using a construct such as `foreach` (in C#) or `For``Each` (in Visual Basic). -- By using the property to retrieve a specific object by index. The property is the object's default property (in Visual Basic) or indexer (in C#). +- By using the property to retrieve a specific object by index. The property is the object's default property (in Visual Basic) or indexer (in C#). If a quantifier is not applied to a capturing group, the object contains a single object that is of little interest, because it provides information about the same match as its object. If a quantifier is applied to a capturing group, the object contains all captures made by the capturing group, and the last member of the collection represents the same capture as the object. @@ -322,7 +322,7 @@ manager: "wpickett" [!code-csharp[Conceptual.RegularExpressions.ObjectModel#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/cs/capturecollection1.cs#14)] [!code-vb[Conceptual.RegularExpressions.ObjectModel#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.regularexpressions.objectmodel/vb/capturecollection1.vb#14)] - The following example uses the regular expression `(Abc)+` to find one or more consecutive runs of the string "Abc" in the string "XYZAbcAbcAbcXYZAbcAb". The example illustrates the use of the property to return multiple groups of captured substrings. + The following example uses the regular expression `(Abc)+` to find one or more consecutive runs of the string "Abc" in the string "XYZAbcAbcAbcXYZAbcAb". The example illustrates the use of the property to return multiple groups of captured substrings. [!code-csharp[RegularExpressions.Classes#5](../../../samples/snippets/csharp/VS_Snippets_CLR/RegularExpressions.Classes/cs/Example.cs#5)] [!code-vb[RegularExpressions.Classes#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/RegularExpressions.Classes/vb/Example.vb#5)] @@ -331,7 +331,7 @@ manager: "wpickett" ## The Individual Capture - The class contains the results from a single subexpression capture. The property contains the matched text, and the property indicates the zero-based position in the input string at which the matched substring begins. + The class contains the results from a single subexpression capture. The property contains the matched text, and the property indicates the zero-based position in the input string at which the matched substring begins. The following example parses an input string for the temperature of selected cities. A comma (",") is used to separate a city and its temperature, and a semicolon (";") is used to separate each city's data. The entire input string represents a single match. In the regular expression pattern `((\w+(\s\w+)*),(\d+);)+`, which is used to parse the string, the city name is assigned to the second capturing group, and the temperature is assigned to the fourth capturing group. diff --git a/docs/standard/base-types/trimming.md b/docs/standard/base-types/trimming.md index 5f7838d59b1ad..771a124960175 100644 --- a/docs/standard/base-types/trimming.md +++ b/docs/standard/base-types/trimming.md @@ -27,13 +27,13 @@ If you are parsing a sentence into individual words, you might end up with words |Method name|Use| |-----------------|---------| -||Removes white spaces or characters specified in an array of characters from the beginning and end of a string.| -||Removes characters specified in an array of characters from the end of a string.| -||Removes characters specified in an array of characters from the beginning of a string.| -||Removes a specified number of characters from a specified index position in a string.| +||Removes white spaces or characters specified in an array of characters from the beginning and end of a string.| +||Removes characters specified in an array of characters from the end of a string.| +||Removes characters specified in an array of characters from the beginning of a string.| +||Removes a specified number of characters from a specified index position in a string.| ## Trim - You can easily remove white spaces from both ends of a string by using the method, as shown in the following example. + You can easily remove white spaces from both ends of a string by using the method, as shown in the following example. [!code-cpp[Conceptual.String.BasicOps#17](../../../samples/snippets/cpp/VS_Snippets_CLR/conceptual.string.basicops/cpp/trimming.cpp#17)] [!code-csharp[Conceptual.String.BasicOps#17](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/trimming.cs#17)] @@ -75,7 +75,7 @@ If you are parsing a sentence into individual words, you might end up with words This code displays `World!` to the console. ## Remove - The method removes a specified number of characters that begin at a specified position in an existing string. This method assumes a zero-based index. + The method removes a specified number of characters that begin at a specified position in an existing string. This method assumes a zero-based index. The following example removes ten characters from a string beginning at position five of a zero-based index of the string. @@ -83,7 +83,7 @@ If you are parsing a sentence into individual words, you might end up with words [!code-csharp[Conceptual.String.BasicOps#21](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/trimming.cs#21)] [!code-vb[Conceptual.String.BasicOps#21](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/trimming.vb#21)] - You can also remove a specified character or substring from a string by calling the method and specifying an empty string () as the replacement. The following example removes all commas from a string. + You can also remove a specified character or substring from a string by calling the method and specifying an empty string () as the replacement. The following example removes all commas from a string. [!code-csharp[Conceptual.String.BasicOps#23](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.string.basicops/cs/replace1.cs#23)] [!code-vb[Conceptual.String.BasicOps#23](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.string.basicops/vb/replace1.vb#23)] diff --git a/docs/standard/base-types/type-conversion.md b/docs/standard/base-types/type-conversion.md index 19fb6070235c2..ea7aaf7492839 100644 --- a/docs/standard/base-types/type-conversion.md +++ b/docs/standard/base-types/type-conversion.md @@ -92,23 +92,23 @@ manager: "wpickett" |Type|Comparison with range of Int32| |----------|------------------------------------| -|| is greater than , and is less than (has a greater negative range than) .| -|| is greater than .| -|| is greater than .| +|| is greater than , and is less than (has a greater negative range than) .| +|| is greater than .| +|| is greater than .| To handle such narrowing conversions, the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] allows types to define an `Explicit` operator. Individual language compilers can then implement this operator using their own syntax, or a member of the class can be called to perform the conversion. (For more information about the class, see [The Convert Class](#Convert) later in this topic.) The following example illustrates the use of language features to handle the explicit conversion of these potentially out-of-range integer values to values. [!code-csharp[Conceptual.Conversion#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/explicit1.cs#4)] [!code-vb[Conceptual.Conversion#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/explicit1.vb#4)] - Explicit conversions can produce different results in different languages, and these results can differ from the value returned by the corresponding method. For example, if the value 12.63251 is converted to an , both the Visual Basic `CInt` method and the .NET Framework method round the to return a value of 13, but the C# `(int)` operator truncates the to return a value of 12. Similarly, the C# `(int)` operator does not support Boolean-to-integer conversion, but the Visual Basic `CInt` method converts a value of `true` to -1. On the other hand, the method converts a value of `true` to 1. + Explicit conversions can produce different results in different languages, and these results can differ from the value returned by the corresponding method. For example, if the value 12.63251 is converted to an , both the Visual Basic `CInt` method and the .NET Framework method round the to return a value of 13, but the C# `(int)` operator truncates the to return a value of 12. Similarly, the C# `(int)` operator does not support Boolean-to-integer conversion, but the Visual Basic `CInt` method converts a value of `true` to -1. On the other hand, the method converts a value of `true` to 1. Most compilers allow explicit conversions to be performed in a checked or unchecked manner. When a checked conversion is performed, an is thrown when the value of the type to be converted is outside the range of the target type. When an unchecked conversion is performed under the same conditions, the conversion might not throw an exception, but the exact behavior becomes undefined and an incorrect value might result. > [!NOTE] > In C#, checked conversions can be performed by using the `checked` keyword together with a casting operator, or by specifying the `/checked+` compiler option. Conversely, unchecked conversions can be performed by using the `unchecked` keyword together with the casting operator, or by specifying the `/checked-` compiler option. By default, explicit conversions are unchecked. In Visual Basic, checked conversions can be performed by clearing the **Remove integer overflow checks** check box in the project's **Advanced Compiler Settings** dialog box, or by specifying the `/removeintchecks-` compiler option. Conversely, unchecked conversions can be performed by selecting the **Remove integer overflow checks** check box in the project's **Advanced Compiler Settings** dialog box or by specifying the `/removeintchecks+` compiler option. By default, explicit conversions are checked. - The following C# example uses the `checked` and `unchecked` keywords to illustrate the difference in behavior when a value outside the range of a is converted to a . The checked conversion throws an exception, but the unchecked conversion assigns to the variable. + The following C# example uses the `checked` and `unchecked` keywords to illustrate the difference in behavior when a value outside the range of a is converted to a . The checked conversion throws an exception, but the unchecked conversion assigns to the variable. [!code-csharp[Conceptual.Conversion#12](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/explicit1.cs#12)] @@ -150,7 +150,7 @@ manager: "wpickett" ## The Convert Class - Although each base type's interface implementation can be called to perform a type conversion, calling the methods of the class is the recommended language-neutral way to convert from one base type to another. In addition, the method can be used to convert from a specified custom type to another type. + Although each base type's interface implementation can be called to perform a type conversion, calling the methods of the class is the recommended language-neutral way to convert from one base type to another. In addition, the method can be used to convert from a specified custom type to another type. ### Conversions Between Base Types The class provides a language-neutral way to perform conversions between base types and is available to all languages that target the common language runtime. It provides a complete set of methods for both widening and narrowing conversions, and throws an for conversions that are not supported (such as the conversion of a value to an integer value). Narrowing conversions are performed in a checked context, and an is thrown if the conversion fails. @@ -158,7 +158,7 @@ manager: "wpickett" > [!IMPORTANT] > Because the class includes methods to convert to and from each base type, it eliminates the need to call each base type's explicit interface implementation. - The following example illustrates the use of the class to perform several widening and narrowing conversions between .NET Framework base types. + The following example illustrates the use of the class to perform several widening and narrowing conversions between .NET Framework base types. [!code-csharp[Conceptual.Conversion#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/convert1.cs#8)] [!code-vb[Conceptual.Conversion#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/convert1.vb#8)] @@ -172,12 +172,12 @@ manager: "wpickett" ### Custom Conversions with the ChangeType Method - In addition to supporting conversions to each of the base types, the class can be used to convert a custom type to one or more predefined types. This conversion is performed by the method, which in turn wraps a call to the method of the `value` parameter. This means that the object represented by the `value` parameter must provide an implementation of the interface. + In addition to supporting conversions to each of the base types, the class can be used to convert a custom type to one or more predefined types. This conversion is performed by the method, which in turn wraps a call to the method of the `value` parameter. This means that the object represented by the `value` parameter must provide an implementation of the interface. > [!NOTE] -> Because the and methods use a object to specify the target type to which `value` is converted, they can be used to perform a dynamic conversion to an object whose type is not known at compile time. However, note that the implementation of `value` must still support this conversion. +> Because the and methods use a object to specify the target type to which `value` is converted, they can be used to perform a dynamic conversion to an object whose type is not known at compile time. However, note that the implementation of `value` must still support this conversion. - The following example illustrates a possible implementation of the interface that allows a `TemperatureCelsius` object to be converted to a `TemperatureFahrenheit` object and vice versa. The example defines a base class, `Temperature`, that implements the interface and overrides the method. The derived `TemperatureCelsius` and `TemperatureFahrenheit` classes each override the `ToType` and the `ToString` methods of the base class. + The following example illustrates a possible implementation of the interface that allows a `TemperatureCelsius` object to be converted to a `TemperatureFahrenheit` object and vice versa. The example defines a base class, `Temperature`, that implements the interface and overrides the method. The derived `TemperatureCelsius` and `TemperatureFahrenheit` classes each override the `ToType` and the `ToString` methods of the base class. [!code-csharp[Conceptual.Conversion#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.conversion/cs/iconvertible2.cs#10)] [!code-vb[Conceptual.Conversion#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.conversion/vb/iconvertible2.vb#10)] @@ -191,7 +191,7 @@ manager: "wpickett" ## The TypeConverter Class - The .NET Framework also allows you to define a type converter for a custom type by extending the class and associating the type converter with the type through a attribute. The following table highlights the differences between this approach and implementing the interface for a custom type. + The .NET Framework also allows you to define a type converter for a custom type by extending the class and associating the type converter with the type through a attribute. The following table highlights the differences between this approach and implementing the interface for a custom type. > [!NOTE] > Design-time support can be provided for a custom type only if it has a type converter defined for it. @@ -203,9 +203,9 @@ manager: "wpickett" |Uses reflection; therefore, is slower than conversion enabled by .|Does not use reflection.| |Allows two-way type conversions from the custom type to other data types, and from other data types to the custom type. For example, a defined for `MyType` allows conversions from `MyType` to , and from to `MyType`.|Allows conversion from a custom type to other data types, but not from other data types to the custom type.| - For more information about using type converters to perform conversions, see . + For more information about using type converters to perform conversions, see . ## See Also - + [Type Conversion Tables](../../../docs/standard/base-types/conversion-tables.md) diff --git a/docs/standard/building-console-apps.md b/docs/standard/building-console-apps.md index 3db7140c589ba..fe3ce31a8362f 100644 --- a/docs/standard/building-console-apps.md +++ b/docs/standard/building-console-apps.md @@ -19,9 +19,9 @@ ms.author: "ronpet" manager: "wpickett" --- # Building Console Applications in the .NET Framework -Applications in the .NET Framework can use the class to read characters from and write characters to the console. Data from the console is read from the standard input stream, data to the console is written to the standard output stream, and error data to the console is written to the standard error output stream. These streams are automatically associated with the console when the application starts and are presented as the , , and properties, respectively. +Applications in the .NET Framework can use the class to read characters from and write characters to the console. Data from the console is read from the standard input stream, data to the console is written to the standard output stream, and error data to the console is written to the standard error output stream. These streams are automatically associated with the console when the application starts and are presented as the , , and properties, respectively. - The value of the property is a object, whereas the values of the and properties are objects. You can associate these properties with streams that do not represent the console, making it possible for you to point the stream to a different location for input or output. For example, you can redirect the output to a file by setting the property to a , which encapsulates a by means of the method. The and properties do not need to refer to the same stream. + The value of the property is a object, whereas the values of the and properties are objects. You can associate these properties with streams that do not represent the console, making it possible for you to point the stream to a different location for input or output. For example, you can redirect the output to a file by setting the property to a , which encapsulates a by means of the method. The and properties do not need to refer to the same stream. > [!NOTE] > For more information about building console applications, including examples in C#, Visual Basic, and C++, see the documentation for the class. @@ -35,5 +35,5 @@ Applications in the .NET Framework can use the + [Formatting Types](../../docs/standard/base-types/formatting-types.md) diff --git a/docs/standard/collections/commonly-used-collection-types.md b/docs/standard/collections/commonly-used-collection-types.md index b3ea423f5673e..dbcfadcf9265b 100644 --- a/docs/standard/collections/commonly-used-collection-types.md +++ b/docs/standard/collections/commonly-used-collection-types.md @@ -44,18 +44,18 @@ Collection types are the common variations of data collections, such as hash tab |[Generics](../../../docs/standard/generics/index.md)|Describes the generics feature, including the generic collections, delegates, and interfaces provided by the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)]. Provides links to feature documentation for C#, Visual Basic, and Visual C++, and to supporting technologies such as reflection.| ## Reference - + - + - + - + - + - + - + - + diff --git a/docs/standard/collections/comparisons-and-sorts-within-collections.md b/docs/standard/collections/comparisons-and-sorts-within-collections.md index f8f7590d27845..22c05dc71a611 100644 --- a/docs/standard/collections/comparisons-and-sorts-within-collections.md +++ b/docs/standard/collections/comparisons-and-sorts-within-collections.md @@ -31,9 +31,9 @@ The classes perform comparisons in almost all the proc - If type T implements the generic interface, then the equality comparer is the method of that interface. -- If type T does not implement , is used. +- If type T does not implement , is used. - In addition, Some constructor overloads for dictionary collections accept an implementation, which is used to compare keys for equality. For an example, see the constructor. + In addition, Some constructor overloads for dictionary collections accept an implementation, which is used to compare keys for equality. For an example, see the constructor. ## Determining sort order @@ -41,13 +41,13 @@ The classes perform comparisons in almost all the proc The default comparer relies on at least one of the objects being compared to implement the **IComparable** interface. It is a good practice to implement **IComparable** on all classes are used as values in a list collection or as keys in a dictionary collection. For a generic collection, equality comparison is determined according to the following: -- If type T implements the generic interface, then the default comparer is the method of that interface +- If type T implements the generic interface, then the default comparer is the method of that interface -- If type T implements the non-generic interface, then the default comparer is the method of that interface. +- If type T implements the non-generic interface, then the default comparer is the method of that interface. - If type T doesn’t implement either interface, then there is no default comparer, and a comparer or comparison delegate must be provided explicitly. - To provide explicit comparisons, some methods accept an **IComparer** implementation as a parameter. For example, the method accepts an implementation. + To provide explicit comparisons, some methods accept an **IComparer** implementation as a parameter. For example, the method accepts an implementation. The current culture setting of the system can affect the comparisons and sorts within a collection. By default, the comparisons and sorts in the **Collections** classes are culture-sensitive. To ignore the culture setting and therefore obtain consistent comparison and sorting results, use the with member overloads that accept a . For more information, see [Performing Culture-Insensitive String Operations in Collections](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-collections.md) and [Performing Culture-Insensitive String Operations in Arrays](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-arrays.md). diff --git a/docs/standard/collections/hashtable-and-dictionary-collection-types.md b/docs/standard/collections/hashtable-and-dictionary-collection-types.md index 97dcbab142d49..71db48081b3dd 100644 --- a/docs/standard/collections/hashtable-and-dictionary-collection-types.md +++ b/docs/standard/collections/hashtable-and-dictionary-collection-types.md @@ -22,7 +22,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Hashtable and Dictionary Collection Types -The class, and the and generic classes, implement the interface. The generic class also implements the generic interface. Therefore, each element in these collections is a key-and-value pair. +The class, and the and generic classes, implement the interface. The generic class also implements the generic interface. Therefore, each element in these collections is a key-and-value pair. A object consists of buckets that contain the elements of the collection. A bucket is a virtual subgroup of elements within the , which makes searching and retrieving easier and faster than in most collections. Each bucket is associated with a hash code, which is generated using a hash function and is based on the key of the element. @@ -43,6 +43,6 @@ The class, and the - - + + [Commonly Used Collection Types](../../../docs/standard/collections/commonly-used-collection-types.md) diff --git a/docs/standard/collections/index.md b/docs/standard/collections/index.md index d864861425ea7..2551f7d30f056 100644 --- a/docs/standard/collections/index.md +++ b/docs/standard/collections/index.md @@ -18,7 +18,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Collections and Data Structures -Similar data can often be handled more efficiently when stored and manipulated as a collection. You can use the class or the classes in the , , , System.Collections.Immutable namespaces to add, remove, and modify either individual elements or a range of elements in a collection. +Similar data can often be handled more efficiently when stored and manipulated as a collection. You can use the class or the classes in the , , , System.Collections.Immutable namespaces to add, remove, and modify either individual elements or a range of elements in a collection. There are two main types of collections; generic collections and non-generic collections. Generic collections were added in the .NET Framework 2.0 and provide collections that are type-safe at compile time. Because of this, generic collections typically offer better performance. Generic collections accept a type parameter when they are constructed and do not require that you cast to and from the type when you add or remove items from the collection. In addition, most generic collections are supported in [!INCLUDE[win8_appstore_long](../../../includes/win8-appstore-long-md.md)] apps. Non-generic collections store items as , require casting, and most are not supported for [!INCLUDE[win8_appstore_long](../../../includes/win8-appstore-long-md.md)] app development. However, you may see non-generic collections in older code. @@ -31,7 +31,7 @@ Similar data can often be handled more efficiently when stored and manipulated a - **The ability to enumerate the collection** - .NET Framework collections either implement or to enable the collection to be iterated through. An enumerator can be thought of as a movable pointer to any element in the collection. The [foreach, in](~/docs/csharp/language-reference/keywords/foreach-in.md) statement and the [For Each...Next Statement](~/docs/visual-basic/language-reference/statements/for-each-next-statement.md) use the enumerator exposed by the method and hide the complexity of manipulating the enumerator. In addition, any collection that implements is considered a *queryable type* and can be queried with LINQ. LINQ queries provide a common pattern for accessing data. They are typically more concise and readable than standard `foreach` loops, and provide filtering, ordering and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects](http://msdn.microsoft.com/library/73cafe73-37cf-46e7-bfa7-97c7eea7ced9), [Parallel LINQ (PLINQ)](../../../docs/standard/parallel-programming/parallel-linq-plinq.md) and [Introduction to LINQ Queries (C#)](~/docs/csharp/programming-guide/concepts/linq/introduction-to-linq-queries.md). + .NET Framework collections either implement or to enable the collection to be iterated through. An enumerator can be thought of as a movable pointer to any element in the collection. The [foreach, in](~/docs/csharp/language-reference/keywords/foreach-in.md) statement and the [For Each...Next Statement](~/docs/visual-basic/language-reference/statements/for-each-next-statement.md) use the enumerator exposed by the method and hide the complexity of manipulating the enumerator. In addition, any collection that implements is considered a *queryable type* and can be queried with LINQ. LINQ queries provide a common pattern for accessing data. They are typically more concise and readable than standard `foreach` loops, and provide filtering, ordering and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects](http://msdn.microsoft.com/library/73cafe73-37cf-46e7-bfa7-97c7eea7ced9), [Parallel LINQ (PLINQ)](../../../docs/standard/parallel-programming/parallel-linq-plinq.md) and [Introduction to LINQ Queries (C#)](~/docs/csharp/programming-guide/concepts/linq/introduction-to-linq-queries.md). - **The ability to copy the collection contents to an array** @@ -49,7 +49,7 @@ Similar data can often be handled more efficiently when stored and manipulated a - **A consistent lower bound** - The lower bound of a collection is the index of its first element. All indexed collections in the namespaces have a lower bound of zero, meaning they are 0-indexed. has a lower bound of zero by default, but a different lower bound can be defined when creating an instance of the **Array** class using . + The lower bound of a collection is the index of its first element. All indexed collections in the namespaces have a lower bound of zero, meaning they are 0-indexed. has a lower bound of zero by default, but a different lower bound can be defined when creating an instance of the **Array** class using . - **Synchronization for access from multiple threads** ( classes only). @@ -61,14 +61,14 @@ Similar data can often be handled more efficiently when stored and manipulated a |I want to…|Generic collection option(s)|Non-generic collection option(s)|Thread-safe or immutable collection option(s)| |-|-|-|-| -|Store items as key/value pairs for quick look-up by key||

(A collection of key/value pairs that are organize based on the hash code of the key.)|



`ImmutableDictionary(TKey, TValue) Class`| -|Access items by index||

|`ImmutableList(T) Class`

`ImmutableArray Class`| -|Use items first-in-first-out (FIFO)|||

`ImmutableQueue(T) Class`| -|Use data Last-In-First-Out (LIFO)|||

`ImmutableStack(T) Class`| -|Access items sequentially||No recommendation|No recommendation| -|Receive notifications when items are removed or added to the collection. (implements and )||No recommendation|No recommendation| -|A sorted collection|||`ImmutableSortedDictionary(TKey, TValue) Class`

`ImmutableSortedSet(T) Class`| -|A set for mathematical functions|

|No recommendation|`ImmutableHashSet(T) Class`

`ImmutableSortedSet(T) Class`| +|Store items as key/value pairs for quick look-up by key||

(A collection of key/value pairs that are organize based on the hash code of the key.)|



`ImmutableDictionary(TKey, TValue) Class`| +|Access items by index||

|`ImmutableList(T) Class`

`ImmutableArray Class`| +|Use items first-in-first-out (FIFO)|||

`ImmutableQueue(T) Class`| +|Use data Last-In-First-Out (LIFO)|||

`ImmutableStack(T) Class`| +|Access items sequentially||No recommendation|No recommendation| +|Receive notifications when items are removed or added to the collection. (implements and )||No recommendation|No recommendation| +|A sorted collection|||`ImmutableSortedDictionary(TKey, TValue) Class`

`ImmutableSortedSet(T) Class`| +|A set for mathematical functions|

|No recommendation|`ImmutableHashSet(T) Class`

`ImmutableSortedSet(T) Class`| ## Related Topics @@ -76,20 +76,20 @@ Similar data can often be handled more efficiently when stored and manipulated a |Title|Description| |-----------|-----------------| |[Selecting a Collection Class](../../../docs/standard/collections/selecting-a-collection-class.md)|Describes the different collections and helps you select one for your scenario.| -|[Commonly Used Collection Types](../../../docs/standard/collections/commonly-used-collection-types.md)|Describes commonly used generic and nongeneric collection types such as , , and .| +|[Commonly Used Collection Types](../../../docs/standard/collections/commonly-used-collection-types.md)|Describes commonly used generic and nongeneric collection types such as , , and .| |[When to Use Generic Collections](../../../docs/standard/collections/when-to-use-generic-collections.md)|Discusses the use of generic collection types.| |[Comparisons and Sorts Within Collections](../../../docs/standard/collections/comparisons-and-sorts-within-collections.md)|Discusses the use of equality comparisons and sorting comparisons in collections.| |[Sorted Collection Types](../../../docs/standard/collections/sorted-collection-types.md)|Describes sorted collections performance and characteristics| |[Hashtable and Dictionary Collection Types](../../../docs/standard/collections/hashtable-and-dictionary-collection-types.md)|Describes the features of generic and non-generic hash-based dictionary types.| -|[Thread-Safe Collections](../../../docs/standard/collections/thread-safe/index.md)|Describes collection types such as and that support safe and efficient concurrent access from multiple threads.| +|[Thread-Safe Collections](../../../docs/standard/collections/thread-safe/index.md)|Describes collection types such as and that support safe and efficient concurrent access from multiple threads.| |System.Collections.Immutable|Introduces the immutable collections and provides links to the collection types.| ## Reference - - - - - - + + + + + + diff --git a/docs/standard/collections/sorted-collection-types.md b/docs/standard/collections/sorted-collection-types.md index 574f5a884d264..f1f4eb1d269ad 100644 --- a/docs/standard/collections/sorted-collection-types.md +++ b/docs/standard/collections/sorted-collection-types.md @@ -21,16 +21,16 @@ ms.author: "mairaw" manager: "wpickett" --- # Sorted Collection Types -The class, the generic class, and the generic class are similar to the class and the generic class in that they implement the interface, but they maintain their elements in sort order by key, and they do not have the O(1) insertion and retrieval characteristic of hash tables. The three classes have several features in common: +The class, the generic class, and the generic class are similar to the class and the generic class in that they implement the interface, but they maintain their elements in sort order by key, and they do not have the O(1) insertion and retrieval characteristic of hash tables. The three classes have several features in common: -- All three classes implement the interface. The two generic classes also implement the generic interface. +- All three classes implement the interface. The two generic classes also implement the generic interface. - Each element is a key/value pair for enumeration purposes. > [!NOTE] > The nongeneric class returns objects when enumerated, although the two generic types return objects. -- Elements are sorted according to a implementation (for nongeneric ) or a implementation (for the two generic classes). +- Elements are sorted according to a implementation (for nongeneric ) or a implementation (for the two generic classes). - Each class provides properties that return collections containing only the keys or only the values. @@ -51,7 +51,7 @@ The class, the class provides a self-balancing tree that maintains data in sorted order after insertions, deletions, and searches. This class and the class implement the interface. ## See Also - - + + [Commonly Used Collection Types](../../../docs/standard/collections/commonly-used-collection-types.md) diff --git a/docs/standard/collections/thread-safe/blockingcollection-overview.md b/docs/standard/collections/thread-safe/blockingcollection-overview.md index a8090b0e21859..10ded19f88b6f 100644 --- a/docs/standard/collections/thread-safe/blockingcollection-overview.md +++ b/docs/standard/collections/thread-safe/blockingcollection-overview.md @@ -80,6 +80,6 @@ BlockingCollection bc = new BlockingCollection(new ConcurrentBag For scenarios in which a consumer needs to take items from multiple collections simultaneously, you can create arrays of and use the static methods such as and that will add to or take from any of the collections in the array. If one collection is blocking, the method immediately tries another until it finds one that can perform the operation. For more information, see [How to: Use Arrays of Blocking Collections in a Pipeline](../../../../docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md). ## See Also - + [Collections and Data Structures](../../../../docs/standard/collections/index.md) [Thread-Safe Collections](../../../../docs/standard/collections/thread-safe/index.md) diff --git a/docs/standard/collections/thread-safe/how-to-add-and-remove-items.md b/docs/standard/collections/thread-safe/how-to-add-and-remove-items.md index fede3ee31449f..fcc66fab23a09 100644 --- a/docs/standard/collections/thread-safe/how-to-add-and-remove-items.md +++ b/docs/standard/collections/thread-safe/how-to-add-and-remove-items.md @@ -17,7 +17,7 @@ ms.author: "mairaw" manager: "wpickett" --- # How to: Add and Remove Items from a ConcurrentDictionary -This example shows how to add, retrieve, update, and remove items from a . This collection class is a thread-safe implementation. We recommend that you use it whenever multiple threads might be attempting to access the elements concurrently. +This example shows how to add, retrieve, update, and remove items from a . This collection class is a thread-safe implementation. We recommend that you use it whenever multiple threads might be attempting to access the elements concurrently. provides several convenience methods that make it unnecessary for code to first check whether a key exists before it attempts to add or remove data. The following table lists these convenience methods and describes when to use them. @@ -48,5 +48,5 @@ This example shows how to add, retrieve, update, and remove items from a is the same data that was created by the thread's valueFactory. A similar sequence of events can occur when is called. ## See Also - + [Thread-Safe Collections](../../../../docs/standard/collections/thread-safe/index.md) diff --git a/docs/standard/collections/thread-safe/how-to-add-and-take-items.md b/docs/standard/collections/thread-safe/how-to-add-and-take-items.md index 96647409fea3d..e63711caec38a 100644 --- a/docs/standard/collections/thread-safe/how-to-add-and-take-items.md +++ b/docs/standard/collections/thread-safe/how-to-add-and-take-items.md @@ -34,5 +34,5 @@ This example shows how to add and remove items from a + [BlockingCollection Overview](../../../../docs/standard/collections/thread-safe/blockingcollection-overview.md) diff --git a/docs/standard/collections/thread-safe/how-to-add-bounding-and-blocking.md b/docs/standard/collections/thread-safe/how-to-add-bounding-and-blocking.md index 347b6c953b04d..09d938f524f0e 100644 --- a/docs/standard/collections/thread-safe/how-to-add-bounding-and-blocking.md +++ b/docs/standard/collections/thread-safe/how-to-add-bounding-and-blocking.md @@ -17,10 +17,10 @@ ms.author: "mairaw" manager: "wpickett" --- # How to: Add Bounding and Blocking Functionality to a Collection -This example shows how to add bounding and blocking functionality to a custom collection class by implementing the interface in the class, and then using a class instance as the internal storage mechanism for a . For more information about bounding and blocking, see [BlockingCollection Overview](../../../../docs/standard/collections/thread-safe/blockingcollection-overview.md). +This example shows how to add bounding and blocking functionality to a custom collection class by implementing the interface in the class, and then using a class instance as the internal storage mechanism for a . For more information about bounding and blocking, see [BlockingCollection Overview](../../../../docs/standard/collections/thread-safe/blockingcollection-overview.md). ## Example - The custom collection class is a basic priority queue in which the priority levels are represented as an array of objects. No additional ordering is performed within each queue. + The custom collection class is a basic priority queue in which the priority levels are represented as an array of objects. No additional ordering is performed within each queue. In the client code, three tasks are started. The first task just polls for keyboard strokes to enable cancellation at any point during execution. The second task is the producer thread; it adds new items to the blocking collection and gives each item a priority based on a random value. The third task removes items from the collection as they become available. @@ -28,7 +28,7 @@ This example shows how to add bounding and blocking functionality to a custom co [!code-csharp[CDS_BlockingCollection#06](../../../../samples/snippets/csharp/VS_Snippets_Misc/cds_blockingcollection/cs/prodcon.cs#06)] - By default, the storage for a is . + By default, the storage for a is . ## See Also [Thread-Safe Collections](../../../../docs/standard/collections/thread-safe/index.md) diff --git a/docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md b/docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md index 348655bb8b387..fd5c3b1e828d7 100644 --- a/docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md +++ b/docs/standard/collections/thread-safe/how-to-use-arrays-of-blockingcollections.md @@ -17,7 +17,7 @@ ms.author: "mairaw" manager: "wpickett" --- # How to: Use Arrays of Blocking Collections in a Pipeline -The following example shows how to use arrays of objects with static methods such as and to implement fast and flexible data transfer between components. +The following example shows how to use arrays of objects with static methods such as and to implement fast and flexible data transfer between components. ## Example The following example demonstrates a basic pipeline implementation in which each object is concurrently taking data from the input collection, transforming it, and passing it to the output collection. @@ -26,5 +26,5 @@ The following example shows how to use arrays of + [Thread-Safe Collections](../../../../docs/standard/collections/thread-safe/index.md) diff --git a/docs/standard/collections/thread-safe/how-to-use-foreach-to-remove.md b/docs/standard/collections/thread-safe/how-to-use-foreach-to-remove.md index cb12147059dfb..85194acf69181 100644 --- a/docs/standard/collections/thread-safe/how-to-use-foreach-to-remove.md +++ b/docs/standard/collections/thread-safe/how-to-use-foreach-to-remove.md @@ -25,12 +25,12 @@ In addition to taking items from a method in the consuming thread, which causes each item to be removed from the collection as it is enumerated. limits the maximum number of items that are in the collection at any time. Enumerating the collection in this way blocks the consumer thread if no items are available or if the collection is empty. In this example blocking is not a concern because the producer thread adds items faster than they can be consumed. + This example uses a `foreach` loop with the method in the consuming thread, which causes each item to be removed from the collection as it is enumerated. limits the maximum number of items that are in the collection at any time. Enumerating the collection in this way blocks the consumer thread if no items are available or if the collection is empty. In this example blocking is not a concern because the producer thread adds items faster than they can be consumed. There is no guarantee that the items are enumerated in the same order in which they are added by the producer threads. To enumerate the collection without modifying it, just use `foreach` (`For Each`) without the method. However, it is important to understand that this kind of enumeration represents a snapshot of the collection at a precise point in time. If other threads are adding or removing items concurrently while you are executing the loop, then the loop might not represent the actual state of the collection. ## See Also - + [Parallel Programming](../../../../docs/standard/parallel-programming/index.md) diff --git a/docs/standard/collections/thread-safe/index.md b/docs/standard/collections/thread-safe/index.md index 2959e44a5fd23..08fde679fad61 100644 --- a/docs/standard/collections/thread-safe/index.md +++ b/docs/standard/collections/thread-safe/index.md @@ -17,12 +17,12 @@ ms.author: "mairaw" manager: "wpickett" --- # Thread-Safe Collections -The [!INCLUDE[net_v40_short](../../../../includes/net-v40-short-md.md)] introduces the namespace, which includes several collection classes that are both thread-safe and scalable. Multiple threads can safely and efficiently add or remove items from these collections, without requiring additional synchronization in user code. When you write new code, use the concurrent collection classes whenever the collection will be writing to multiple threads concurrently. If you are only reading from a shared collection, then you can use the classes in the namespace. We recommend that you do not use 1.0 collection classes unless you are required to target the .NET Framework 1.1 or earlier runtime. +The [!INCLUDE[net_v40_short](../../../../includes/net-v40-short-md.md)] introduces the namespace, which includes several collection classes that are both thread-safe and scalable. Multiple threads can safely and efficiently add or remove items from these collections, without requiring additional synchronization in user code. When you write new code, use the concurrent collection classes whenever the collection will be writing to multiple threads concurrently. If you are only reading from a shared collection, then you can use the classes in the namespace. We recommend that you do not use 1.0 collection classes unless you are required to target the .NET Framework 1.1 or earlier runtime. ## Thread Synchronization in the .NET Framework 1.0 and 2.0 Collections - The collections introduced in the .NET Framework 1.0 are found in the namespace. These collections, which include the commonly used and , provide some thread-safety through the `Synchronized` property, which returns a thread-safe wrapper around the collection. The wrapper works by locking the entire collection on every add or remove operation. Therefore, each thread that is attempting to access the collection must wait for its turn to take the one lock. This is not scalable and can cause significant performance degradation for large collections. Also, the design is not completely protected from race conditions. For more information, see [Synchronization in Generic Collections](http://go.microsoft.com/fwlink/?LinkID=161130) on the MSDN Web site. + The collections introduced in the .NET Framework 1.0 are found in the namespace. These collections, which include the commonly used and , provide some thread-safety through the `Synchronized` property, which returns a thread-safe wrapper around the collection. The wrapper works by locking the entire collection on every add or remove operation. Therefore, each thread that is attempting to access the collection must wait for its turn to take the one lock. This is not scalable and can cause significant performance degradation for large collections. Also, the design is not completely protected from race conditions. For more information, see [Synchronization in Generic Collections](http://go.microsoft.com/fwlink/?LinkID=161130) on the MSDN Web site. - The collection classes introduced in the .NET Framework 2.0 are found in the namespace. These include , , and so on. These classes provide improved type safety and performance compared to the .NET Framework 1.0 classes. However, the .NET Framework 2.0 collection classes do not provide any thread synchronization; user code must provide all synchronization when items are added or removed on multiple threads concurrently. + The collection classes introduced in the .NET Framework 2.0 are found in the namespace. These include , , and so on. These classes provide improved type safety and performance compared to the .NET Framework 1.0 classes. However, the .NET Framework 2.0 collection classes do not provide any thread synchronization; user code must provide all synchronization when items are added or removed on multiple threads concurrently. We recommend the concurrent collections classes in the [!INCLUDE[net_v40_short](../../../../includes/net-v40-short-md.md)] because they provide not only the type safety of the .NET Framework 2.0 collection classes, but also more efficient and more complete thread safety than the [!INCLUDE[net_v10_short](../../../../includes/net-v10-short-md.md)] collections provide. @@ -34,7 +34,7 @@ The [!INCLUDE[net_v40_short](../../../../includes/net-v40-short-md.md)] introduc > [!NOTE] > Because the concurrent collections classes support , they provide implementations for the and properties, even though these properties are irrelevant. `IsSynchronized` always returns `false` and `SyncRoot` is always `null` (`Nothing` in Visual Basic). - The following table lists the collection types in the namespace. + The following table lists the collection types in the namespace. |Type|Description| |----------|-----------------| @@ -58,4 +58,4 @@ The [!INCLUDE[net_v40_short](../../../../includes/net-v40-short-md.md)] introduc |[How to: Create an Object Pool by Using a ConcurrentBag](../../../../docs/standard/collections/thread-safe/how-to-create-an-object-pool.md)|Shows how to use a concurrent bag to improve performance in scenarios where you can reuse objects instead of continually creating new ones.| ## Reference - + diff --git a/docs/standard/collections/thread-safe/when-to-use-a-thread-safe-collection.md b/docs/standard/collections/thread-safe/when-to-use-a-thread-safe-collection.md index c9d023d4768eb..9e9527bcfe768 100644 --- a/docs/standard/collections/thread-safe/when-to-use-a-thread-safe-collection.md +++ b/docs/standard/collections/thread-safe/when-to-use-a-thread-safe-collection.md @@ -36,35 +36,35 @@ The [!INCLUDE[net_v40_long](../../../../includes/net-v40-long-md.md)] introduces The increase in performance that is proportional to the number of cores on the computer. An algorithm that scales performs faster on eight cores than it does on two cores. ## ConcurrentQueue(T) vs. Queue(T) - In pure producer-consumer scenarios, where the processing time for each element is very small (a few instructions), then can offer modest performance benefits over a that has an external lock. In this scenario, performs best when one dedicated thread is queuing and one dedicated thread is de-queuing. If you do not enforce this rule, then might even perform slightly faster than on computers that have multiple cores. + In pure producer-consumer scenarios, where the processing time for each element is very small (a few instructions), then can offer modest performance benefits over a that has an external lock. In this scenario, performs best when one dedicated thread is queuing and one dedicated thread is de-queuing. If you do not enforce this rule, then might even perform slightly faster than on computers that have multiple cores. When processing time is around 500 FLOPS (floating point operations) or more, then the two-thread rule does not apply to , which then has very good scalability. does not scale well in this scenario. In mixed producer-consumer scenarios, when the processing time is very small, a that has an external lock scales better than does. However, when processing time is around 500 FLOPS or more, then the scales better. ## ConcurrentStack vs. Stack - In pure producer-consumer scenarios, when processing time is very small, then and that has an external lock will probably perform about the same with one dedicated pushing thread and one dedicated popping thread. However, as the number of threads increases, both types slow down because of increased contention, and might perform better than . When processing time is around 500 FLOPS or more, then both types scale at about the same rate. + In pure producer-consumer scenarios, when processing time is very small, then and that has an external lock will probably perform about the same with one dedicated pushing thread and one dedicated popping thread. However, as the number of threads increases, both types slow down because of increased contention, and might perform better than . When processing time is around 500 FLOPS or more, then both types scale at about the same rate. In mixed producer-consumer scenarios, is faster for both small and large workloads. The use of the and may greatly speed up access times. ## ConcurrentDictionary vs. Dictionary - In general, use a in any scenario where you are adding and updating keys or values concurrently from multiple threads. In scenarios that involve frequent updates and relatively few reads, the generally offers modest benefits. In scenarios that involve many reads and many updates, the generally is significantly faster on computers that have any number of cores. + In general, use a in any scenario where you are adding and updating keys or values concurrently from multiple threads. In scenarios that involve frequent updates and relatively few reads, the generally offers modest benefits. In scenarios that involve many reads and many updates, the generally is significantly faster on computers that have any number of cores. In scenarios that involve frequent updates, you can increase the degree of concurrency in the and then measure to see whether performance increases on computers that have more cores. If you change the concurrency level, avoid global operations as much as possible. If you are only reading key or values, the is faster because no synchronization is required if the dictionary is not being modified by any threads. ## ConcurrentBag - In pure producer-consumer scenarios, will probably perform more slowly than the other concurrent collection types. + In pure producer-consumer scenarios, will probably perform more slowly than the other concurrent collection types. In mixed producer-consumer scenarios, is generally much faster and more scalable than any other concurrent collection type for both large and small workloads. ## BlockingCollection - When bounding and blocking semantics are required, will probably perform faster than any custom implementation. It also supports rich cancellation, enumeration, and exception handling. + When bounding and blocking semantics are required, will probably perform faster than any custom implementation. It also supports rich cancellation, enumeration, and exception handling. ## See Also - + [Thread-Safe Collections](../../../../docs/standard/collections/thread-safe/index.md) [Parallel Programming](../../../../docs/standard/parallel-programming/index.md) diff --git a/docs/standard/collections/when-to-use-generic-collections.md b/docs/standard/collections/when-to-use-generic-collections.md index 394975880f2dd..6ca1b6fe30fcf 100644 --- a/docs/standard/collections/when-to-use-generic-collections.md +++ b/docs/standard/collections/when-to-use-generic-collections.md @@ -48,7 +48,7 @@ Using generic collections is generally recommended, because you gain the immedia - provides fast insertion and removal of unordered elements. ## LINQ to Objects - The LINQ to Objects feature enables you to use LINQ queries to access in-memory objects as long as the object type implements the or interface. LINQ queries provide a common pattern for accessing data; are typically more concise and readable than standard `foreach` loops; and provide filtering, ordering and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects](http://msdn.microsoft.com/library/73cafe73-37cf-46e7-bfa7-97c7eea7ced9) and [Parallel LINQ (PLINQ)](../../../docs/standard/parallel-programming/parallel-linq-plinq.md). + The LINQ to Objects feature enables you to use LINQ queries to access in-memory objects as long as the object type implements the or interface. LINQ queries provide a common pattern for accessing data; are typically more concise and readable than standard `foreach` loops; and provide filtering, ordering and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects](http://msdn.microsoft.com/library/73cafe73-37cf-46e7-bfa7-97c7eea7ced9) and [Parallel LINQ (PLINQ)](../../../docs/standard/parallel-programming/parallel-linq-plinq.md). ## Additional Functionality Some of the generic types have functionality that is not found in the nongeneric collection types. For example, the class, which corresponds to the nongeneric class, has a number of methods that accept generic delegates, such as the delegate that allows you to specify methods for searching the list, the delegate that represents methods that act on each element of the list, and the delegate that lets you define conversions between types. diff --git a/docs/standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md b/docs/standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md index a9e2a373a6592..54d1a148fe24c 100644 --- a/docs/standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md +++ b/docs/standard/cross-platform/app-resources-for-libraries-that-target-multiple-platforms.md @@ -44,7 +44,7 @@ You can use the .NET Framework [Portable Class Library](../../../docs/standard/c ||Retrieves a named resource for the current culture.| ||Retrieves a named resource belonging to the specified culture.| - The exclusion of other members from the [!INCLUDE[net_portable](../../../includes/net-portable-md.md)] means that serialized objects, non-string data, and images cannot be retrieved from a resource file. To use resources from a [!INCLUDE[net_portable](../../../includes/net-portable-md.md)], you should store all object data in string form. For example, you can store numeric values in a resource file by converting them to strings, and you can retrieve them and then convert them back to numbers by using the numeric data type's `Parse` or `TryParse` method. You can convert images or other binary data to a string representation by calling the method, and restore them to a byte array by calling the method. + The exclusion of other members from the [!INCLUDE[net_portable](../../../includes/net-portable-md.md)] means that serialized objects, non-string data, and images cannot be retrieved from a resource file. To use resources from a [!INCLUDE[net_portable](../../../includes/net-portable-md.md)], you should store all object data in string form. For example, you can store numeric values in a resource file by converting them to strings, and you can retrieve them and then convert them back to numbers by using the numeric data type's `Parse` or `TryParse` method. You can convert images or other binary data to a string representation by calling the method, and restore them to a byte array by calling the method. ## The [!INCLUDE[net_portable](../../../includes/net-portable-md.md)] and Windows Store Apps [!INCLUDE[net_portable](../../../includes/net-portable-md.md)] projects store resources in .resx files, which are then compiled into .resources files and embedded in the main assembly or in satellite assemblies at compile time. [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps, on the other hand, require resources to be stored in .resw files, which are then compiled into a single package resource index (PRI) file. However, despite the incompatible file formats, your [!INCLUDE[net_portable](../../../includes/net-portable-md.md)] will work in a [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] app. diff --git a/docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md b/docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md index f2a70c6dace39..9ea7709042cc9 100644 --- a/docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md +++ b/docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md @@ -23,12 +23,12 @@ ms.author: "mairaw" manager: "wpickett" --- # Passing a URI to the Windows Runtime -Windows Runtime methods accept only absolute URIs. If you pass a relative URI to a [!INCLUDE[wrt](../../../includes/wrt-md.md)] method, an exception is thrown. Here's why: When you use the [!INCLUDE[wrt](../../../includes/wrt-md.md)] in .NET Framework code, the [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376) class appears as in Intellisense. The class allows relative URIs, but the [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376) class does not. This is also true for methods you expose in [!INCLUDE[wrt](../../../includes/wrt-md.md)] Components. If your component exposes a method that takes a URI, the signature in your code includes . However, to users of your component, the signature includes [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376). A URI that is passed to your component must be an absolute URI. +Windows Runtime methods accept only absolute URIs. If you pass a relative URI to a [!INCLUDE[wrt](../../../includes/wrt-md.md)] method, an exception is thrown. Here's why: When you use the [!INCLUDE[wrt](../../../includes/wrt-md.md)] in .NET Framework code, the [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376) class appears as in Intellisense. The class allows relative URIs, but the [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376) class does not. This is also true for methods you expose in [!INCLUDE[wrt](../../../includes/wrt-md.md)] Components. If your component exposes a method that takes a URI, the signature in your code includes . However, to users of your component, the signature includes [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376). A URI that is passed to your component must be an absolute URI. This topic shows how to detect an absolute URI and how to create one when referring to a resource in the app package. ## Detecting and using an absolute URI - Use the property to ensure that a URI is absolute before passing it to the [!INCLUDE[wrt](../../../includes/wrt-md.md)]. Using this property is more efficient than catching and handling the exception. + Use the property to ensure that a URI is absolute before passing it to the [!INCLUDE[wrt](../../../includes/wrt-md.md)]. Using this property is more efficient than catching and handling the exception. ## Using an absolute URI for a resource in the app package If you want to specify a URI for a resource that your app package contains, you can use the `ms-appx` or `ms-appx-web` scheme to create an absolute URI. diff --git a/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md b/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md index 7b62442784f33..b3ba74ec5d417 100644 --- a/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md +++ b/docs/standard/cross-platform/support-for-windows-store-apps-and-windows-runtime.md @@ -63,11 +63,11 @@ The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] supports a number of so - Topics such as the [IIterable interface](http://go.microsoft.com/fwlink/p/?LinkId=238321) don't have declaration syntax for Visual Basic or C#. Instead, a note appears above the syntax section (in this case, ".NET: This interface appears as System.Collections.Generic.IEnumerable\"). This is because the .NET Framework and the [!INCLUDE[wrt](../../../includes/wrt-md.md)] provide similar functionality with different interfaces. In addition, there are behavioral differences: `IIterable` has a `First` method instead of a method to return the enumerator. Instead of forcing you to learn a different way of performing a common task, the .NET Framework supports the [!INCLUDE[wrt](../../../includes/wrt-md.md)] by making your managed code appear to use the type you're familiar with. You won't see the `IIterable` interface in the IDE, and therefore the only way you'll encounter it in the [!INCLUDE[wrt](../../../includes/wrt-md.md)] reference documentation is by browsing through that documentation directly. -- The [SyndicationFeed constructor](http://go.microsoft.com/fwlink/p/?LinkId=238322) documentation illustrates a closely related issue: Its parameter types appear to be different for different languages. For C# and Visual Basic, the parameter types are and . Again, this is because the .NET Framework has its own `String` and `Uri` types, and for such commonly used types it doesn't make sense to force .NET Framework users to learn a different way of doing things. In the IDE, the .NET Framework hides the corresponding [!INCLUDE[wrt](../../../includes/wrt-md.md)] types. +- The [SyndicationFeed constructor](http://go.microsoft.com/fwlink/p/?LinkId=238322) documentation illustrates a closely related issue: Its parameter types appear to be different for different languages. For C# and Visual Basic, the parameter types are and . Again, this is because the .NET Framework has its own `String` and `Uri` types, and for such commonly used types it doesn't make sense to force .NET Framework users to learn a different way of doing things. In the IDE, the .NET Framework hides the corresponding [!INCLUDE[wrt](../../../includes/wrt-md.md)] types. - In a few cases, such as the [Windows.UI.Xaml.GridLength](http://go.microsoft.com/fwlink/p/?LinkId=251059) structure, the .NET Framework provides a type with the same name but more functionality. For example, a set of constructor and property topics are associated with `GridLength`, but they have syntax blocks only for Visual Basic and C# because the members are available only in managed code. In the [!INCLUDE[wrt](../../../includes/wrt-md.md)], structures have only fields. The [!INCLUDE[wrt](../../../includes/wrt-md.md)] structure requires a helper class, [Windows.UI.Xaml.GridLengthHelper](http://go.microsoft.com/fwlink/p/?LinkId=251060), to provide equivalent functionality. You won't see that helper class in the IDE when you're writing managed code. -- In the IDE, [!INCLUDE[wrt](../../../includes/wrt-md.md)] types appear to derive from . They appear to have members inherited from , such as . These members operate as they would if the types actually inherited from , and [!INCLUDE[wrt](../../../includes/wrt-md.md)] types can be cast to . This functionality is part of the support that the .NET Framework provides for the [!INCLUDE[wrt](../../../includes/wrt-md.md)]. However, if you view the types in the [!INCLUDE[wrt](../../../includes/wrt-md.md)] reference documentation, no such members appear. The documentation for these apparent inherited members is provided by the reference documentation. +- In the IDE, [!INCLUDE[wrt](../../../includes/wrt-md.md)] types appear to derive from . They appear to have members inherited from , such as . These members operate as they would if the types actually inherited from , and [!INCLUDE[wrt](../../../includes/wrt-md.md)] types can be cast to . This functionality is part of the support that the .NET Framework provides for the [!INCLUDE[wrt](../../../includes/wrt-md.md)]. However, if you view the types in the [!INCLUDE[wrt](../../../includes/wrt-md.md)] reference documentation, no such members appear. The documentation for these apparent inherited members is provided by the reference documentation. ### Differences That Are Visible in the IDE @@ -108,10 +108,10 @@ The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] supports a number of so As with interface types, the only time you might see evidence of this representation is when your .NET Framework project is a [!INCLUDE[wrt](../../../includes/wrt-md.md)] component that is used by a [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] app built using JavaScript. - Other basic, commonly used [!INCLUDE[wrt](../../../includes/wrt-md.md)] types that appear in managed code as their .NET Framework equivalents include the `Windows.Foundation.DateTime` structure, which appears in managed code as the structure, and the `Windows.Foundation.TimeSpan` structure, which appears as the structure. + Other basic, commonly used [!INCLUDE[wrt](../../../includes/wrt-md.md)] types that appear in managed code as their .NET Framework equivalents include the `Windows.Foundation.DateTime` structure, which appears in managed code as the structure, and the `Windows.Foundation.TimeSpan` structure, which appears as the structure. ### Other Differences - In a few cases, the fact that .NET Framework types appear in your code instead of [!INCLUDE[wrt](../../../includes/wrt-md.md)] types requires action on your part. For example, the [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376) class appears as in .NET Framework code. allows a relative URI, but [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376) requires an absolute URI. Therefore, when you pass a URI to a [!INCLUDE[wrt](../../../includes/wrt-md.md)] method, you must ensure that it's absolute. (See [Passing a URI to the Windows Runtime](../../../docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md).) + In a few cases, the fact that .NET Framework types appear in your code instead of [!INCLUDE[wrt](../../../includes/wrt-md.md)] types requires action on your part. For example, the [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376) class appears as in .NET Framework code. allows a relative URI, but [Windows.Foundation.Uri](http://go.microsoft.com/fwlink/p/?LinkId=238376) requires an absolute URI. Therefore, when you pass a URI to a [!INCLUDE[wrt](../../../includes/wrt-md.md)] method, you must ensure that it's absolute. (See [Passing a URI to the Windows Runtime](../../../docs/standard/cross-platform/passing-a-uri-to-the-windows-runtime.md).) ## Scenarios for Developing Windows Runtime Components diff --git a/docs/standard/cross-platform/using-portable-class-library-with-model-view-view-model.md b/docs/standard/cross-platform/using-portable-class-library-with-model-view-view-model.md index ffbea4b40f109..186a6e7542c13 100644 --- a/docs/standard/cross-platform/using-portable-class-library-with-model-view-view-model.md +++ b/docs/standard/cross-platform/using-portable-class-library-with-model-view-view-model.md @@ -34,27 +34,27 @@ You can use the .NET Framework [Portable Class Library](../../../docs/standard/c ## Classes That Support MVVM When you target the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], [!INCLUDE[net_win8_profile](../../../includes/net-win8-profile-md.md)], Silverlight, or Windows Phone 7.5 for your [!INCLUDE[net_portable](../../../includes/net-portable-md.md)] project, the following classes are available for implementing the MVVM pattern: -- class +- class -- class +- class -- class +- class -- class +- class -- class +- class -- class +- class -- class +- class -- class +- class -- class +- class -- class +- class -- All classes in the namespace +- All classes in the namespace ## Implementing MVVM To implement MVVM, you typically create both the model and the view model in a [!INCLUDE[net_portable](../../../includes/net-portable-md.md)] project, because a [!INCLUDE[net_portable](../../../includes/net-portable-md.md)] project cannot reference a non-portable project. The model and view model can be in the same project or in separate projects. If you use separate projects, add a reference from the view model project to the model project. diff --git a/docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md b/docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md index e437d970b6f2d..f82f0e1c7f59a 100644 --- a/docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md +++ b/docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md @@ -28,7 +28,7 @@ manager: "wpickett" Converts the specified stream to a random access stream. - **Namespace:** + **Namespace:** **Assembly:** System.Runtime.WindowsRuntime (in System.Runtime.WindowsRuntime.dll) ## Syntax @@ -49,7 +49,7 @@ Public Shared Function AsRandomAccessStream ( _ #### Parameters `stream` - Type: + Type: The stream to convert. ## Return Value @@ -63,7 +63,7 @@ A [!INCLUDE[wrt](../../../includes/wrt-md.md)] random access stream, which repre ||The stream to convert does not support seeking.| ## Remarks - This extension method is available only when you develop Windows Store apps. This method provides a convenient way of working with streams in Windows Store apps. The .NET Framework stream you want to convert must support seeking. For more information, see the method. + This extension method is available only when you develop Windows Store apps. This method provides a convenient way of working with streams in Windows Store apps. The .NET Framework stream you want to convert must support seeking. For more information, see the method. > [!IMPORTANT] > This API is supported in the .NET Framework 4.5.1 and later versions, but not in version 4.5. diff --git a/docs/standard/data/xml/accessing-attributes-in-the-dom.md b/docs/standard/data/xml/accessing-attributes-in-the-dom.md index d42e56b38b4d3..6c0648287d87a 100644 --- a/docs/standard/data/xml/accessing-attributes-in-the-dom.md +++ b/docs/standard/data/xml/accessing-attributes-in-the-dom.md @@ -195,7 +195,7 @@ public class Sample ``` ## Retrieving an Individual Attribute Node - To retrieve a single attribute node from an element, the method is used. It returns an object of type **XmlAttribute**. Once you have an **XmlAttribute**, all the methods and properties available in the class are available on that object, such as finding the **OwnerElement**. + To retrieve a single attribute node from an element, the method is used. It returns an object of type **XmlAttribute**. Once you have an **XmlAttribute**, all the methods and properties available in the class are available on that object, such as finding the **OwnerElement**. ```vb Imports System diff --git a/docs/standard/data/xml/building-xml-schemas.md b/docs/standard/data/xml/building-xml-schemas.md index 599cedca36a99..8a8a430bcd828 100644 --- a/docs/standard/data/xml/building-xml-schemas.md +++ b/docs/standard/data/xml/building-xml-schemas.md @@ -20,7 +20,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Building XML Schemas -The classes in the namespace map to the structures defined in the World Wide Web Consortium (W3C) XML Schema Recommendation and can be used to build XML schemas in-memory. +The classes in the namespace map to the structures defined in the World Wide Web Consortium (W3C) XML Schema Recommendation and can be used to build XML schemas in-memory. ## Building an XML Schema In the code examples that follow, the SOM API is used to build a customer XML schema in-memory. @@ -40,7 +40,7 @@ The classes in the namespace m > [!NOTE] > To create unnamed simple or complex types that are anonymous children of an element or attribute (only simple types apply for attributes), set the property of the or classes to the unnamed simple or complex type, instead of the property of the or classes. - XML schemas allow both anonymous and named simple types to be derived by restriction from other simple types (built-in or user-defined) or constructed as a list or union of other simple types. The class is used to create a simple type by restricting the built-in `xs:string` type. You can also use the or classes to create list or union types. The property denotes whether it is a simple type restriction, list, or union. + XML schemas allow both anonymous and named simple types to be derived by restriction from other simple types (built-in or user-defined) or constructed as a list or union of other simple types. The class is used to create a simple type by restricting the built-in `xs:string` type. You can also use the or classes to create list or union types. The property denotes whether it is a simple type restriction, list, or union. In the following code example, the `FirstName` element's type is the built-in type `xs:string`, the `LastName` element's type is a named simple type that is a restriction of the built-in type `xs:string`, with a `MaxLength` facet value of 20, and the `CustomerId` attribute's type is the built-in type `xs:positiveInteger`. The `Customer` element is an anonymous complex type whose particle is the sequence of the `FirstName` and `LastName` elements and whose attributes contains the `CustomerId` attribute. @@ -52,13 +52,13 @@ The classes in the namespace m [!code-vb[XmlSchemaCreateExample#3](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaCreateExample/VB/XmlSchemaCreateExample.vb#3)] ### Creating and Compiling Schemas - At this point, the child elements and attributes, their corresponding types, and the top-level `Customer` element have been created in-memory using the SOM API. In the following code example, the schema element is created using the class, the top-level elements and types are added to it using the property and the complete schema is compiled using the class and written to the console. + At this point, the child elements and attributes, their corresponding types, and the top-level `Customer` element have been created in-memory using the SOM API. In the following code example, the schema element is created using the class, the top-level elements and types are added to it using the property and the complete schema is compiled using the class and written to the console. [!code-cpp[XmlSchemaCreateExample#4](../../../../samples/snippets/cpp/VS_Snippets_Data/XmlSchemaCreateExample/CPP/XmlSchemaCreateExample.cpp#4)] [!code-csharp[XmlSchemaCreateExample#4](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaCreateExample/CS/XmlSchemaCreateExample.cs#4)] [!code-vb[XmlSchemaCreateExample#4](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaCreateExample/VB/XmlSchemaCreateExample.vb#4)] - The method validates the customer schema against the rules for an XML schema and makes post-schema-compilation properties available. + The method validates the customer schema against the rules for an XML schema and makes post-schema-compilation properties available. > [!NOTE] > All post-schema-compilation properties in the SOM API differ from the Post-Schema-Validation-Infoset. diff --git a/docs/standard/data/xml/compiled-xpath-expressions.md b/docs/standard/data/xml/compiled-xpath-expressions.md index fb15d6d76da01..a984f7202dfb2 100644 --- a/docs/standard/data/xml/compiled-xpath-expressions.md +++ b/docs/standard/data/xml/compiled-xpath-expressions.md @@ -29,9 +29,9 @@ An object represents a compiled XPath qu Once compiled, the object may be used as input to the following class methods depending on the type returned from the XPath query. -- +- -- +- - diff --git a/docs/standard/data/xml/editing-xml-schemas.md b/docs/standard/data/xml/editing-xml-schemas.md index fcb92fdcdb8df..98cd64dbce0ef 100644 --- a/docs/standard/data/xml/editing-xml-schemas.md +++ b/docs/standard/data/xml/editing-xml-schemas.md @@ -25,7 +25,7 @@ Editing an XML schema is one of the most important features of the Schema Object The first step in editing a schema loaded into the SOM is to traverse the schema. You should be familiar with traversing a schema using the SOM API before you attempt to edit a schema. You should also be familiar with the pre- and post-schema-compilation properties of the Post-Schema-Compilation-Infoset (PSCI). ## Editing an XML Schema - In this section, two code examples are provided, both of which edit the customer schema created in the [Building XML Schemas](../../../../docs/standard/data/xml/building-xml-schemas.md) topic. The first code example adds a new `PhoneNumber` element to the `Customer` element and the second code example adds a new `Title` attribute to the `FirstName` element. The first sample also uses the post-schema-compilation collection as the means of traversing the customer schema while the second code example uses the pre-schema-compilation collection. + In this section, two code examples are provided, both of which edit the customer schema created in the [Building XML Schemas](../../../../docs/standard/data/xml/building-xml-schemas.md) topic. The first code example adds a new `PhoneNumber` element to the `Customer` element and the second code example adds a new `Title` attribute to the `FirstName` element. The first sample also uses the post-schema-compilation collection as the means of traversing the customer schema while the second code example uses the pre-schema-compilation collection. ### PhoneNumber Element Example This first code example adds a new `PhoneNumber` element to the `Customer` element of the customer schema. The code example edits the customer schema in the following steps. @@ -36,7 +36,7 @@ Editing an XML schema is one of the most important features of the Schema Object 3. Creates the `PhoneNumber` element using the class, the `xs:string` simple type restriction using the and classes, adds a pattern facet to the property of the restriction, and adds the restriction to the property of the simple type and the simple type to the of the `PhoneNumber` element. -4. Iterates over each in the collection of the post-schema-compilation collection. +4. Iterates over each in the collection of the post-schema-compilation collection. 5. If the of the element is `"Customer"`, gets the complex type of the `Customer` element using the class and the sequence particle of the complex type using the class. @@ -91,18 +91,18 @@ Editing an XML schema is one of the most important features of the Schema Object 6. Sets the content model of the simple content to the simple content extension and the content model of the complex type to the simple content. -7. Adds the new complex type to the pre-schema-compilation collection. +7. Adds the new complex type to the pre-schema-compilation collection. -8. Iterates over each in the pre-schema-compilation collection. +8. Iterates over each in the pre-schema-compilation collection. > [!NOTE] -> Because the `FirstName` element is not a global element in the schema, it is not available in the or collections. The code example locates the `FirstName` element by first locating the `Customer` element. +> Because the `FirstName` element is not a global element in the schema, it is not available in the or collections. The code example locates the `FirstName` element by first locating the `Customer` element. > -> The first code example traversed the schema using the post-schema-compilation collection. In this sample, the pre-schema-compilation collection is used to traverse the schema. While both collections provide access to the global elements in the schema, iterating through the collection is more time consuming because you must iterate over all global elements in the schema and it does not have any PSCI properties. The PSCI collections (, , , and so on) provide direct access to their global elements, attributes, and types and their PSCI properties. +> The first code example traversed the schema using the post-schema-compilation collection. In this sample, the pre-schema-compilation collection is used to traverse the schema. While both collections provide access to the global elements in the schema, iterating through the collection is more time consuming because you must iterate over all global elements in the schema and it does not have any PSCI properties. The PSCI collections (, , , and so on) provide direct access to their global elements, attributes, and types and their PSCI properties. 1. If the is an element, whose is `"Customer"`, gets the complex type of the `Customer` element using the class and the sequence particle of the complex type using the class. -2. Iterates over each in the pre-schema-compilation collection. +2. Iterates over each in the pre-schema-compilation collection. 3. If the is an element, who's is `"FirstName"`, sets the of the `FirstName` element to the new `FirstName` complex type. diff --git a/docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md b/docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md index 2bede503b5075..4c2573f45c7fa 100644 --- a/docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md +++ b/docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md @@ -20,7 +20,7 @@ ms.author: "mairaw" manager: "wpickett" --- # How to: Perform an XSLT Transformation by Using an Assembly -The XSLT compiler (xsltc.exe) compiles XSLT style sheets and generates an assembly. The assembly can be passed directly into the method. +The XSLT compiler (xsltc.exe) compiles XSLT style sheets and generates an assembly. The assembly can be passed directly into the method. ### To copy the XML and XSLT files to your local computer diff --git a/docs/standard/data/xml/including-or-importing-xml-schemas.md b/docs/standard/data/xml/including-or-importing-xml-schemas.md index 5ceaf740f9197..37f0e4fba0e12 100644 --- a/docs/standard/data/xml/including-or-importing-xml-schemas.md +++ b/docs/standard/data/xml/including-or-importing-xml-schemas.md @@ -101,7 +101,7 @@ An XML schema may contain ``, ``, and ` ``` - For more information about the ``, ``, and `` elements and the , and classes, see the [W3C XML Schema](http://go.microsoft.com/fwlink/?LinkId=45242) and the namespace class reference documentation. + For more information about the ``, ``, and `` elements and the , and classes, see the [W3C XML Schema](http://go.microsoft.com/fwlink/?LinkId=45242) and the namespace class reference documentation. ## See Also [XML Schema Object Model Overview](../../../../docs/standard/data/xml/xml-schema-object-model-overview.md) diff --git a/docs/standard/data/xml/index.md b/docs/standard/data/xml/index.md index 52186efb03940..bb4fb3779235d 100644 --- a/docs/standard/data/xml/index.md +++ b/docs/standard/data/xml/index.md @@ -36,13 +36,13 @@ The .NET Framework provides a comprehensive and integrated set of classes that e The classes in these namespaces support World Wide Web Consortium (W3C) recommendations. For example: -- The class implements the [W3C Document Object Model (DOM) Level 1 Core](http://www.w3.org/TR/REC-DOM-Level-1/) and [DOM Level 2 Core](http://www.w3.org/TR/DOM-Level-2-Core/) recommendations. +- The class implements the [W3C Document Object Model (DOM) Level 1 Core](http://www.w3.org/TR/REC-DOM-Level-1/) and [DOM Level 2 Core](http://www.w3.org/TR/DOM-Level-2-Core/) recommendations. -- The and classes support the [W3C XML 1.0](http://www.w3.org/TR/2006/REC-xml-20060816/) and the [Namespaces in XML](http://www.w3.org/TR/REC-xml-names/) recommendations. +- The and classes support the [W3C XML 1.0](http://www.w3.org/TR/2006/REC-xml-20060816/) and the [Namespaces in XML](http://www.w3.org/TR/REC-xml-names/) recommendations. -- Schemas in the class support the [W3C XML Schema Part 1: Structures](http://www.w3.org/TR/xmlschema-1/) and [XML Schema Part 2: Datatypes](http://www.w3.org/TR/xmlschema-2/) recommendations. +- Schemas in the class support the [W3C XML Schema Part 1: Structures](http://www.w3.org/TR/xmlschema-1/) and [XML Schema Part 2: Datatypes](http://www.w3.org/TR/xmlschema-2/) recommendations. -- Classes in the namespace support XSLT transformations that conform to the [W3C XSLT 1.0](http://www.w3.org/TR/xslt) recommendation. +- Classes in the namespace support XSLT transformations that conform to the [W3C XSLT 1.0](http://www.w3.org/TR/xslt) recommendation. The XML classes in the .NET Framework provide these benefits: diff --git a/docs/standard/data/xml/inferring-an-xml-schema.md b/docs/standard/data/xml/inferring-an-xml-schema.md index 4c5a7f35c98f6..2778a8d2a2c26 100644 --- a/docs/standard/data/xml/inferring-an-xml-schema.md +++ b/docs/standard/data/xml/inferring-an-xml-schema.md @@ -22,7 +22,7 @@ manager: "wpickett" # Inferring an XML Schema Describes how to use the Schema Object Model (SOM) class to infer an XML Schema definition language (XSD) schema from the structure of an XML document. - The Schema Object Model (SOM) class in the namespace allows you to infer an XML Schema definition language (XSD) schema from the structure of an XML document. The class outputs an XML schema that can validate the XML document. + The Schema Object Model (SOM) class in the namespace allows you to infer an XML Schema definition language (XSD) schema from the structure of an XML document. The class outputs an XML schema that can validate the XML document. ## In This Section [Inferring Schemas from XML Documents](../../../../docs/standard/data/xml/inferring-schemas-from-xml-documents.md) diff --git a/docs/standard/data/xml/inferring-schemas-from-xml-documents.md b/docs/standard/data/xml/inferring-schemas-from-xml-documents.md index d71edeef5ccfd..bd6c12c8626d1 100644 --- a/docs/standard/data/xml/inferring-schemas-from-xml-documents.md +++ b/docs/standard/data/xml/inferring-schemas-from-xml-documents.md @@ -23,7 +23,7 @@ manager: "wpickett" This topic describes how to use the class to infer an XML Schema definition language (XSD) schema from the structure of an XML document. ## The Schema Inference Process - The class of the namespace is used to generate one or more XML Schema definition language (XSD) schemas from the structure of an XML document. The generated schemas may be used to validate the original XML document. + The class of the namespace is used to generate one or more XML Schema definition language (XSD) schemas from the structure of an XML document. The generated schemas may be used to validate the original XML document. As an XML document is processed by the class, the class makes assumptions about the schema components that describe the elements and attributes in the XML document. The class also infers schema components in a constrained way by inferring the most restrictive type for a particular element or attribute. As more information about the XML document is gathered, these constraints are loosened by inferring less restrictive types. The least restrictive type that can be inferred is `xs:string`. @@ -42,9 +42,9 @@ This topic describes how to use the ## Inferring Schemas from XML Documents The class uses two overloaded methods to infer a schema from an XML document. - The first method is used to create a schema based on an XML document. The second method is used to infer a schema that describes multiple XML documents. For example, you can feed multiple XML documents to the method one at a time to produce a schema that describes the entire set of XML documents. + The first method is used to create a schema based on an XML document. The second method is used to infer a schema that describes multiple XML documents. For example, you can feed multiple XML documents to the method one at a time to produce a schema that describes the entire set of XML documents. - The first method infers a schema from an XML document contained in an object, and returns an object containing the inferred schema. The second method searches an object for a schema with the same target namespace as the XML document contained in the object, refines the existing schema, and returns an object containing the inferred schema. + The first method infers a schema from an XML document contained in an object, and returns an object containing the inferred schema. The second method searches an object for a schema with the same target namespace as the XML document contained in the object, refines the existing schema, and returns an object containing the inferred schema. The changes made to the refined schema are based on new structure found in the XML document. For example, as an XML document is traversed, assumptions are made about the data types found, and the schema is created based on those assumptions. However, if data is encountered on a second inference pass that differs from the original assumption, the schema is refined. The following example illustrates the refinement process. diff --git a/docs/standard/data/xml/inputs-to-the-xslcompiledtransform-class.md b/docs/standard/data/xml/inputs-to-the-xslcompiledtransform-class.md index 5436c64fc428d..e0ec886ebc5c7 100644 --- a/docs/standard/data/xml/inputs-to-the-xslcompiledtransform-class.md +++ b/docs/standard/data/xml/inputs-to-the-xslcompiledtransform-class.md @@ -35,7 +35,7 @@ The method accepts three > [!NOTE] > Transformations apply to the document as a whole. In other words, if you pass in a node other than the document root node, this does not prevent the transformation process from accessing all nodes in the loaded document. To transform a node fragment, you must create an object containing just the node fragment, and pass that object to the method. For more information, see [How to: Transform a Node Fragment](../../../../docs/standard/data/xml/how-to-transform-a-node-fragment.md). - The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](../../../../docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md). + The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](../../../../docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md). [!code-csharp[XslCompiledTransform.Transform2#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XslCompiledTransform.Transform2/CS/Program.cs#1)] [!code-vb[XslCompiledTransform.Transform2#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#1)] @@ -43,7 +43,7 @@ The method accepts three ## XmlReader Object The method loads from the current node of the through all its children. This enables you to use a portion of a document as the context document. After the method returns, the is positioned on the next node after the end of the context document. If the end of the document is reached, the is positioned at the end of file (EOF). - The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](../../../../docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md). + The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](../../../../docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md). [!code-csharp[XslCompiledTransform.Transform2#2](../../../../samples/snippets/csharp/VS_Snippets_Data/XslCompiledTransform.Transform2/CS/Program.cs#2)] [!code-vb[XslCompiledTransform.Transform2#2](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#2)] @@ -51,7 +51,7 @@ The method accepts three ## String URI You can also specify the source document URI as your XSLT input. An is used to resolve the URI. You can specify the to use by passing it to the method. If an is not specified, the method uses a default with no credentials. - The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](../../../../docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md). + The following example uses the method to transform the books.xml file to the books.html file using the transform.xsl style sheet. The books.xml and transform.xsl files can be found in this topic: [How to: Perform an XSLT Transformation by Using an Assembly](../../../../docs/standard/data/xml/how-to-perform-an-xslt-transformation-by-using-an-assembly.md). [!code-csharp[XslCompiledTransform.Transform2#3](../../../../samples/snippets/csharp/VS_Snippets_Data/XslCompiledTransform.Transform2/CS/Program.cs#3)] [!code-vb[XslCompiledTransform.Transform2#3](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XslCompiledTransform.Transform2/VB/Module1.vb#3)] diff --git a/docs/standard/data/xml/output-options-on-the-xslcompiledtransform-class.md b/docs/standard/data/xml/output-options-on-the-xslcompiledtransform-class.md index 053c84e0a808d..0bede90f24820 100644 --- a/docs/standard/data/xml/output-options-on-the-xslcompiledtransform-class.md +++ b/docs/standard/data/xml/output-options-on-the-xslcompiledtransform-class.md @@ -31,7 +31,7 @@ This topic discusses the available XSLT output options. You can specify output o |--------------------|--------------| |method|Supported.| |version|Ignored. The version is always 1.0 for XML and 4.0 for HTML.| -|encoding|Ignored when outputting to a . The property is used instead.| +|encoding|Ignored when outputting to a . The property is used instead.| |omit-xml-declaration|Supported.| |standalone|Supported.| |doctype-public|Supported.| @@ -41,7 +41,7 @@ This topic discusses the available XSLT output options. You can specify output o |media-type|Supported.| #### Sending Output to an XmlWriter - If your style sheet uses the `xsl:output` element and the output type is an object, you should use the property when you create the object. The property returns an object that contains information derived from the `xsl:output` element of a compiled style sheet. This object can be passed to the method to create an object with the correct settings. + If your style sheet uses the `xsl:output` element and the output type is an object, you should use the property when you create the object. The property returns an object that contains information derived from the `xsl:output` element of a compiled style sheet. This object can be passed to the method to create an object with the correct settings. ## Output Types The following list describes the output types available on the command. diff --git a/docs/standard/data/xml/post-schema-compilation-infoset.md b/docs/standard/data/xml/post-schema-compilation-infoset.md index bdfcd1ed3fab4..a413442dc10e0 100644 --- a/docs/standard/data/xml/post-schema-compilation-infoset.md +++ b/docs/standard/data/xml/post-schema-compilation-infoset.md @@ -24,7 +24,7 @@ The [World Wide Web Consortium (W3C) XML Schema Recommendation](http://go.micros The pre-schema validation infoset is built during the editing of the schema. The post-schema compilation infoset is generated after the method of the is called, during compilation of the schema, and is exposed as properties. - The SOM is the object model that represents the pre-schema validation and post-schema compilation infosets; it consists of the classes in the namespace. All read and write properties of classes in the namespace belong to the pre-schema validation infoset, while all read-only properties of classes in the namespace belong to the post-schema compilation infoset. The exception to this rule are the following properties, which are both pre-schema validation infoset and post-schema compilation infoset properties. + The SOM is the object model that represents the pre-schema validation and post-schema compilation infosets; it consists of the classes in the namespace. All read and write properties of classes in the namespace belong to the pre-schema validation infoset, while all read-only properties of classes in the namespace belong to the post-schema compilation infoset. The exception to this rule are the following properties, which are both pre-schema validation infoset and post-schema compilation infoset properties. |Class|Property| |-----------|--------------| diff --git a/docs/standard/data/xml/process-xml-data-using-the-xpath-data-model.md b/docs/standard/data/xml/process-xml-data-using-the-xpath-data-model.md index e3f4ccdc367c7..39d293f5a2134 100644 --- a/docs/standard/data/xml/process-xml-data-using-the-xpath-data-model.md +++ b/docs/standard/data/xml/process-xml-data-using-the-xpath-data-model.md @@ -20,7 +20,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Process XML Data Using the XPath Data Model -The namespace provides a programmatic representation of XML documents, fragments, nodes, or node-sets in-memory, using the or classes. +The namespace provides a programmatic representation of XML documents, fragments, nodes, or node-sets in-memory, using the or classes. The class provides a fast, read-only, in-memory representation of an XML document using the XPath data model. The class provides an editable in-memory representation of an XML document implementing W3C Document Object Model (DOM) Level 1 Core and Core DOM Level 2. Both classes implement the interface and return an object used to select, evaluate, navigate, and in some cases, edit the underlying XML data. diff --git a/docs/standard/data/xml/reading-an-xml-document-into-the-dom.md b/docs/standard/data/xml/reading-an-xml-document-into-the-dom.md index b76340d59bb60..eaa9a4ba026e6 100644 --- a/docs/standard/data/xml/reading-an-xml-document-into-the-dom.md +++ b/docs/standard/data/xml/reading-an-xml-document-into-the-dom.md @@ -29,7 +29,7 @@ XML information is read into memory from different formats. It can be read from |Subject|Topic| |-------------|-----------| |Creation of white space nodes|The object used to load the DOM has an affect on the white space and significant white space nodes generated in the DOM. For more information, see [White Space and Significant White Space Handling when Loading the DOM](../../../../docs/standard/data/xml/white-space-and-significant-white-space-handling-when-loading-the-dom.md).| -|Loading XML starting from a specific node or loading the entire XML document|Using the method data can be loaded from a specific node into the DOM. For more information, see [Load Data from a Reader](../../../../docs/standard/data/xml/load-data-from-a-reader.md).| +|Loading XML starting from a specific node or loading the entire XML document|Using the method data can be loaded from a specific node into the DOM. For more information, see [Load Data from a Reader](../../../../docs/standard/data/xml/load-data-from-a-reader.md).| |Validating the XML as it is loaded|The XML data loaded into the DOM can be validated as it is loaded. This is accomplished using a validating . For more information about validating XML as it is loaded, see [Validating an XML Document in the DOM](../../../../docs/standard/data/xml/validating-an-xml-document-in-the-dom.md).| The following example shows XML being loaded with the method and the data subsequently saved to a text file called `data.xml`. diff --git a/docs/standard/data/xml/reading-and-writing-xml-schemas.md b/docs/standard/data/xml/reading-and-writing-xml-schemas.md index 526c216bf6141..a76ff17acbb05 100644 --- a/docs/standard/data/xml/reading-and-writing-xml-schemas.md +++ b/docs/standard/data/xml/reading-and-writing-xml-schemas.md @@ -20,7 +20,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Reading and Writing XML Schemas -The Schema Object Model (SOM) API can be used to read and write XML Schema definition language (XSD) schemas from files or other sources and build XML schemas in-memory using the classes in the namespace that map to the structures defined in the World Wide Web Consortium (W3C) XML Schema Recommendation. +The Schema Object Model (SOM) API can be used to read and write XML Schema definition language (XSD) schemas from files or other sources and build XML schemas in-memory using the classes in the namespace that map to the structures defined in the World Wide Web Consortium (W3C) XML Schema Recommendation. ## Reading and Writing XML Schemas The class provides the and methods to read and write XML schemas. The method returns an object representing the XML schema and takes an optional as a parameter to handle schema validation warnings and errors encountered while reading an XML schema. diff --git a/docs/standard/data/xml/reading-xml-data-using-xpathdocument-and-xmldocument.md b/docs/standard/data/xml/reading-xml-data-using-xpathdocument-and-xmldocument.md index 541ec86449932..59e4475211014 100644 --- a/docs/standard/data/xml/reading-xml-data-using-xpathdocument-and-xmldocument.md +++ b/docs/standard/data/xml/reading-xml-data-using-xpathdocument-and-xmldocument.md @@ -20,7 +20,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Reading XML Data using XPathDocument and XmlDocument -There are two ways to read an XML document in the namespace. One is to read an XML document using the read-only class and the other is to read an XML document using the editable class in the namespace. +There are two ways to read an XML document in the namespace. One is to read an XML document using the read-only class and the other is to read an XML document using the editable class in the namespace. ## Reading XML Documents using the XPathDocument Class The class provides a fast, read-only, in-memory representation of an XML document using the XPath data model. Instances of the class are created using one of its six constructors. These constructors allow you to read an XML document using a , , or object, as well as the `string` path to an XML file. @@ -60,7 +60,7 @@ document.Load("books.xml"); ## Creating XPathNavigator Objects After you have read an XML document into either an or object, you can create an object to select, evaluate, navigate, and in some cases, edit the underlying XML data. - Both the and classes, in addition to the class, implement the interface of the namespace. As a result, all three classes provide a method that returns an object. + Both the and classes, in addition to the class, implement the interface of the namespace. As a result, all three classes provide a method that returns an object. ### Editing XML Documents using the XPathNavigator Class In addition to selecting, evaluating, and navigating XML data, the class can be used to edit an XML document in some cases, based on the object that created it. diff --git a/docs/standard/data/xml/recoverable-xslt-errors.md b/docs/standard/data/xml/recoverable-xslt-errors.md index 9f3d166715bec..17b317abf5368 100644 --- a/docs/standard/data/xml/recoverable-xslt-errors.md +++ b/docs/standard/data/xml/recoverable-xslt-errors.md @@ -25,7 +25,7 @@ The W3C XSL Transformations (XSLT) Version 1.0 Recommendation includes areas in ## Discretionary Behaviors The following table lists each of the discretionary behaviors allowed by the XSLT 1.0 recommendation, and how these behaviors are handled by the class. -- Recover indicates that the class will recover from this error. The event can be used to report any events from the XSLT processor. +- Recover indicates that the class will recover from this error. The event can be used to report any events from the XSLT processor. - Error indicates that an exception is raised for this condition. diff --git a/docs/standard/data/xml/resolving-external-xslt-style-sheets-and-documents.md b/docs/standard/data/xml/resolving-external-xslt-style-sheets-and-documents.md index bcec21e8e6df0..6787b776f333f 100644 --- a/docs/standard/data/xml/resolving-external-xslt-style-sheets-and-documents.md +++ b/docs/standard/data/xml/resolving-external-xslt-style-sheets-and-documents.md @@ -46,7 +46,7 @@ There are several times during a transformation when you may need to resolve ext The `document()` function retrieves other XML resources from a style sheet, in addition to the initial XML data provided by the input stream. Since this function allows the inclusion of XML data that can be located elsewhere, an with a `null` value supplied to the method prevents the `document()` function from executing. If you want to use the `document()` function, use the method that takes an as a parameter, in addition to having the appropriate permission set. - For more information on the method and its use of the , see . + For more information on the method and its use of the , see . When the method is called, permissions are calculated against the evidence provided at load time, and that permission set is assigned to the entire transformation process. If the `document()` function attempts to initiate an action that requires permissions not found in the set, an exception is thrown. diff --git a/docs/standard/data/xml/saving-and-writing-a-document.md b/docs/standard/data/xml/saving-and-writing-a-document.md index 86e14ba1d09b0..3b8446d903e89 100644 --- a/docs/standard/data/xml/saving-and-writing-a-document.md +++ b/docs/standard/data/xml/saving-and-writing-a-document.md @@ -41,7 +41,7 @@ When you load and save an , the saved document may For the properties of , , and the , , and methods, the encoding written out in the XML declaration is taken from the node. If there is no node, is not written out. If there is no encoding in the node, encoding is not written out in the XML declaration. - The and methods always write out an . These methods take the encoding from the writer that it is writing to. That is, the encoding value on the writer overrides the encoding on the document and in the . For example, the following code does not write an encoding in the XML declaration found in the output file `out.xml`. + The and methods always write out an . These methods take the encoding from the writer that it is writing to. That is, the encoding value on the writer overrides the encoding on the document and in the . For example, the following code does not write an encoding in the XML declaration found in the output file `out.xml`. ```vb Dim doc As New XmlDocument() diff --git a/docs/standard/data/xml/script-blocks-using-msxsl-script.md b/docs/standard/data/xml/script-blocks-using-msxsl-script.md index 8d60fe6e1c80b..da73c0bea0f9b 100644 --- a/docs/standard/data/xml/script-blocks-using-msxsl-script.md +++ b/docs/standard/data/xml/script-blocks-using-msxsl-script.md @@ -37,7 +37,7 @@ The class supports embedded scripts u The `msxsl` prefix is bound to the `urn:schemas-microsoft-com:xslt` namespace URI. The style sheet must include the `xmlns:msxsl=urn:schemas-microsoft-com:xslt` namespace declaration. - The `language` attribute is optional. Its value is the code language of the embedded code block. The language is mapped to the appropriate CodeDOM compiler using the method. The class can support any Microsoft .NET language, assuming the appropriate provider is installed on the machine and is registered in the system.codedom section of the machine.config file. If a `language` attribute is not specified, the language defaults to JScript. The language name is not case-sensitive so 'JavaScript' and 'javascript' are equivalent. + The `language` attribute is optional. Its value is the code language of the embedded code block. The language is mapped to the appropriate CodeDOM compiler using the method. The class can support any Microsoft .NET language, assuming the appropriate provider is installed on the machine and is registered in the system.codedom section of the machine.config file. If a `language` attribute is not specified, the language defaults to JScript. The language name is not case-sensitive so 'JavaScript' and 'javascript' are equivalent. The `implements-prefix` attribute is mandatory. This attribute is used to declare a namespace and associate it with the script block. The value of this attribute is the prefix that represents the namespace. This prefix can be defined somewhere in a style sheet. diff --git a/docs/standard/data/xml/traversing-xml-schemas.md b/docs/standard/data/xml/traversing-xml-schemas.md index cb1188a6c864a..b14cb1c13d2ce 100644 --- a/docs/standard/data/xml/traversing-xml-schemas.md +++ b/docs/standard/data/xml/traversing-xml-schemas.md @@ -50,7 +50,7 @@ Traversing an XML schema using the Schema Object Model (SOM) API provides access 2. Retrieves the compiled object from the by iterating over the property. Because the schema is compiled, Post-Schema-Compilation-Infoset (PSCI) properties are accessible. -3. Iterates over each in the collection of the post-schema-compilation collection writing the name of each element to the console. +3. Iterates over each in the collection of the post-schema-compilation collection writing the name of each element to the console. 4. Gets the complex type of the `Customer` element using the class. @@ -58,7 +58,7 @@ Traversing an XML schema using the Schema Object Model (SOM) API provides access 6. Gets the sequence particle of the complex type using the class. -7. Iterates over each in the collection writing the name of each child element to the console. +7. Iterates over each in the collection writing the name of each child element to the console. The following is the complete code example. @@ -66,9 +66,9 @@ Traversing an XML schema using the Schema Object Model (SOM) API provides access [!code-csharp[XmlSchemaTraverseExample#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaTraverseExample/CS/XmlSchemaTraverseExample.cs#1)] [!code-vb[XmlSchemaTraverseExample#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaTraverseExample/VB/XmlSchemaTraverseExample.vb#1)] - The property can be , or if it is a user-defined simple type or a complex type. It can also be if it is one of the built-in datatypes defined in the W3C XML Schema Recommendation. In the customer schema, the of the `Customer` element is , and the `FirstName` and `LastName` elements are . + The property can be , or if it is a user-defined simple type or a complex type. It can also be if it is one of the built-in datatypes defined in the W3C XML Schema Recommendation. In the customer schema, the of the `Customer` element is , and the `FirstName` and `LastName` elements are . - The code example in the [Building XML Schemas](../../../../docs/standard/data/xml/building-xml-schemas.md) topic used the collection to add the attribute `CustomerId` to the `Customer` element. This is a pre-schema-compilation property. The corresponding Post-Schema-Compilation-Infoset property is the collection, which holds all the attributes of the complex type, including the ones that are inherited through type derivation. + The code example in the [Building XML Schemas](../../../../docs/standard/data/xml/building-xml-schemas.md) topic used the collection to add the attribute `CustomerId` to the `Customer` element. This is a pre-schema-compilation property. The corresponding Post-Schema-Compilation-Infoset property is the collection, which holds all the attributes of the complex type, including the ones that are inherited through type derivation. ## See Also [XML Schema Object Model Overview](../../../../docs/standard/data/xml/xml-schema-object-model-overview.md) diff --git a/docs/standard/data/xml/working-with-xml-schemas.md b/docs/standard/data/xml/working-with-xml-schemas.md index ca7d488f03e8c..c04464e00b326 100644 --- a/docs/standard/data/xml/working-with-xml-schemas.md +++ b/docs/standard/data/xml/working-with-xml-schemas.md @@ -26,7 +26,7 @@ To define the structure of an XML document, as well as its element relationships ## In This Section [XML Schema Object Model (SOM)](../../../../docs/standard/data/xml/xml-schema-object-model-som.md) - Discusses the Schema Object Model (SOM) in the namespace that provides a set of classes that allows you to read a Schema definition language (XSD) schema from a file or programmatically create a schema in-memory. + Discusses the Schema Object Model (SOM) in the namespace that provides a set of classes that allows you to read a Schema definition language (XSD) schema from a file or programmatically create a schema in-memory. [XmlSchemaSet for Schema Compilation](../../../../docs/standard/data/xml/xmlschemaset-for-schema-compilation.md) Discusses the class that is a cache where XSD schemas can be stored and validated. diff --git a/docs/standard/data/xml/xml-processing-options.md b/docs/standard/data/xml/xml-processing-options.md index 4741794afaaa8..dca976f86f751 100644 --- a/docs/standard/data/xml/xml-processing-options.md +++ b/docs/standard/data/xml/xml-processing-options.md @@ -27,10 +27,10 @@ See the following tables for a list of Microsoft technologies you can use to pro |**Option**|**Processing type**|**Description**| |----------------|-------------------------|---------------------| |[LINQ to XML](http://msdn.microsoft.com/library/f0fe21e9-ee43-4a55-b91a-0800e5782c13)
( namespace)|In-memory|- Based on the .NET Framework Language-Integrated Query (LINQ) technology.
- Provides query experience that is similar to SQL for objects, relational data, and XML data.
- Provides inituive document creation and transformation capabilities.
- Use this option if you're writing new code.| -||Stream-based|- Provides a fast, non-cached, forward-only way to access XML data.
- You can create objects by using the method, and specify the set of features to enable on the object by using the class.| -||Stream-based|- Provides a fast, non-cached, forward-only way to generate XML data.
- You can create objects by using the method, and specify the set of features to enable on the object by using the class.| -||In-memory|- Implements the [W3C Document Object Model (DOM) Level 1 Core](http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html) and [DOM Level 2 Core](http://www.w3.org/TR/DOM-Level-2-Core/) recommendations.
- You can create, insert, remove, and modify nodes by using methods and properties based on the familiar DOM model.
- Use this option if you're modifying existing code that utilizes the W3C DOM.| -||In-memory|- Offers several editing options and navigation capabilities using a cursor model.
- XML documents can be contained in an or object.
- Provides excellent performance for read-only processing of XML.
- Use this option if you're modifying existing code with XPath queries or XSLT transformations.| +||Stream-based|- Provides a fast, non-cached, forward-only way to access XML data.
- You can create objects by using the method, and specify the set of features to enable on the object by using the class.| +||Stream-based|- Provides a fast, non-cached, forward-only way to generate XML data.
- You can create objects by using the method, and specify the set of features to enable on the object by using the class.| +||In-memory|- Implements the [W3C Document Object Model (DOM) Level 1 Core](http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html) and [DOM Level 2 Core](http://www.w3.org/TR/DOM-Level-2-Core/) recommendations.
- You can create, insert, remove, and modify nodes by using methods and properties based on the familiar DOM model.
- Use this option if you're modifying existing code that utilizes the W3C DOM.| +||In-memory|- Offers several editing options and navigation capabilities using a cursor model.
- XML documents can be contained in an or object.
- Provides excellent performance for read-only processing of XML.
- Use this option if you're modifying existing code with XPath queries or XSLT transformations.| ||In-memory|- Provides options for transforming XML data using XSL transformations.
- The [XSLT Compiler (xsltc.exe)](../../../../docs/standard/data/xml/xslt-compiler-xsltc-exe.md) lets you reference pre-compiled transformations in your app.| ## Win32 and COM-based Options diff --git a/docs/standard/data/xml/xml-schema-object-model-overview.md b/docs/standard/data/xml/xml-schema-object-model-overview.md index f98e6d4f2739b..2dabce91f5865 100644 --- a/docs/standard/data/xml/xml-schema-object-model-overview.md +++ b/docs/standard/data/xml/xml-schema-object-model-overview.md @@ -39,7 +39,7 @@ The Schema Object Model (SOM) in the Microsoft .NET Framework is a rich API that - Dynamically edit a schema that can be complied and saved for use in the validation of XML instance documents. ## The Schema Object Model - The SOM consists of an extensive set of classes in the namespace corresponding to the elements in an XML schema. For example, the `...` element maps to the class, and all the information that can be contained within an `` element can be represented using the class. Similarly, the `...` and `...` elements map to the and classes respectively. This mapping continues for all the elements of an XML schema creating an XML schema object model in the namespace illustrated in the diagram that follows. + The SOM consists of an extensive set of classes in the namespace corresponding to the elements in an XML schema. For example, the `...` element maps to the class, and all the information that can be contained within an `` element can be represented using the class. Similarly, the `...` and `...` elements map to the and classes respectively. This mapping continues for all the elements of an XML schema creating an XML schema object model in the namespace illustrated in the diagram that follows. ![System.Xml.Schema Object Model](../../../../docs/standard/data/xml/media/xmlschemaobjmodeloverview.gif "XMLSchemaObjModelOverview") diff --git a/docs/standard/data/xml/xml-schema-object-model-som.md b/docs/standard/data/xml/xml-schema-object-model-som.md index 3923ae324e457..7e57ca0684dc1 100644 --- a/docs/standard/data/xml/xml-schema-object-model-som.md +++ b/docs/standard/data/xml/xml-schema-object-model-som.md @@ -22,7 +22,7 @@ manager: "wpickett" # XML Schema Object Model (SOM) An XML schema is a powerful and complex tool for creating and validating structure in compliant XML documents. Similar to data modeling in a relational database, a schema provides a way to define the structure of XML documents, by specifying the elements that can be used in the documents, as well as the structure and types that these elements must follow in order to be valid for that specific schema. - The Schema Object Model (SOM) provides a set of classes in the namespace that allow you to read a schema from a file or to programmatically create a schema in-memory. The schema can then be traversed, editing, compiled, validated, or written to a file. + The Schema Object Model (SOM) provides a set of classes in the namespace that allow you to read a schema from a file or to programmatically create a schema in-memory. The schema can then be traversed, editing, compiled, validated, or written to a file. ## In This Section [XML Schema Object Model Overview](../../../../docs/standard/data/xml/xml-schema-object-model-overview.md) @@ -32,7 +32,7 @@ An XML schema is a powerful and complex tool for creating and validating structu Describes how to read and write XML schemas from files or other sources. [Building XML Schemas](../../../../docs/standard/data/xml/building-xml-schemas.md) - Describes how to use the classes in the namespace to build XML schemas in-memory. + Describes how to use the classes in the namespace to build XML schemas in-memory. [Traversing XML Schemas](../../../../docs/standard/data/xml/traversing-xml-schemas.md) Describes how to traverse an XML schema to access the elements, attributes, and types stored in the SOM. diff --git a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemacollection.md b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemacollection.md index 80f74d47b3c81..637a775759d42 100644 --- a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemacollection.md +++ b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemacollection.md @@ -214,6 +214,6 @@ while(vr.Read()) { ## See Also - - + + [XmlSchemaCollection Schema Compilation](../../../../docs/standard/data/xml/xmlschemacollection-schema-compilation.md) diff --git a/docs/standard/data/xml/xml-type-support-implementation-notes.md b/docs/standard/data/xml/xml-type-support-implementation-notes.md index 8105af33004c1..505afd7dae08e 100644 --- a/docs/standard/data/xml/xml-type-support-implementation-notes.md +++ b/docs/standard/data/xml/xml-type-support-implementation-notes.md @@ -49,7 +49,7 @@ This topic describes some implementation details that you want to be aware of. Similarly, instances of `xs:gMonth`, `xs:gDay`, `xs:gYear`, `xs:gYearMonth` and `xs:gMonthDay` are also mapped to a object. Unused properties on the object are initialized to those from . > [!NOTE] -> You cannot rely on the value when the content is typed as `xs:gMonthDay`. The value is always set to 1904 in this case. +> You cannot rely on the value when the content is typed as `xs:gMonthDay`. The value is always set to 1904 in this case. ### xs:anyURI and System.Uri When an instance of `xs:anyURI` that represents a relative URI is mapped to a , the object does not have a base URI. diff --git a/docs/standard/data/xml/xmlschemaset-for-schema-compilation.md b/docs/standard/data/xml/xmlschemaset-for-schema-compilation.md index a9010bf16e2f8..d951b7f20f595 100644 --- a/docs/standard/data/xml/xmlschemaset-for-schema-compilation.md +++ b/docs/standard/data/xml/xmlschemaset-for-schema-compilation.md @@ -25,7 +25,7 @@ Describes the , a cache where XML Schema de ## The XmlSchemaSet Class The is a cache where XML Schema definition language (XSD) schemas can be stored and validated. - In version 1.0, XML schemas were loaded into an class as a library of schemas. In version 2.0, the and the classes are obsolete, and have been replaced by the methods, and the class respectively. + In version 1.0, XML schemas were loaded into an class as a library of schemas. In version 2.0, the and the classes are obsolete, and have been replaced by the methods, and the class respectively. The has been introduced to fix a number of issues including standards compatibility, performance, and the obsolete Microsoft XML-Data Reduced (XDR) schema format. diff --git a/docs/standard/data/xml/xmlschemavalidator-push-based-validation.md b/docs/standard/data/xml/xmlschemavalidator-push-based-validation.md index c83021787f46c..ab09981c8ab7c 100644 --- a/docs/standard/data/xml/xmlschemavalidator-push-based-validation.md +++ b/docs/standard/data/xml/xmlschemavalidator-push-based-validation.md @@ -80,20 +80,20 @@ The class provides an efficient, hig ### Initializing Validation After an object has been constructed, there are two overloaded methods used to initialize the state of the object. The following are the two methods. -- +- -- +- - The default method initializes an object to its starting state, and the overloaded method that takes an as a parameter initializes an object to its starting state for partial validation. + The default method initializes an object to its starting state, and the overloaded method that takes an as a parameter initializes an object to its starting state for partial validation. Both methods can only be called immediately after an object has been constructed or after a call to . - For an example of the method, see the example in the introduction. For more information about the method, see the class reference documentation. + For an example of the method, see the example in the introduction. For more information about the method, see the class reference documentation. #### Partial Validation - The method that takes an as a parameter initializes an object to its starting state for partial validation. + The method that takes an as a parameter initializes an object to its starting state for partial validation. - In the following example, an is initialized for partial validation using the method. The `orderNumber` schema element is passed by selecting the schema element by in the collection returned by the property of the object. The object then validates this specific element. + In the following example, an is initialized for partial validation using the method. The `orderNumber` schema element is passed by selecting the schema element by in the collection returned by the property of the object. The object then validates this specific element. ```vb Dim schemaSet As XmlSchemaSet = New XmlSchemaSet() @@ -143,7 +143,7 @@ validator.ValidateEndElement(null); > [!NOTE] > The target namespace of the parameter cannot match that of any element or attribute already encountered by the object. > -> If the value was not passed as a parameter to the constructor, the method does nothing. +> If the value was not passed as a parameter to the constructor, the method does nothing. The result of the method is dependant on the current XML node context being validated. For more information about validation contexts, see the "Validation Context" section of this topic. diff --git a/docs/standard/data/xml/xslt-compiler-xsltc-exe.md b/docs/standard/data/xml/xslt-compiler-xsltc-exe.md index b0ea3ffe20f73..8b0d0394a8ca0 100644 --- a/docs/standard/data/xml/xslt-compiler-xsltc-exe.md +++ b/docs/standard/data/xml/xslt-compiler-xsltc-exe.md @@ -20,7 +20,7 @@ ms.author: "mairaw" manager: "wpickett" --- # XSLT Compiler (xsltc.exe) -The XSLT compiler (xsltc.exe) compiles XSLT style sheets and generates an assembly. The compiled style sheet can then be passed directly into the method. You cannot generate signed assemblies with xsltc.exe. +The XSLT compiler (xsltc.exe) compiles XSLT style sheets and generates an assembly. The compiled style sheet can then be passed directly into the method. You cannot generate signed assemblies with xsltc.exe. The xsltc.exe tool is included with Visual Studio 2008. For more information, see the [Microsoft Download Center](http://go.microsoft.com/fwlink/?LinkId=89463). @@ -51,7 +51,7 @@ xsltc [options] [/class:] [[/class:] ...] |`?`|Displays command syntax and options for the tool.| ## Remarks - XSLT solutions can consist of multiple style sheet modules. The xsltc.exe tool generates assemblies from style sheets. The assemblies can then be passed into the method. This can help decrease performance costs in some XSLT deployment scenarios. + XSLT solutions can consist of multiple style sheet modules. The xsltc.exe tool generates assemblies from style sheets. The assemblies can then be passed into the method. This can help decrease performance costs in some XSLT deployment scenarios. > [!NOTE] > You must also include the compiled assembly as a reference in your application. diff --git a/docs/standard/data/xml/xslt-parameters.md b/docs/standard/data/xml/xslt-parameters.md index 9c5db913e8757..c46efaeaaed1a 100644 --- a/docs/standard/data/xml/xslt-parameters.md +++ b/docs/standard/data/xml/xslt-parameters.md @@ -35,11 +35,11 @@ XSLT parameters are added to the using th |W3C type|Equivalent .NET class (type)|XPath or XSLT type| |--------------|------------------------------------|------------------------| -|`String`||XPath| -|`Boolean`||XPath| -|`Number`||XPath| -|`Result Tree Fragment`||XSLT| -|`Node*`||XPath| +|`String`||XPath| +|`Boolean`||XPath| +|`Number`||XPath| +|`Result Tree Fragment`||XSLT| +|`Node*`||XPath| |`Node Set`|

**XPathNavigator[]**|XPath| *This is equivalent to a node set that contains a single node. diff --git a/docs/standard/data/xml/xslt-security-considerations.md b/docs/standard/data/xml/xslt-security-considerations.md index 5deefddeedd94..ae94ac50ebda9 100644 --- a/docs/standard/data/xml/xslt-security-considerations.md +++ b/docs/standard/data/xml/xslt-security-considerations.md @@ -33,7 +33,7 @@ The XSLT language has a rich set of features that give you a great deal of power Extension objects are added using the method. The FullTrust permission set is required to support extension objects. This ensures that elevation of permissions does not happen when extension object code is executed. Attempting to call the method without FullTrust permissions results in a security exception being thrown. ### Style Sheet Scripts - Scripts can be embedded in a style sheet using the `msxsl:script` extension element. Script support is an optional feature on the class that is disabled by default. Scripting can be enabled by setting the property to `true` and passing the object to the method. + Scripts can be embedded in a style sheet using the `msxsl:script` extension element. Script support is an optional feature on the class that is disabled by default. Scripting can be enabled by setting the property to `true` and passing the object to the method. #### Guidelines Enable scripting only when the style sheet comes from a trusted source. If you cannot verify the source of the style sheet, or if the style sheet does not come from a trusted source, pass in `null` for the XSLT settings argument. @@ -46,7 +46,7 @@ The XSLT language has a rich set of features that give you a great deal of power - When executing the transformation, the is used to resolve the `document()` function. > [!NOTE] - > The `document()` function is disabled by default on the class. This feature can be enabled by setting the property to `true` and passing the object to the method. + > The `document()` function is disabled by default on the class. This feature can be enabled by setting the property to `true` and passing the object to the method. The and methods each include overloads that accept an as one of its arguments. If an is not specified, a default with no credentials is used. diff --git a/docs/standard/data/xml/xsltransform-class-implements-the-xslt-processor.md b/docs/standard/data/xml/xsltransform-class-implements-the-xslt-processor.md index 642a75725caab..eabf7debec86a 100644 --- a/docs/standard/data/xml/xsltransform-class-implements-the-xslt-processor.md +++ b/docs/standard/data/xml/xsltransform-class-implements-the-xslt-processor.md @@ -230,7 +230,7 @@ Root node is book. |Void Transform(IXPathNavigable input, XsltArgumentList args, Stream output)|Void Transform(IXPathNavigable input, XsltArgumentList args, Stream output, XmlResolver resolver)| |Void Transform(String input, String output);|Void Transform(String input, String output, XmlResolver resolver);| - The property is obsolete in [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] version 1.1. Instead, use the new overloads which take an object. + The property is obsolete in [!INCLUDE[dnprdnshort](../../../../includes/dnprdnshort-md.md)] version 1.1. Instead, use the new overloads which take an object. ## See Also diff --git a/docs/standard/datetime/access-utc-and-local.md b/docs/standard/datetime/access-utc-and-local.md index aee073633460e..27295775e54d6 100644 --- a/docs/standard/datetime/access-utc-and-local.md +++ b/docs/standard/datetime/access-utc-and-local.md @@ -28,24 +28,24 @@ The class provides two properties, property to access Coordinated Universal Time. +1. Use the `static` (`Shared` in Visual Basic) property to access Coordinated Universal Time. -2. Rather than assigning the object returned by the property to an object variable, continue to access Coordinated Universal Time through the property. +2. Rather than assigning the object returned by the property to an object variable, continue to access Coordinated Universal Time through the property. ### To access the local time zone -1. Use the `static` (`Shared` in Visual Basic) property to access the local system time zone. +1. Use the `static` (`Shared` in Visual Basic) property to access the local system time zone. -2. Rather than assigning the object returned by the property to an object variable, continue to access the local time zone through the property. +2. Rather than assigning the object returned by the property to an object variable, continue to access the local time zone through the property. ## Example -The following code uses the and properties to convert a time from the U.S. and Canadian Eastern Standard time zone, as well as to display the time zone name to the console. +The following code uses the and properties to convert a time from the U.S. and Canadian Eastern Standard time zone, as well as to display the time zone name to the console. [!code-csharp[System.TimeZone2.Concepts#13](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.TimeZone2.Concepts/CS/TimeZone2Concepts.cs#13)] [!code-vb[System.TimeZone2.Concepts#13](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#13)] -You should always access the local time zone through the property rather than assigning the local time zone to a object variable. Similarly, you should always access Coordinated Universal Time through the property rather than assigning the UTC zone to a object variable. This prevents the object variable from being invalidated by a call to the method. +You should always access the local time zone through the property rather than assigning the local time zone to a object variable. Similarly, you should always access Coordinated Universal Time through the property rather than assigning the UTC zone to a object variable. This prevents the object variable from being invalidated by a call to the method. ## Compiling the code diff --git a/docs/standard/datetime/choosing-between-datetime.md b/docs/standard/datetime/choosing-between-datetime.md index 765c9107c3113..f61fbcd8bc86c 100644 --- a/docs/standard/datetime/choosing-between-datetime.md +++ b/docs/standard/datetime/choosing-between-datetime.md @@ -47,7 +47,7 @@ manager: "wpickett" ## The DateTime structure -A value defines a particular date and time. It includes a property that provides limited information about the time zone to which that date and time belongs. The value returned by the property indicates whether the value represents the local time (), Coordinated Universal Time (UTC) (), or an unspecified time (). +A value defines a particular date and time. It includes a property that provides limited information about the time zone to which that date and time belongs. The value returned by the property indicates whether the value represents the local time (), Coordinated Universal Time (UTC) (), or an unspecified time (). The structure is suitable for applications that do the following: @@ -65,10 +65,10 @@ The structure is suitable for applications that do the fo * Perform date and time arithmetic, but are concerned with general results. For example, in an addition operation that adds six months to a particular date and time, it is often not important whether the result is adjusted for daylight saving time. -Unless a particular value represents UTC, that date and time value is often ambiguous or limited in its portability. For example, if a value represents the local time, it is portable within that local time zone (that is, if the value is deserialized on another system in the same time zone, that value still unambiguously identifies a single point in time). Outside the local time zone, that value can have multiple interpretations. If the value's property is , it is even less portable: it is now ambiguous within the same time zone and possibly even on the same system on which it was first serialized. Only if a value represents UTC does that value unambiguously identify a single point in time regardless of the system or time zone in which the value is used. +Unless a particular value represents UTC, that date and time value is often ambiguous or limited in its portability. For example, if a value represents the local time, it is portable within that local time zone (that is, if the value is deserialized on another system in the same time zone, that value still unambiguously identifies a single point in time). Outside the local time zone, that value can have multiple interpretations. If the value's property is , it is even less portable: it is now ambiguous within the same time zone and possibly even on the same system on which it was first serialized. Only if a value represents UTC does that value unambiguously identify a single point in time regardless of the system or time zone in which the value is used. > [!IMPORTANT] -> When saving or sharing data, UTC should be used and the value's property should be set to . +> When saving or sharing data, UTC should be used and the value's property should be set to . ## The DateTimeOffset structure @@ -98,9 +98,9 @@ The structure represents a time interval. Its two typical * Reflecting the time interval between two date and time values. For example, subtracting one value from another returns a value. -* Measuring elapsed time. For example, the property returns a value that reflects the time interval that has elapsed since the call to one of the methods that begins to measure elapsed time. +* Measuring elapsed time. For example, the property returns a value that reflects the time interval that has elapsed since the call to one of the methods that begins to measure elapsed time. -A value can also be used as a replacement for a value when that value reflects a time without reference to a particular time of day. This usage is similar to the and properties, which return a value that represents the time without reference to a date. For example, the structure can be used to reflect a store's daily opening or closing time, or it can be used to represent the time at which any regular event occurs. +A value can also be used as a replacement for a value when that value reflects a time without reference to a particular time of day. This usage is similar to the and properties, which return a value that represents the time without reference to a date. For example, the structure can be used to reflect a store's daily opening or closing time, or it can be used to represent the time at which any regular event occurs. The following example defines a `StoreInfo` structure that includes objects for store opening and closing times, as well as a object that represents the store's time zone. The structure also includes two methods, `IsOpenNow` and `IsOpenAt`, that indicates whether the store is open at a time specified by the user, who is assumed to be in the local time zone. diff --git a/docs/standard/datetime/converting-between-datetime-and-offset.md b/docs/standard/datetime/converting-between-datetime-and-offset.md index b265020189fdd..3a3300c5fc3f5 100644 --- a/docs/standard/datetime/converting-between-datetime-and-offset.md +++ b/docs/standard/datetime/converting-between-datetime-and-offset.md @@ -50,7 +50,7 @@ In this case, the offset of the `utcTime2` variable is 00:00. Similarly, the fol [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#2](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#2)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#2)] -However, for values whose property is , these two conversion methods produce a value whose offset is that of the local time zone. This is shown in the following example, which is run in the U.S. Pacific Standard Time zone. +However, for values whose property is , these two conversion methods produce a value whose offset is that of the local time zone. This is shown in the following example, which is run in the U.S. Pacific Standard Time zone. [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#3](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#3)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#3)] @@ -60,7 +60,7 @@ If the value reflects the date and time in something othe [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#4](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#4)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#4)] -The second parameter to this constructor overload, a object that represents the time's offset from UTC, should be retrieved by calling the method of the time's corresponding time zone. The method's single parameter is the value that represents the date and time to be converted. If the time zone supports daylight saving time, this parameter allows the method to determine the appropriate offset for that particular date and time. +The second parameter to this constructor overload, a object that represents the time's offset from UTC, should be retrieved by calling the method of the time's corresponding time zone. The method's single parameter is the value that represents the date and time to be converted. If the time zone supports daylight saving time, this parameter allows the method to determine the appropriate offset for that particular date and time. ## Conversions from DateTimeOffset to DateTime @@ -71,20 +71,20 @@ The property is most commonly used to p This means that any information about the value's relationship to UTC is lost by the conversion when the property is used. This affects values that correspond to UTC time or to the system's local time because the structure reflects only those two time zones in its property. -To preserve as much time zone information as possible when converting a to a value, you can use the and properties. +To preserve as much time zone information as possible when converting a to a value, you can use the and properties. ### Converting a UTC time -To indicate that a converted value is the UTC time, you can retrieve the value of the property. It differs from the property in two ways: +To indicate that a converted value is the UTC time, you can retrieve the value of the property. It differs from the property in two ways: * It returns a value whose property is . -* If the property value does not equal , it converts the time to UTC. +* If the property value does not equal , it converts the time to UTC. > [!NOTE] -> If your application requires that converted values unambiguously identify a single point in time, you should consider using the property to handle all to conversions. +> If your application requires that converted values unambiguously identify a single point in time, you should consider using the property to handle all to conversions. -The following code uses the property to convert a value whose offset equals to a value. +The following code uses the property to convert a value whose offset equals to a value. [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#6](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#6)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#6)] @@ -96,17 +96,17 @@ The following code uses the property ### Converting a local time -To indicate that a value represents the local time, you can pass the value returned by the property to the `static` (`Shared` in Visual Basic) method. The method returns the date and time passed to it as its first parameter, but sets the property to the value specified by its second parameter. The following code uses the method when converting a value whose offset corresponds to that of the local time zone. +To indicate that a value represents the local time, you can pass the value returned by the property to the `static` (`Shared` in Visual Basic) method. The method returns the date and time passed to it as its first parameter, but sets the property to the value specified by its second parameter. The following code uses the method when converting a value whose offset corresponds to that of the local time zone. [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#7](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#7)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#7)] -You can also use the property to convert a value to a local value. The property of the returned value is . The following code uses the property when converting a value whose offset corresponds to that of the local time zone. +You can also use the property to convert a value to a local value. The property of the returned value is . The following code uses the property when converting a value whose offset corresponds to that of the local time zone. [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#10](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#10)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#10)] -When you retrieve a value using the property, the property's `get` accessor first converts the value to UTC, then converts it to local time by calling the method. This means that you can retrieve a value from the property to perform a time zone conversion at the same time that you perform a type conversion. It also means that the local time zone's adjustment rules are applied in performing the conversion. The following code illustrates the use of the property to perform both a type and a time zone conversion. +When you retrieve a value using the property, the property's `get` accessor first converts the value to UTC, then converts it to local time by calling the method. This means that you can retrieve a value from the property to perform a time zone conversion at the same time that you perform a type conversion. It also means that the local time zone's adjustment rules are applied in performing the conversion. The following code illustrates the use of the property to perform both a type and a time zone conversion. [!code-csharp[System.DateTimeOffset.Conceptual.Conversions#11](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/cs/Conversions.cs#11)] [!code-vb[System.DateTimeOffset.Conceptual.Conversions#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Conversions/vb/Conversions.vb#11)] @@ -125,7 +125,7 @@ The follow example calls the `ConvertFromDateTimeOffset` method to convert represents UTC. In fact, UTC is not a time in a particular time zone, but the time in relation to which the times in the world's time zones are standardized. Time zones can also have an offset of . +* It assumes that a date and time value whose offset is represents UTC. In fact, UTC is not a time in a particular time zone, but the time in relation to which the times in the world's time zones are standardized. Time zones can also have an offset of . * It assumes that a date and time whose offset equals that of the local time zone represents the local time zone. Because date and time values are disassociated from their original time zone, this may not be the case; the date and time can have originated in another time zone with the same offset. diff --git a/docs/standard/datetime/converting-between-time-zones.md b/docs/standard/datetime/converting-between-time-zones.md index 87be15144819c..b4d433986ed27 100644 --- a/docs/standard/datetime/converting-between-time-zones.md +++ b/docs/standard/datetime/converting-between-time-zones.md @@ -32,7 +32,7 @@ Coordinated Universal Time (UTC) is a high-precision, atomic time standard. The > [!NOTE] > You can also serialize a structure to unambiguously represent a single point in time. Because objects store a date and time value along with its offset from UTC, they always represent a particular point in time in relationship to UTC. -The easiest way to convert a time to UTC is to call the `static` (`Shared` in Visual Basic) method. The exact conversion performed by the method depends on the value of the `dateTime` parameter's property, as the following table shows. +The easiest way to convert a time to UTC is to call the `static` (`Shared` in Visual Basic) method. The exact conversion performed by the method depends on the value of the `dateTime` parameter's property, as the following table shows. | `DateTime.Kind` | Conversion | | -------------------------- | ------------------------------------------------------------------------------ | @@ -46,14 +46,14 @@ The following code converts the current local time to UTC and displays the resul [!code-vb[System.TimeZone2.Concepts#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#6)] > [!NOTE] -> The method does not necessarily produce results that are identical to the and methods. If the host system's local time zone includes multiple adjustment rules, applies the appropriate rule to a particular date and time. The other two methods always apply the latest adjustment rule. +> The method does not necessarily produce results that are identical to the and methods. If the host system's local time zone includes multiple adjustment rules, applies the appropriate rule to a particular date and time. The other two methods always apply the latest adjustment rule. -If the date and time value does not represent either the local time or UTC, the method will likely return an erroneous result. However, you can use the method to convert the date and time from a specified time zone. (For details on retrieving a object that represents the destination time zone, see [Finding the time zones defined on a local system](../../../docs/standard/datetime/finding-the-time-zones-on-local-system.md).) The following code uses the method to convert Eastern Standard Time to UTC. +If the date and time value does not represent either the local time or UTC, the method will likely return an erroneous result. However, you can use the method to convert the date and time from a specified time zone. (For details on retrieving a object that represents the destination time zone, see [Finding the time zones defined on a local system](../../../docs/standard/datetime/finding-the-time-zones-on-local-system.md).) The following code uses the method to convert Eastern Standard Time to UTC. [!code-csharp[System.TimeZone2.Concepts#7](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.TimeZone2.Concepts/CS/TimeZone2Concepts.cs#7)] [!code-vb[System.TimeZone2.Concepts#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#7)] -Note that this method throws an if the object's property and the time zone are mismatched. A mismatch occurs if the property is but the object does not represent the local time zone, or if the property is but the object does not equal . +Note that this method throws an if the object's property and the time zone are mismatched. A mismatch occurs if the property is but the object does not represent the local time zone, or if the property is but the object does not equal . All of these methods take values as parameters and return a value. For values, the structure has a instance method that converts the date and time of the current instance to UTC. The following example calls the method to convert a local time and several other times to Coordinated Universal Time (UTC). @@ -64,7 +64,7 @@ All of these methods take values as parameters and return To convert UTC to local time, see the "Converting UTC to Local Time" section that follows. To convert UTC to the time in any time zone that you designate, call the method. The method takes two parameters: -* The UTC to convert. This must be a value whose property is set to or . +* The UTC to convert. This must be a value whose property is set to or . * The time zone to convert the UTC to. @@ -84,9 +84,9 @@ To convert UTC to local time, call the met | `DateTimeKind.Utc` | Converts the value to local time. | > [!NOTE] -> The method behaves identically to the `DateTime.ToLocalTime` method. It takes a single parameter, which is the date and time value to convert. +> The method behaves identically to the `DateTime.ToLocalTime` method. It takes a single parameter, which is the date and time value to convert. -You can also convert the time in any designated time zone to local time by using the `static` (`Shared` in Visual Basic) method. This technique is discussed in the next section. +You can also convert the time in any designated time zone to local time by using the `static` (`Shared` in Visual Basic) method. This technique is discussed in the next section. ## Converting between any two time zones @@ -118,7 +118,7 @@ For example, if the date and time of a user request for a Web page is known and If the method is passed the string "9/1/2007 5:32:07 -05:00", which represents the date and time in a time zone five hours earlier than UTC, it returns 9/1/2007 3:32:07 AM -07:00 for a server located in the U.S. Pacific Standard Time zone. -The class also includes an overload of the method that performs time zone conversions with values. The method's parameters are a value and a reference to the time zone to which the time is to be converted. The method call returns a value. For example, the `ReturnTimeOnServer` method in the previous example could be rewritten as follows to call the method. +The class also includes an overload of the method that performs time zone conversions with values. The method's parameters are a value and a reference to the time zone to which the time is to be converted. The method call returns a value. For example, the `ReturnTimeOnServer` method in the previous example could be rewritten as follows to call the method. [!code-csharp[System.DateTimeOffset.Conceptual.OffsetConversions#2](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.OffsetConversions/cs/timeconversions2.cs#2)] [!code-vb[System.DateTimeOffset.Conceptual.OffsetConversions#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.OffsetConversions/vb/TimeConversions2.vb#2)] diff --git a/docs/standard/datetime/create-time-zones-with-adjustment-rules.md b/docs/standard/datetime/create-time-zones-with-adjustment-rules.md index 0768846e5dab7..d1d03d0cff31d 100644 --- a/docs/standard/datetime/create-time-zones-with-adjustment-rules.md +++ b/docs/standard/datetime/create-time-zones-with-adjustment-rules.md @@ -42,9 +42,9 @@ This topic shows how to create a time zone with adjustment rules. To create a ti 1. Define the starting transition time for the time zone adjustment. - You must call the method and pass it a value that defines the time of the transition, an integer value that defines the month of the transition, an integer value that defines the week on which the transition occurs, and a value that defines the day of the week on which the transition occurs. This method call instantiates a object. + You must call the method and pass it a value that defines the time of the transition, an integer value that defines the month of the transition, an integer value that defines the week on which the transition occurs, and a value that defines the day of the week on which the transition occurs. This method call instantiates a object. - 2. Define the ending transition time for the time zone adjustment. This requires another call to the method. This method call instantiates a second object. + 2. Define the ending transition time for the time zone adjustment. This requires another call to the method. This method call instantiates a second object. 3. Call the method and pass it the effective start and end dates of the adjustment, a object that defines the amount of time in the transition, and the two objects that define when the transitions to and from daylight saving time occur. This method call instantiates a object. @@ -60,7 +60,7 @@ This topic shows how to create a time zone with adjustment rules. To create a ti 6. Instantiate a object that defines the time zone's offset from UTC. Time zones with times that are later than UTC have a positive offset. Time zones with times that are earlier than UTC have a negative offset. -7. Call the method to instantiate the new time zone. +7. Call the method to instantiate the new time zone. ## Example @@ -73,7 +73,7 @@ The time zone created in this example has multiple adjustment rules. Care must b For floating adjustment rules, the value 5 is passed to the `week` parameter of the method to indicate that the transition occurs on the last week of a particular month. -In creating the array of objects to use in the method call, the code could initialize the array to the size required by the number of adjustments to be created for the time zone. Instead, this code example calls the method to add each adjustment rule to a generic collection of objects. The code then calls the method to copy the members of this collection to the array. +In creating the array of objects to use in the method call, the code could initialize the array to the size required by the number of adjustments to be created for the time zone. Instead, this code example calls the method to add each adjustment rule to a generic collection of objects. The code then calls the method to copy the members of this collection to the array. The example also uses the method to define fixed-date adjustments. This is similar to calling the method, except that it requires only the time, month, and day of the transition parameters. diff --git a/docs/standard/datetime/create-time-zones-without-adjustment-rules.md b/docs/standard/datetime/create-time-zones-without-adjustment-rules.md index f2db907a7aa2d..e81c05bb635ec 100644 --- a/docs/standard/datetime/create-time-zones-without-adjustment-rules.md +++ b/docs/standard/datetime/create-time-zones-without-adjustment-rules.md @@ -48,7 +48,7 @@ This topic shows how to create a time zone without adjustment rules. To create a 4. Instantiate a object that defines the time zone's offset from UTC. Time zones with times that are later than UTC have a positive offset. Time zones with times that are earlier than UTC have a negative offset. -5. Call the method to instantiate the new time zone. +5. Call the method to instantiate the new time zone. ## Example diff --git a/docs/standard/datetime/enumerate-time-zones.md b/docs/standard/datetime/enumerate-time-zones.md index 33276e231d633..4a9228331067f 100644 --- a/docs/standard/datetime/enumerate-time-zones.md +++ b/docs/standard/datetime/enumerate-time-zones.md @@ -27,7 +27,7 @@ Successfully working with a designated time zone requires that information about ### To enumerate the time zones present on the local system -1. Call the method. The method returns a generic collection of objects. The entries in the collection are sorted by their property. For example: +1. Call the method. The method returns a generic collection of objects. The entries in the collection are sorted by their property. For example: [!code-csharp[System.TimeZone2.Concepts#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.TimeZone2.Concepts/CS/TimeZone2Concepts.cs#1)] [!code-vb[System.TimeZone2.Concepts#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#1)] @@ -39,7 +39,7 @@ Successfully working with a designated time zone requires that information about ### To present the user with a list of time zones present on the local system -1. Call the method. The method returns a generic collection of objects. +1. Call the method. The method returns a generic collection of objects. 2. Assign the collection returned in step 1 to the `DataSource` property of a Windows forms or ASP.NET list control. @@ -54,7 +54,7 @@ The example starts a Windows application that displays the time zones defined on [!code-csharp[System.TimeZone2.Concepts#2](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.TimeZone2.Concepts/CS/TimeZone2Concepts.cs#2)] [!code-vb[System.TimeZone2.Concepts#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#2)] -Most list controls (such as the or control) allow you to assign a collection of object variables to their `DataSource` property as long as that collection implements the interface. (The generic class does this.) To display an individual object in the collection, the control calls that object's `ToString` method to extract the string that is used to represent the object. In the case of objects, the `ToString` method returns the object's display name (the value of its property). +Most list controls (such as the or control) allow you to assign a collection of object variables to their `DataSource` property as long as that collection implements the interface. (The generic class does this.) To display an individual object in the collection, the control calls that object's `ToString` method to extract the string that is used to represent the object. In the case of objects, the `ToString` method returns the object's display name (the value of its property). > [!NOTE] > Because list controls call an object's `ToString` method, you can assign a collection of objects to the control, have the control display a meaningful name for each object, and retrieve the object that the user has selected. This eliminates the need to extract a string for each object in the collection, assign the string to a collection that is in turn assigned to the control's `DataSource` property, retrieve the string the user has selected, and then use this string to extract the object that it describes. diff --git a/docs/standard/datetime/finding-the-time-zones-on-local-system.md b/docs/standard/datetime/finding-the-time-zones-on-local-system.md index 7fe441825fac5..fa0d0b0354a3b 100644 --- a/docs/standard/datetime/finding-the-time-zones-on-local-system.md +++ b/docs/standard/datetime/finding-the-time-zones-on-local-system.md @@ -38,7 +38,7 @@ You can also instantiate a object that represents any ## Time zone identifiers -The time zone identifier is a key field that uniquely identifies the time zone. While most keys are relatively short, the time zone identifier is comparatively long. In most cases, its value corresponds to the property, which is used to provide the name of the time zone's standard time. However, there are exceptions. The best way to make sure that you supply a valid identifier is to enumerate the time zones available on your system and note their associated identifiers. +The time zone identifier is a key field that uniquely identifies the time zone. While most keys are relatively short, the time zone identifier is comparatively long. In most cases, its value corresponds to the property, which is used to provide the name of the time zone's standard time. However, there are exceptions. The best way to make sure that you supply a valid identifier is to enumerate the time zones available on your system and note their associated identifiers. ## See also diff --git a/docs/standard/datetime/index.md b/docs/standard/datetime/index.md index 111abd8189124..7ab5d90070326 100644 --- a/docs/standard/datetime/index.md +++ b/docs/standard/datetime/index.md @@ -97,4 +97,4 @@ This section of the documentation provides the information that you need to work ## Reference - + diff --git a/docs/standard/datetime/instantiate-time-zone-info.md b/docs/standard/datetime/instantiate-time-zone-info.md index 6de5675da81f3..b096fbc83402e 100644 --- a/docs/standard/datetime/instantiate-time-zone-info.md +++ b/docs/standard/datetime/instantiate-time-zone-info.md @@ -26,7 +26,7 @@ The most common way to instantiate a object is to ret 1. Declare a object. -2. Call the `static` (`Shared` in Visual Basic) method. +2. Call the `static` (`Shared` in Visual Basic) method. 3. Handle any exceptions thrown by the method, particularly the that is thrown if the time zone is not defined in the registry. @@ -37,7 +37,7 @@ The following code retrieves a object that represents [!code-csharp[System.TimeZone2.Concepts#5](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.TimeZone2.Concepts/CS/TimeZone2Concepts.cs#5)] [!code-vb[System.TimeZone2.Concepts#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.TimeZone2.Concepts/VB/TimeZone2Concepts.vb#5)] -The method's single parameter is the identifier of the time zone that you want to retrieve, which corresponds to the object's property. The time zone identifier is a key field that uniquely identifies the time zone. While most keys are relatively short, the time zone identifier is comparatively long. In most cases, its value corresponds to the property of a object, which is used to provide the name of the time zone's standard time. However, there are exceptions. The best way to make sure that you supply a valid identifier is to enumerate the time zones available on your system and note the identifiers of the time zones present on them. For an illustration, see [How to: Enumerate time zones present on a computer](../../../docs/standard/datetime/enumerate-time-zones.md). The [Finding the time zones defined on a local system](../../../docs/standard/datetime/finding-the-time-zones-on-local-system.md) topic also contains a list of selected time zone identifiers. +The method's single parameter is the identifier of the time zone that you want to retrieve, which corresponds to the object's property. The time zone identifier is a key field that uniquely identifies the time zone. While most keys are relatively short, the time zone identifier is comparatively long. In most cases, its value corresponds to the property of a object, which is used to provide the name of the time zone's standard time. However, there are exceptions. The best way to make sure that you supply a valid identifier is to enumerate the time zones available on your system and note the identifiers of the time zones present on them. For an illustration, see [How to: Enumerate time zones present on a computer](../../../docs/standard/datetime/enumerate-time-zones.md). The [Finding the time zones defined on a local system](../../../docs/standard/datetime/finding-the-time-zones-on-local-system.md) topic also contains a list of selected time zone identifiers. If the time zone is found, the method returns its object. If the time zone is not found, the method throws a . If the time zone is found but its data is corrupted or incomplete, the method throws an . diff --git a/docs/standard/datetime/instantiating-a-datetimeoffset-object.md b/docs/standard/datetime/instantiating-a-datetimeoffset-object.md index 8d61c0c4cebdf..7d2a3e76f9a52 100644 --- a/docs/standard/datetime/instantiating-a-datetimeoffset-object.md +++ b/docs/standard/datetime/instantiating-a-datetimeoffset-object.md @@ -55,7 +55,7 @@ The type defines six constructors. Four of them cor Note that, when the value of the object instantiated using a object as one of the arguments to its constructor is displayed to the console, it is expressed as a date in the Gregorian rather than the Persian calendar. To output a date using the Persian calendar, see the example in the topic. -The other two constructors create a object from a value. The first of these has a single parameter, the value to convert to a value. The offset of the resulting value depends on the property of the constructor's single parameter. If its value is , the offset is set equal to . Otherwise, its offset is set equal to that of the local time zone. The following example illustrates the use of this constructor to instantiate objects representing UTC and the local time zone: +The other two constructors create a object from a value. The first of these has a single parameter, the value to convert to a value. The offset of the resulting value depends on the property of the constructor's single parameter. If its value is , the offset is set equal to . Otherwise, its offset is set equal to that of the local time zone. The following example illustrates the use of this constructor to instantiate objects representing UTC and the local time zone: [!code-csharp[System.DateTimeOffset.Conceptual.Instantiate#4](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Instantiate/cs/Instantiate.cs#4)] [!code-vb[System.DateTimeOffset.Conceptual.Instantiate#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Instantiate/vb/Instantiate.vb#4)] @@ -63,7 +63,7 @@ The other two constructors create a object from a < > [!NOTE] > Calling the overload of the constructor that has a single parameter is equivalent to performing an implicit conversion of a value to a value. -The second constructor that creates a object from a value has two parameters: the value to convert, and a value representing the date and time's offset from UTC. This offset value must correspond to the property of the constructor's first parameter or an is thrown. If the property of the first parameter is , the value of the second parameter must be . If the property of the first parameter is , the value of the second parameter must be the offset of the local system's time zone. If the property of the first parameter is , the offset can be any valid value. The following code illustrates calls to this constructor to convert to values. +The second constructor that creates a object from a value has two parameters: the value to convert, and a value representing the date and time's offset from UTC. This offset value must correspond to the property of the constructor's first parameter or an is thrown. If the property of the first parameter is , the value of the second parameter must be . If the property of the first parameter is , the value of the second parameter must be the offset of the local system's time zone. If the property of the first parameter is , the offset can be any valid value. The following code illustrates calls to this constructor to convert to values. [!code-csharp[System.DateTimeOffset.Conceptual.Instantiate#5](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Instantiate/cs/Instantiate.cs#5)] [!code-vb[System.DateTimeOffset.Conceptual.Instantiate#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Instantiate/vb/Instantiate.vb#5)] @@ -75,7 +75,7 @@ The type supports one implicit type conversion: fro [!code-csharp[System.DateTimeOffset.Conceptual.Instantiate#6](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Instantiate/cs/Instantiate.cs#6)] [!code-vb[System.DateTimeOffset.Conceptual.Instantiate#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual.Instantiate/vb/Instantiate.vb#6)] -The offset of the resulting value depends on the property value. If its value is , the offset is set equal to . If its value is either or , the offset is set equal to that of the local time zone. +The offset of the resulting value depends on the property value. If its value is , the offset is set equal to . If its value is either or , the offset is set equal to that of the local time zone. ## Parsing the string representation of a date and time diff --git a/docs/standard/datetime/let-users-resolve-ambiguous-times.md b/docs/standard/datetime/let-users-resolve-ambiguous-times.md index 32b7e6636374b..07e5e5f1e2141 100644 --- a/docs/standard/datetime/let-users-resolve-ambiguous-times.md +++ b/docs/standard/datetime/let-users-resolve-ambiguous-times.md @@ -40,7 +40,7 @@ This topic shows how to let a user resolve an ambiguous time. 5. Get the UTC date and time by subtracting the offset selected by the user from the local time. -6. Call the `static` (`Shared` in Visual Basic .NET) method to set the UTC date and time value's property to . +6. Call the `static` (`Shared` in Visual Basic .NET) method to set the UTC date and time value's property to . ## Example @@ -51,7 +51,7 @@ The following example prompts the user to enter a date and time and, if it is am The core of the example code uses an array of objects to indicate possible offsets of the ambiguous time from UTC. However, these offsets are unlikely to be meaningful to the user. To clarify the meaning of the offsets, the code also notes whether an offset represents the local time zone's standard time or its daylight saving time. The code determines which time is standard and which time is daylight by comparing the offset with the value of the property. This property indicates the difference between the UTC and the time zone's standard time. -In this example, all references to the local time zone are made through the property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the method invalidates any objects that the local time zone is assigned to. +In this example, all references to the local time zone are made through the property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the method invalidates any objects that the local time zone is assigned to. ## Compiling the code diff --git a/docs/standard/datetime/performing-arithmetic-operations.md b/docs/standard/datetime/performing-arithmetic-operations.md index d9bd629b3948b..9d722aee30548 100644 --- a/docs/standard/datetime/performing-arithmetic-operations.md +++ b/docs/standard/datetime/performing-arithmetic-operations.md @@ -29,18 +29,18 @@ Although both the and the st ## Comparisons and arithmetic operations with DateTime values -The property allows a value to be assigned to the date and time to indicate whether it represents local time, Coordinated Universal Time (UTC), or the time in an unspecified time zone. However, this limited time zone information is ignored when comparing or performing date and time arithmetic on values. The following example, which compares the current local time with the current UTC time, illustrates this. +The property allows a value to be assigned to the date and time to indicate whether it represents local time, Coordinated Universal Time (UTC), or the time in an unspecified time zone. However, this limited time zone information is ignored when comparing or performing date and time arithmetic on values. The following example, which compares the current local time with the current UTC time, illustrates this. [!code-csharp[System.DateTimeOffset.Conceptual#2](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual/cs/Conceptual2.cs#2)] [!code-vb[System.DateTimeOffset.Conceptual#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual/vb/Conceptual2.vb#2)] The method reports that the local time is earlier than (or less than) the UTC time, and the subtraction operation indicates that the difference between UTC and the local time for a system in the U.S. Pacific Standard Time zone is seven hours. But because these two values provide different representations of a single point in time, it is clear in this case that this time interval is completely attributable to the local time zone's offset from UTC. -More generally, the property does not affect the results returned by comparison and arithmetic methods (as the comparison of two identical points in time indicates), although it can affect the interpretation of those results. For example: +More generally, the property does not affect the results returned by comparison and arithmetic methods (as the comparison of two identical points in time indicates), although it can affect the interpretation of those results. For example: -* The result of any arithmetic operation performed on two date and time values whose properties both equal reflects the actual time interval between the two values. Similarly, the comparison of two such date and time values accurately reflects the relationship between times. +* The result of any arithmetic operation performed on two date and time values whose properties both equal reflects the actual time interval between the two values. Similarly, the comparison of two such date and time values accurately reflects the relationship between times. -* The result of any arithmetic or comparison operation performed on two date and time values whose properties both equal or on two date and time values with different property values reflects the difference in clock time between the two values. +* The result of any arithmetic or comparison operation performed on two date and time values whose properties both equal or on two date and time values with different property values reflects the difference in clock time between the two values. * Arithmetic or comparison operations on local date and time values do not consider whether a particular value is ambiguous or invalid, nor do they take account of the effect of any adjustment rules that result from the local time zone's transition to or from daylight saving time. @@ -59,7 +59,7 @@ A value includes not only a date and time, but also [!code-csharp[System.DateTimeOffset.Conceptual#3](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual/cs/Conceptual3.cs#3)] [!code-vb[System.DateTimeOffset.Conceptual#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.DateTimeOffset.Conceptual/vb/Conceptual3.vb#3)] -In this example, the method indicates that the current local time and the current UTC time are equal, and subtraction of values indicates that the difference between the two times is . +In this example, the method indicates that the current local time and the current UTC time are equal, and subtraction of values indicates that the difference between the two times is . The chief limitation of using values in date and time arithmetic is that although values have some time zone awareness, they are not fully time zone aware. Although the value's offset reflects a time zone's offset from UTC when a variable is first assigned a value, it becomes disassociated from the time zone thereafter. Because it is no longer directly associated with an identifiable time, the addition and subtraction of date and time intervals does not consider a time zone's adjustment rules. diff --git a/docs/standard/datetime/resolve-ambiguous-times.md b/docs/standard/datetime/resolve-ambiguous-times.md index bcf537271eb3e..2dbf83f1d3729 100644 --- a/docs/standard/datetime/resolve-ambiguous-times.md +++ b/docs/standard/datetime/resolve-ambiguous-times.md @@ -34,7 +34,7 @@ This topic shows how to resolve an ambiguous time by assuming that it represents 2. If the time is ambiguous, subtract the time from the object returned by the time zone's property. -3. Call the `static` (`Shared` in Visual Basic .NET) method to set the UTC date and time value's property to . +3. Call the `static` (`Shared` in Visual Basic .NET) method to set the UTC date and time value's property to . ## Example @@ -47,7 +47,7 @@ The example consists of a method named `ResolveAmbiguousTime` that determines wh Ordinarily, an ambiguous time is handled by calling the method to retrieve an array of objects that contain the ambiguous time's possible UTC offsets. However, this example makes the arbitrary assumption that an ambiguous time should always be mapped to the time zone's standard time. The property returns the offset between UTC and a time zone's standard time. -In this example, all references to the local time zone are made through the property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the method invalidates any objects that the local time zone is assigned to. +In this example, all references to the local time zone are made through the property; the local time zone is never assigned to an object variable. This is a recommended practice because a call to the method invalidates any objects that the local time zone is assigned to. ## Compiling the code diff --git a/docs/standard/datetime/restore-time-zones-from-an-embedded-resource.md b/docs/standard/datetime/restore-time-zones-from-an-embedded-resource.md index c7ef5322c73fc..e923574b9e86e 100644 --- a/docs/standard/datetime/restore-time-zones-from-an-embedded-resource.md +++ b/docs/standard/datetime/restore-time-zones-from-an-embedded-resource.md @@ -32,7 +32,7 @@ This topic describes how to restore time zones that have been saved in a resourc If the resource file is embedded in the same assembly that contains the time zone instantiation code, you can retrieve a reference to it by calling the `static` (`Shared` in Visual Basic) method. -3. If the call to the method fails, or if a custom time zone is to be instantiated, retrieve a string that contains the serialized time zone by calling the method. +3. If the call to the method fails, or if a custom time zone is to be instantiated, retrieve a string that contains the serialized time zone by calling the method. 4. Deserialize the time zone data by calling the method. diff --git a/docs/standard/datetime/save-time-zones-to-an-embedded-resource.md b/docs/standard/datetime/save-time-zones-to-an-embedded-resource.md index 0ec5edbcaff50..7f67330294d8d 100644 --- a/docs/standard/datetime/save-time-zones-to-an-embedded-resource.md +++ b/docs/standard/datetime/save-time-zones-to-an-embedded-resource.md @@ -46,11 +46,11 @@ In addition to a resource file that is compiled with the application, several ot 4. Instantiate a object by passing the object to the class constructor. -5. Pass the time zone's serialized string to the method. +5. Pass the time zone's serialized string to the method. -6. Call the method. +6. Call the method. -7. Call the method. +7. Call the method. 8. Close the object by calling its method. @@ -67,7 +67,7 @@ The following example serializes a object that repres This example serializes objects so that they are available in a resource file at compile time. -Because the method adds complete header information to a .NET XML resource file, it cannot be used to add resources to an existing file. The example handles this by checking for the SerializedTimeZones.resx file and, if it exists, storing all of its resources other than the two serialized time zones to a generic object. The existing file is then deleted and the existing resources are added to a new SerializedTimeZones.resx file. The serialized time zone data is also added to this file. +Because the method adds complete header information to a .NET XML resource file, it cannot be used to add resources to an existing file. The example handles this by checking for the SerializedTimeZones.resx file and, if it exists, storing all of its resources other than the two serialized time zones to a generic object. The existing file is then deleted and the existing resources are added to a new SerializedTimeZones.resx file. The serialized time zone data is also added to this file. The key (or **Name**) fields of resources should not contain embedded spaces. The method is called to remove all embedded spaces in the time zone identifiers before they are assigned to the resource file. diff --git a/docs/standard/datetime/saving-and-restoring-time-zones.md b/docs/standard/datetime/saving-and-restoring-time-zones.md index 5c4c10ccd4753..92a5e7575ba40 100644 --- a/docs/standard/datetime/saving-and-restoring-time-zones.md +++ b/docs/standard/datetime/saving-and-restoring-time-zones.md @@ -42,7 +42,7 @@ Saving and restoring a time zone by serializing and deserializing time zone data * You can serialize a object by calling that object's method. The method takes no parameters and returns a string that contains time zone information. -* You can deserialize a object from a serialized string by passing that string to the `static` (`Shared` in Visual Basic) method. +* You can deserialize a object from a serialized string by passing that string to the `static` (`Shared` in Visual Basic) method. ## Serialization and deserialization scenarios diff --git a/docs/standard/datetime/use-time-zones-in-arithmetic.md b/docs/standard/datetime/use-time-zones-in-arithmetic.md index 81ed7708e1c0c..594a629f57573 100644 --- a/docs/standard/datetime/use-time-zones-in-arithmetic.md +++ b/docs/standard/datetime/use-time-zones-in-arithmetic.md @@ -34,7 +34,7 @@ Ordinarily, when you perform date and time arithmetic using method. +4. Convert the time from UTC to the original time's associated time zone by calling the method. ## Example diff --git a/docs/standard/datetime/working-with-calendars.md b/docs/standard/datetime/working-with-calendars.md index be7bed7aedaf3..e205f512ee2ed 100644 --- a/docs/standard/datetime/working-with-calendars.md +++ b/docs/standard/datetime/working-with-calendars.md @@ -28,11 +28,11 @@ Although a date and time value represents a moment in time, its string represent ## Calendars in .NET -All calendars in .NET derive from the class, which provides the base calendar implementation. One of the classes that inherits from the class is the class, which is the base class for all lunisolar calendars. .NET includes the following calendar implementations: +All calendars in .NET derive from the class, which provides the base calendar implementation. One of the classes that inherits from the class is the class, which is the base class for all lunisolar calendars. .NET includes the following calendar implementations: * , which represents the Chinese lunisolar calendar. -* , which represents the Gregorian calendar. This calendar is further divided into subtypes (such as Arabic and Middle East French) that are defined by the enumeration. The property specifies the subtype of the Gregorian calendar. +* , which represents the Gregorian calendar. This calendar is further divided into subtypes (such as Arabic and Middle East French) that are defined by the enumeration. The property specifies the subtype of the Gregorian calendar. * , which represents the Hebrew calendar. @@ -68,14 +68,14 @@ Note that six calendar classes – property. The property returns an array of objects that specifies all the calendars supported by a particular culture, including that culture's default calendar. +Each culture has a default calendar, which is defined by the property. The property returns an array of objects that specifies all the calendars supported by a particular culture, including that culture's default calendar. -The following example illustrates the and properties. It creates `CultureInfo` objects for the Thai (Thailand) and Japanese (Japan) cultures and displays their default and optional calendars. Note that in both cases, the culture's default calendar is also included in the collection. +The following example illustrates the and properties. It creates `CultureInfo` objects for the Thai (Thailand) and Japanese (Japan) cultures and displays their default and optional calendars. Note that in both cases, the culture's default calendar is also included in the collection. [!code-csharp[Conceptual.Calendars#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/calendarinfo1.cs#1)] [!code-vb[Conceptual.Calendars#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/calendarinfo1.vb#1)] -The calendar currently in use by a particular object is defined by the culture's property. A culture's object is returned by the property. When a culture is created, its default value is the same as the value of the property. However, you can change the culture's current calendar to any calendar contained in the array returned by the property. If you try to set the current calendar to a calendar that is not included in the property value, an is thrown. +The calendar currently in use by a particular object is defined by the culture's property. A culture's object is returned by the property. When a culture is created, its default value is the same as the value of the property. However, you can change the culture's current calendar to any calendar contained in the array returned by the property. If you try to set the current calendar to a calendar that is not included in the property value, an is thrown. The following example changes the calendar used by the Arabic (Saudi Arabia) culture. It first instantiates a value and displays it using the current culture - which, in this case, is English (United States) - and the current culture's calendar (which, in this case, is the Gregorian calendar). Next, it changes the current culture to Arabic (Saudi Arabia) and displays the date using its default Um Al-Qura calendar. It then calls the `CalendarExists` method to determine whether the Hijri calendar is supported by the Arabic (Saudi Arabia) culture. Because the calendar is supported, it changes the current calendar to Hijri and again displays the date. Note that in each case, the date is displayed using the current culture's current calendar. @@ -84,21 +84,21 @@ The following example changes the calendar used by the Arabic (Saudi Arabia) cul ## Dates and calendars -With the exception of the constructors that include a parameter of type and allow the elements of a date (that is, the month, the day, and the year) to reflect values in a designated calendar, both and values are always based on the Gregorian calendar. This means, for example, that the property returns the year in the Gregorian calendar, and the property returns the day of the month in the Gregorian calendar. +With the exception of the constructors that include a parameter of type and allow the elements of a date (that is, the month, the day, and the year) to reflect values in a designated calendar, both and values are always based on the Gregorian calendar. This means, for example, that the property returns the year in the Gregorian calendar, and the property returns the day of the month in the Gregorian calendar. > [!IMPORTANT] > It is important to remember that there is a difference between a date value and its string representation. The former is based on the Gregorian calendar; the latter is based on the current calendar of a specific culture. -The following example illustrates this difference between properties and their corresponding methods. In the example, the current culture is Arabic (Egypt), and the current calendar is Um Al Qura. A value is set to the fifteenth day of the seventh month of 2011. It is clear that this is interpreted as a Gregorian date, because these same values are returned by the method when it uses the conventions of the invariant culture. The string representation of the date that is formatted using the conventions of the current culture is 14/08/32, which is the equivalent date in the Um Al Qura calendar. Next, members of `DateTime` and `Calendar` are used to return the day, the month, and the year of the value. In each case, the values returned by members reflect values in the Gregorian calendar, whereas values returned by members reflect values in the Uum al-Qura calendar. +The following example illustrates this difference between properties and their corresponding methods. In the example, the current culture is Arabic (Egypt), and the current calendar is Um Al Qura. A value is set to the fifteenth day of the seventh month of 2011. It is clear that this is interpreted as a Gregorian date, because these same values are returned by the method when it uses the conventions of the invariant culture. The string representation of the date that is formatted using the conventions of the current culture is 14/08/32, which is the equivalent date in the Um Al Qura calendar. Next, members of `DateTime` and `Calendar` are used to return the day, the month, and the year of the value. In each case, the values returned by members reflect values in the Gregorian calendar, whereas values returned by members reflect values in the Uum al-Qura calendar. [!code-csharp[Conceptual.Calendars#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/datesandcalendars2.cs#3)] [!code-vb[Conceptual.Calendars#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/datesandcalendars2.vb#3)] ### Instantiating dates based on a calendar -Because and values are based on the Gregorian calendar, you must call an overloaded constructor that includes a parameter of type to instantiate a date value if you want to use the day, month, or year values from a different calendar. You can also call one of the overloads of a specific calendar's method to instantiate a object based on the values of a particular calendar. +Because and values are based on the Gregorian calendar, you must call an overloaded constructor that includes a parameter of type to instantiate a date value if you want to use the day, month, or year values from a different calendar. You can also call one of the overloads of a specific calendar's method to instantiate a object based on the values of a particular calendar. -The following example instantiates one value by passing a object to a constructor, and instantiates a second value by calling the method. Because the two values are created with identical values from the Hebrew calendar, the call to the method shows that the two values are equal. +The following example instantiates one value by passing a object to a constructor, and instantiates a second value by calling the method. Because the two values are created with identical values from the Hebrew calendar, the call to the method shows that the two values are equal. [!code-csharp[Conceptual.Calendars#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/instantiatehcdate1.cs#4)] [!code-vb[Conceptual.Calendars#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/instantiatehcdate1.vb#4)] @@ -114,7 +114,7 @@ The following example shows how the current calendar affects the string represen ### Representing dates in a non-current calendar -To represent a date using a calendar that is not the current calendar of a particular culture, you must call methods of that object. For example, the , , and methods convert the year, month, and day to values that reflect a particular calendar. +To represent a date using a calendar that is not the current calendar of a particular culture, you must call methods of that object. For example, the , , and methods convert the year, month, and day to values that reflect a particular calendar. > [!WARNING] > Because some calendars are not optional calendars of any culture, representing dates in these calendars always requires that you call calendar methods. This is true of all calendars that derive from the , , and classes. @@ -126,9 +126,9 @@ The following example uses a object t ### Calendars and date ranges -The earliest date supported by a calendar is indicated by that calendar's property. For the class, that date is January 1, 0001 C.E. Most of the other calendars in .NET support a later date. Trying to work with a date and time value that precedes a calendar's earliest supported date throws an exception. +The earliest date supported by a calendar is indicated by that calendar's property. For the class, that date is January 1, 0001 C.E. Most of the other calendars in .NET support a later date. Trying to work with a date and time value that precedes a calendar's earliest supported date throws an exception. -However, there is one important exception. The default (uninitialized) value of a object and a object is equal to the value. If you try to format this date in a calendar that does not support January 1, 0001 C.E. and you do not provide a format specifier, the formatting method uses the "s" (sortable date/time pattern) format specifier instead of the "G" (general date/time pattern) format specifier. As a result, the formatting operation does not throw an exception. Instead, it returns the unsupported date. This is illustrated in the following example, which displays the value of when the current culture is set to Japanese (Japan) with the Japanese calendar, and to Arabic (Egypt) with the Um Al Qura calendar. It also sets the current culture to English (United States) and calls the method with each of these objects. In each case, the date is displayed by using the sortable date/time pattern. +However, there is one important exception. The default (uninitialized) value of a object and a object is equal to the value. If you try to format this date in a calendar that does not support January 1, 0001 C.E. and you do not provide a format specifier, the formatting method uses the "s" (sortable date/time pattern) format specifier instead of the "G" (general date/time pattern) format specifier. As a result, the formatting operation does not throw an exception. Instead, it returns the unsupported date. This is illustrated in the following example, which displays the value of when the current culture is set to Japanese (Japan) with the Japanese calendar, and to Arabic (Egypt) with the Um Al Qura calendar. It also sets the current culture to English (United States) and calls the method with each of these objects. In each case, the date is displayed by using the sortable date/time pattern. [!code-csharp[Conceptual.Calendars#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/minsupporteddatetime1.cs#11)] [!code-vb[Conceptual.Calendars#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/minsupporteddatetime1.vb#11)] @@ -139,7 +139,7 @@ Calendars typically divide dates into eras. However, the array. The current era is at index zero, and for classes that support multiple eras, each successive index reflects the previous era. The static property defines the index of the current era in the array; it is a constant whose value is always zero. Individual classes also include static fields that return the value of the current era. They are listed in the following table. +In .NET, integers that represent the eras supported by a particular calendar implementation are stored in reverse order in the array. The current era is at index zero, and for classes that support multiple eras, each successive index reflects the previous era. The static property defines the index of the current era in the array; it is a constant whose value is always zero. Individual classes also include static fields that return the value of the current era. They are listed in the following table. | Calendar class | Current era field | | ----------------------------------------------------- | ----------------------------------------------------------------- | @@ -155,7 +155,7 @@ In .NET, integers that represent the eras supported by a particular calendar imp | | | | | | -The name that corresponds to a particular era number can be retrieved by passing the era number to the or method. The following example calls these methods to retrieve information about era support in the class. +The name that corresponds to a particular era number can be retrieved by passing the era number to the or method. The following example calls these methods to retrieve information about era support in the class. [!code-csharp[Conceptual.Calendars#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/instantiatewithera1.cs#7)] [!code-vb[Conceptual.Calendars#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/instantiatewithera1.vb#7)] @@ -164,9 +164,9 @@ In addition, the "g" custom date and time format string includes a calendar's er ### Instantiating a date with an era -For the two classes that support multiple eras, a date that consists of a particular year, month, and day of the month value can be ambiguous, For example, all four eras of the have years numbered from 1 to 15. Ordinarily, if an era is not specified, both date and time and calendar methods assume that values belong to the current era. To explicitly specify the era when instantiating a date for a class that supports multiple eras, you can call the method. This method enables you to explicitly specify an era along with the calendar's year, month, day, hour, minute, second, and millisecond. +For the two classes that support multiple eras, a date that consists of a particular year, month, and day of the month value can be ambiguous, For example, all four eras of the have years numbered from 1 to 15. Ordinarily, if an era is not specified, both date and time and calendar methods assume that values belong to the current era. To explicitly specify the era when instantiating a date for a class that supports multiple eras, you can call the method. This method enables you to explicitly specify an era along with the calendar's year, month, day, hour, minute, second, and millisecond. -The following example uses the method to instantiate the same date, the first month of the first day of the second year, in each era supported by the class. It then displays the date in both the Japanese and Gregorian calendars. It also calls a constructor to illustrate that methods that create date values without specifying an era create dates in the current era. +The following example uses the method to instantiate the same date, the first month of the first day of the second year, in each era supported by the class. It then displays the date in both the Japanese and Gregorian calendars. It also calls a constructor to illustrate that methods that create date values without specifying an era create dates in the current era. [!code-csharp[Conceptual.Calendars#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/instantiatewithera1.cs#7)] [!code-vb[Conceptual.Calendars#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/instantiatewithera1.vb#7)] @@ -186,7 +186,7 @@ For all calendars, the "g" custom format specifier includes the era in the resul [!code-csharp[Conceptual.Calendars#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/formatstrings2.cs#9)] [!code-vb[Conceptual.Calendars#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/formatstrings2.vb#9)] -In cases where the string representation of a date is expressed in a calendar that is not the current calendar, the class includes a method that can be used along with the , , and methods to unambiguously indicate a date as well as the era to which it belongs. The following example uses the class to provide an illustration. However, note that including a meaningful name or abbreviation instead of an integer for the era in the result string requires that you instantiate a object and make its current calendar. (The calendar cannot be the current calendar of any culture, but in this case the two calendars share the same eras.) +In cases where the string representation of a date is expressed in a calendar that is not the current calendar, the class includes a method that can be used along with the , , and methods to unambiguously indicate a date as well as the era to which it belongs. The following example uses the class to provide an illustration. However, note that including a meaningful name or abbreviation instead of an integer for the era in the result string requires that you instantiate a object and make its current calendar. (The calendar cannot be the current calendar of any culture, but in this case the two calendars share the same eras.) [!code-csharp[Conceptual.Calendars#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.calendars/cs/formatstrings3.cs#10)] [!code-vb[Conceptual.Calendars#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.calendars/vb/formatstrings3.vb#10)] diff --git a/docs/standard/design-guidelines/abstract-class.md b/docs/standard/design-guidelines/abstract-class.md index 330d256dad35a..e25190511c8a8 100644 --- a/docs/standard/design-guidelines/abstract-class.md +++ b/docs/standard/design-guidelines/abstract-class.md @@ -39,7 +39,7 @@ manager: "wpickett" **✓ 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. + 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.* diff --git a/docs/standard/design-guidelines/attributes.md b/docs/standard/design-guidelines/attributes.md index 12fbee97be3b0..ddc2c9bd83cf4 100644 --- a/docs/standard/design-guidelines/attributes.md +++ b/docs/standard/design-guidelines/attributes.md @@ -23,7 +23,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Attributes - is a base class used to define custom attributes. + 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 runtime 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. @@ -31,7 +31,7 @@ manager: "wpickett" 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. + 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." diff --git a/docs/standard/design-guidelines/dependency-properties.md b/docs/standard/design-guidelines/dependency-properties.md index 09c0426a42340..fb417d8301472 100644 --- a/docs/standard/design-guidelines/dependency-properties.md +++ b/docs/standard/design-guidelines/dependency-properties.md @@ -29,9 +29,9 @@ A dependency property (DP) is a regular property that stores its value in a prop ## 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** 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** implement dependency properties by calling instance methods and . **✓ DO** name the dependency property static field by suffixing the name of the property with "Property." @@ -48,7 +48,7 @@ A dependency property (DP) is a regular property that stores its value in a prop ## 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. + 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. ``` diff --git a/docs/standard/design-guidelines/dispose-pattern.md b/docs/standard/design-guidelines/dispose-pattern.md index b6943a362484e..b6b2422bed966 100644 --- a/docs/standard/design-guidelines/dispose-pattern.md +++ b/docs/standard/design-guidelines/dispose-pattern.md @@ -32,7 +32,7 @@ All programs acquire one or more system resources, such as memory, system handle Unfortunately, managed memory is just one of many types of system resources. Resources other than managed memory still need to be released explicitly and are referred to as unmanaged resources. The GC was specifically not designed to manage such unmanaged resources, which means that the responsibility for managing unmanaged resources lies in the hands of the developers. - The CLR provides some help in releasing unmanaged resources. declares a virtual method (also called the finalizer) that is called by the GC before the object’s memory is reclaimed by the GC and can be overridden to release unmanaged resources. Types that override the finalizer are referred to as finalizable types. + The CLR provides some help in releasing unmanaged resources. declares a virtual method (also called the finalizer) that is called by the GC before the object’s memory is reclaimed by the GC and can be overridden to release unmanaged resources. Types that override the finalizer are referred to as finalizable types. Although finalizers are effective in some cleanup scenarios, they have two significant drawbacks: @@ -42,7 +42,7 @@ All programs acquire one or more system resources, such as memory, system handle Therefore, relying exclusively on finalizers might not be appropriate in many scenarios when it is important to reclaim unmanaged resources as quickly as possible, when dealing with scarce resources, or in highly performant scenarios in which the added GC overhead of finalization is unacceptable. - The Framework provides the interface that should be implemented to provide the developer a manual way to release unmanaged resources as soon as they are not needed. It also provides the method that can tell the GC that an object was manually disposed of and does not need to be finalized anymore, in which case the object’s memory can be reclaimed earlier. Types that implement the `IDisposable` interface are referred to as disposable types. + The Framework provides the interface that should be implemented to provide the developer a manual way to release unmanaged resources as soon as they are not needed. It also provides the method that can tell the GC that an object was manually disposed of and does not need to be finalized anymore, in which case the object’s memory can be reclaimed earlier. Types that implement the `IDisposable` interface are referred to as disposable types. The Dispose Pattern is intended to standardize the usage and implementation of finalizers and the `IDisposable` interface. @@ -58,7 +58,7 @@ All programs acquire one or more system resources, such as memory, system handle **✓ CONSIDER** implementing the Basic Dispose Pattern on classes that themselves don’t hold unmanaged resources or disposable objects but are likely to have subtypes that do. - A great example of this is the class. Although it is an abstract base class that doesn’t hold any resources, most of its subclasses do and because of this, it implements this pattern. + A great example of this is the class. Although it is an abstract base class that doesn’t hold any resources, most of its subclasses do and because of this, it implements this pattern. ## Basic Dispose Pattern @@ -270,7 +270,7 @@ public class ComplexResourceHolder : IDisposable { For example, a finalizable object A that has a reference to another finalizable object B cannot reliably use B in A’s finalizer, or vice versa. Finalizers are called in a random order (short of a weak ordering guarantee for critical finalization). - Also, be aware that objects stored in static variables will get collected at certain points during an application domain unload or while exiting the process. Accessing a static variable that refers to a finalizable object (or calling a static method that might use values stored in static variables) might not be safe if returns true. + Also, be aware that objects stored in static variables will get collected at certain points during an application domain unload or while exiting the process. Accessing a static variable that refers to a finalizable object (or calling a static method that might use values stored in static variables) might not be safe if returns true. **✓ DO** make your `Finalize` method protected. @@ -287,8 +287,8 @@ public class ComplexResourceHolder : IDisposable { *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](http://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](../../../docs/standard/design-guidelines/index.md) [Common Design Patterns](../../../docs/standard/design-guidelines/common-design-patterns.md) [Garbage Collection](../../../docs/standard/garbage-collection/index.md) diff --git a/docs/standard/design-guidelines/enum.md b/docs/standard/design-guidelines/enum.md index fd9462f84bb94..d4c078e6b914f 100644 --- a/docs/standard/design-guidelines/enum.md +++ b/docs/standard/design-guidelines/enum.md @@ -72,13 +72,13 @@ Enums are a special kind of value type. There are two kinds of enums: simple enu **✓ DO** name flag enums with plural nouns or noun phrases and simple enums with singular nouns or noun phrases. - **X DO NOT** extend directly. + **X 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. + 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** 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. diff --git a/docs/standard/design-guidelines/equality-operators.md b/docs/standard/design-guidelines/equality-operators.md index d8084536780bf..36d97ae9914ad 100644 --- a/docs/standard/design-guidelines/equality-operators.md +++ b/docs/standard/design-guidelines/equality-operators.md @@ -30,7 +30,7 @@ This section discusses overloading equality operators and refers to `operator==` **X 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. + **✓ 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. diff --git a/docs/standard/design-guidelines/event.md b/docs/standard/design-guidelines/event.md index 9e04e331c6b52..dac712f13b061 100644 --- a/docs/standard/design-guidelines/event.md +++ b/docs/standard/design-guidelines/event.md @@ -33,7 +33,7 @@ Events are the most commonly used form of callbacks (constructs that allow the f **✓ 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. + **✓ 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. @@ -59,7 +59,7 @@ Events are the most commonly used form of callbacks (constructs that allow the f **✓ 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. + 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. @@ -70,7 +70,7 @@ Events are the most commonly used form of callbacks (constructs that allow the f **✓ 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** use or its subclass as the type of the second parameter of the event handler, and call it `e`. **X DO NOT** have more than two parameters on event handlers. diff --git a/docs/standard/design-guidelines/extension-methods.md b/docs/standard/design-guidelines/extension-methods.md index 270b82a450a72..56f193d7be941 100644 --- a/docs/standard/design-guidelines/extension-methods.md +++ b/docs/standard/design-guidelines/extension-methods.md @@ -32,9 +32,9 @@ Extension methods are a language feature that allows static methods to be called - 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. +- 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. - **X AVOID** defining extension methods on . + **X 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 runtime), while bindings to extension methods are determined at compile-time (early bound). diff --git a/docs/standard/design-guidelines/field.md b/docs/standard/design-guidelines/field.md index 3678739592e3f..e621ca8bdb346 100644 --- a/docs/standard/design-guidelines/field.md +++ b/docs/standard/design-guidelines/field.md @@ -44,7 +44,7 @@ The principle of encapsulation is one of the most important notions in object-or **X 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. + 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.* diff --git a/docs/standard/design-guidelines/interface.md b/docs/standard/design-guidelines/interface.md index 439b7b6a66983..47ae63eb672dd 100644 --- a/docs/standard/design-guidelines/interface.md +++ b/docs/standard/design-guidelines/interface.md @@ -44,7 +44,7 @@ Although most APIs are best modeled using classes and structs, there are cases i **✓ 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. + Doing this helps to validate the interface design. For example, consumes the interface. **X DO NOT** add members to an interface that has previously shipped. diff --git a/docs/standard/design-guidelines/names-of-namespaces.md b/docs/standard/design-guidelines/names-of-namespaces.md index d7ce9cffc255a..a19da2829fdf0 100644 --- a/docs/standard/design-guidelines/names-of-namespaces.md +++ b/docs/standard/design-guidelines/names-of-namespaces.md @@ -61,14 +61,14 @@ As with other naming guidelines, the goal when naming namespaces is creating suf - **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: + 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*` **X 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`. + For example, do not add a type named `Page` to the namespace, because the namespace already contains a type named `Page`. - **Infrastructure namespaces** @@ -80,7 +80,7 @@ As with other naming guidelines, the goal when naming namespaces is creating suf **X 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. + For example, never use `Stream` as a type name. It would conflict with , a very commonly used type. - **Technology namespace groups** diff --git a/docs/standard/design-guidelines/operator-overloads.md b/docs/standard/design-guidelines/operator-overloads.md index c2da9cfc49130..98576d0479270 100644 --- a/docs/standard/design-guidelines/operator-overloads.md +++ b/docs/standard/design-guidelines/operator-overloads.md @@ -33,9 +33,9 @@ Operator overloads allow framework types to appear as if they were built-in lang **✓ CONSIDER** defining operator overloads in a type that should feel like a primitive type. - For example, has `operator==` and `operator!=` defined. + For example, has `operator==` and `operator!=` defined. - **✓ DO** define operator overloads in structs that represent numbers (such as ). + **✓ DO** define operator overloads in structs that represent numbers (such as ). **X DO NOT** be cute when defining operator overloads. @@ -95,7 +95,7 @@ Operator overloads allow framework types to appear as if they were built-in lang |`~`|`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 . + 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. @@ -114,7 +114,7 @@ Operator overloads allow framework types to appear as if they were built-in lang 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. + **✓ 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.* diff --git a/docs/standard/design-guidelines/parameter-design.md b/docs/standard/design-guidelines/parameter-design.md index 0b5cad6893f17..8580093f09aec 100644 --- a/docs/standard/design-guidelines/parameter-design.md +++ b/docs/standard/design-guidelines/parameter-design.md @@ -58,7 +58,7 @@ This section provides broad guidelines on parameter design, including sections w **✓ 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. + **✓ 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. @@ -68,7 +68,7 @@ This section provides broad guidelines on parameter design, including sections w 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. - **X DO NOT** use for enum range checks. + **X DO NOT** use for enum range checks. **✓ DO** be aware that mutable arguments might have changed after they were validated. @@ -100,7 +100,7 @@ public class String { } ``` - A user can then call the method, as follows: + A user can then call the method, as follows: `String.Format("File {0} not found in {1}",new object[]{filename,directory});` diff --git a/docs/standard/design-guidelines/property.md b/docs/standard/design-guidelines/property.md index 515300051cf9d..c85c2d48d3638 100644 --- a/docs/standard/design-guidelines/property.md +++ b/docs/standard/design-guidelines/property.md @@ -50,7 +50,7 @@ Although properties are technically very similar to methods, they are quite diff ### 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. + 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. @@ -60,7 +60,7 @@ Although properties are technically very similar to methods, they are quite diff 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`. - **X AVOID** indexers with parameter types other than , , , , or an enum. + **X 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`. diff --git a/docs/standard/design-guidelines/serialization.md b/docs/standard/design-guidelines/serialization.md index 630c4eaff472e..b8f3ea1818676 100644 --- a/docs/standard/design-guidelines/serialization.md +++ b/docs/standard/design-guidelines/serialization.md @@ -70,7 +70,7 @@ Serialization is the process of converting an object into a format that can be r **✓ 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. + 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. @@ -84,7 +84,7 @@ Serialization is the process of converting an object into a format that can be r 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** 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. @@ -103,7 +103,7 @@ public class Person : ISerializable { **✓ DO** implement the `ISerializable` 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. + **✓ 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.* diff --git a/docs/standard/design-guidelines/static-class.md b/docs/standard/design-guidelines/static-class.md index e1ac487a6bb13..8a976ed96db3a 100644 --- a/docs/standard/design-guidelines/static-class.md +++ b/docs/standard/design-guidelines/static-class.md @@ -27,9 +27,9 @@ ms.author: "ronpet" manager: "wpickett" --- # 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. +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 ). + 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. diff --git a/docs/standard/design-guidelines/struct.md b/docs/standard/design-guidelines/struct.md index 42cc0e536dd90..f555e6a84e025 100644 --- a/docs/standard/design-guidelines/struct.md +++ b/docs/standard/design-guidelines/struct.md @@ -44,7 +44,7 @@ The general-purpose value type is most often referred to as a struct, its C# key **✓ 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. + 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. **X DO NOT** explicitly extend . In fact, most languages prevent this. diff --git a/docs/standard/design-guidelines/system-xml-usage.md b/docs/standard/design-guidelines/system-xml-usage.md index 4ac83b6591e7b..21c071da1bd40 100644 --- a/docs/standard/design-guidelines/system-xml-usage.md +++ b/docs/standard/design-guidelines/system-xml-usage.md @@ -20,7 +20,7 @@ ms.author: "ronpet" manager: "wpickett" --- # System.Xml Usage -This section talks about usage of several types residing in namespaces that can be used to represent XML data. +This section talks about usage of several types residing in namespaces that can be used to represent XML data. **X 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. diff --git a/docs/standard/design-guidelines/usage-guidelines.md b/docs/standard/design-guidelines/usage-guidelines.md index c1330ef11f1e2..8baa387e29df2 100644 --- a/docs/standard/design-guidelines/usage-guidelines.md +++ b/docs/standard/design-guidelines/usage-guidelines.md @@ -24,10 +24,10 @@ manager: "wpickett" # 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](../../../docs/standard/design-guidelines/dispose-pattern.md) section. + The interface is not covered in this section, but is discussed in the [Dispose Pattern](../../../docs/standard/design-guidelines/dispose-pattern.md) section. > [!NOTE] -> For guidelines and additional information about about other common, built-in .NET Framework types, see the reference topics for the following: , , , , , , , . +> For guidelines and additional information about about other common, built-in .NET Framework types, see the reference topics for the following: , , , , , , , . ## In This Section [Arrays](../../../docs/standard/design-guidelines/arrays.md) diff --git a/docs/standard/design-guidelines/using-standard-exception-types.md b/docs/standard/design-guidelines/using-standard-exception-types.md index 5043566adedf2..15bfd27e44578 100644 --- a/docs/standard/design-guidelines/using-standard-exception-types.md +++ b/docs/standard/design-guidelines/using-standard-exception-types.md @@ -28,7 +28,7 @@ manager: "wpickett" 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 - **X DO NOT** throw or . + **X DO NOT** throw or . **X DO NOT** catch `System.Exception` or `System.SystemException` in framework code, unless you intend to rethrow. diff --git a/docs/standard/events/how-to-consume-events-in-a-web-forms-application.md b/docs/standard/events/how-to-consume-events-in-a-web-forms-application.md index bdc2f34bd309f..e24027ff71dd2 100644 --- a/docs/standard/events/how-to-consume-events-in-a-web-forms-application.md +++ b/docs/standard/events/how-to-consume-events-in-a-web-forms-application.md @@ -21,7 +21,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Consume Events in a Web Forms Application -A common scenario in ASP.NET Web Forms applications is to populate a webpage with controls, and then perform a specific action based on which control the user clicks. For example, a control raises an event when the user clicks it in the webpage. By handling the event, your application can perform the appropriate application logic for that button click. +A common scenario in ASP.NET Web Forms applications is to populate a webpage with controls, and then perform a specific action based on which control the user clicks. For example, a control raises an event when the user clicks it in the webpage. By handling the event, your application can perform the appropriate application logic for that button click. ### To handle a button click event on a webpage diff --git a/docs/standard/events/how-to-handle-multiple-events-using-event-properties.md b/docs/standard/events/how-to-handle-multiple-events-using-event-properties.md index ed011bad9c85d..c5175acee5c7d 100644 --- a/docs/standard/events/how-to-handle-multiple-events-using-event-properties.md +++ b/docs/standard/events/how-to-handle-multiple-events-using-event-properties.md @@ -49,7 +49,7 @@ To use event properties, you define the event properties in the class that raise [!code-vb[Conceptual.Events.Other#31](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.events.other/vb/example3.vb#31)] ## See Also - + [Events](../../../docs/standard/events/index.md) [How to: Declare Custom Events To Conserve Memory](~/docs/visual-basic/programming-guide/language-features/events/how-to-declare-custom-events-to-conserve-memory.md) diff --git a/docs/standard/events/how-to-implement-a-provider.md b/docs/standard/events/how-to-implement-a-provider.md index 8f3cdfe55e6d1..44c5ba558028e 100644 --- a/docs/standard/events/how-to-implement-a-provider.md +++ b/docs/standard/events/how-to-implement-a-provider.md @@ -28,7 +28,7 @@ The observer design pattern requires a division between a provider, which monito [!code-csharp[Conceptual.ObserverDesign.HowTo#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/data.cs#1)] [!code-vb[Conceptual.ObserverDesign.HowTo#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/data.vb#1)] -2. Define the data provider, which is a type that implements the interface. The provider's generic type argument is the type that the provider sends to observers. The following example defines a `TemperatureMonitor` class, which is a constructed implementation with a generic type argument of `Temperature`. +2. Define the data provider, which is a type that implements the interface. The provider's generic type argument is the type that the provider sends to observers. The following example defines a `TemperatureMonitor` class, which is a constructed implementation with a generic type argument of `Temperature`. [!code-csharp[Conceptual.ObserverDesign.HowTo#2](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#2)] [!code-vb[Conceptual.ObserverDesign.HowTo#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#2)] @@ -38,17 +38,17 @@ The observer design pattern requires a division between a provider, which monito [!code-csharp[Conceptual.ObserverDesign.HowTo#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#3)] [!code-vb[Conceptual.ObserverDesign.HowTo#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#3)] -4. Define an implementation that the provider can return to subscribers so that they can stop receiving notifications at any time. The following example defines a nested `Unsubscriber` class that is passed a reference to the subscribers collection and to the subscriber when the class is instantiated. This code enables the subscriber to call the object's implementation to remove itself from the subscribers collection. +4. Define an implementation that the provider can return to subscribers so that they can stop receiving notifications at any time. The following example defines a nested `Unsubscriber` class that is passed a reference to the subscribers collection and to the subscriber when the class is instantiated. This code enables the subscriber to call the object's implementation to remove itself from the subscribers collection. [!code-csharp[Conceptual.ObserverDesign.HowTo#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#4)] [!code-vb[Conceptual.ObserverDesign.HowTo#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#4)] -5. Implement the method. The method is passed a reference to the interface and should be stored in the object designed for that purpose in step 3. The method should then return the implementation developed in step 4. The following example shows the implementation of the method in the `TemperatureMonitor` class. +5. Implement the method. The method is passed a reference to the interface and should be stored in the object designed for that purpose in step 3. The method should then return the implementation developed in step 4. The following example shows the implementation of the method in the `TemperatureMonitor` class. [!code-csharp[Conceptual.ObserverDesign.HowTo#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#5)] [!code-vb[Conceptual.ObserverDesign.HowTo#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#5)] -6. Notify observers as appropriate by calling their , , and implementations. In some cases, a provider may not call the method when an error occurs. For example, the following `GetTemperature` method simulates a monitor that reads temperature data every five seconds and notifies observers if the temperature has changed by at least .1 degree since the previous reading. If the device does not report a temperature (that is, if its value is null), the provider notifies observers that the transmission is complete. Note that, in addition to calling each observer's method, the `GetTemperature` method clears the collection. In this case, the provider makes no calls to the method of its observers. +6. Notify observers as appropriate by calling their , , and implementations. In some cases, a provider may not call the method when an error occurs. For example, the following `GetTemperature` method simulates a monitor that reads temperature data every five seconds and notifies observers if the temperature has changed by at least .1 degree since the previous reading. If the device does not report a temperature (that is, if its value is null), the provider notifies observers that the transmission is complete. Note that, in addition to calling each observer's method, the `GetTemperature` method clears the collection. In this case, the provider makes no calls to the method of its observers. [!code-csharp[Conceptual.ObserverDesign.HowTo#6](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/provider.cs#6)] [!code-vb[Conceptual.ObserverDesign.HowTo#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/provider.vb#6)] diff --git a/docs/standard/events/how-to-implement-an-observer.md b/docs/standard/events/how-to-implement-an-observer.md index 5c1fda32b20ee..f2e70420afe38 100644 --- a/docs/standard/events/how-to-implement-an-observer.md +++ b/docs/standard/events/how-to-implement-an-observer.md @@ -22,22 +22,22 @@ The observer design pattern requires a division between an observer, which regis ### To create an observer -1. Define the observer, which is a type that implements the interface. For example, the following code defines a type named `TemperatureReporter` that is a constructed implementation with a generic type argument of `Temperature`. +1. Define the observer, which is a type that implements the interface. For example, the following code defines a type named `TemperatureReporter` that is a constructed implementation with a generic type argument of `Temperature`. [!code-csharp[Conceptual.ObserverDesign.HowTo#8](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#8)] [!code-vb[Conceptual.ObserverDesign.HowTo#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#8)] -2. If the observer can stop receiving notifications before the provider calls its implementation, define a private variable that will hold the implementation returned by the provider's method. You should also define a subscription method that calls the provider's method and stores the returned object. For example, the following code defines a private variable named `unsubscriber` and defines a `Subscribe` method that calls the provider's method and assigns the returned object to the `unsubscriber` variable. +2. If the observer can stop receiving notifications before the provider calls its implementation, define a private variable that will hold the implementation returned by the provider's method. You should also define a subscription method that calls the provider's method and stores the returned object. For example, the following code defines a private variable named `unsubscriber` and defines a `Subscribe` method that calls the provider's method and assigns the returned object to the `unsubscriber` variable. [!code-csharp[Conceptual.ObserverDesign.HowTo#9](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#9)] [!code-vb[Conceptual.ObserverDesign.HowTo#9](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#9)] -3. Define a method that enables the observer to stop receiving notifications before the provider calls its implementation, if this feature is required. The following example defines an `Unsubscribe` method. +3. Define a method that enables the observer to stop receiving notifications before the provider calls its implementation, if this feature is required. The following example defines an `Unsubscribe` method. [!code-csharp[Conceptual.ObserverDesign.HowTo#10](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#10)] [!code-vb[Conceptual.ObserverDesign.HowTo#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#10)] -4. Provide implementations of the three methods defined by the interface: , , and . Depending on the provider and the needs of the application, the and methods can be stub implementations. Note that the method should not handle the passed object as an exception, and the method is free to call the provider's implementation. The following example shows the implementation of the `TemperatureReporter` class. +4. Provide implementations of the three methods defined by the interface: , , and . Depending on the provider and the needs of the application, the and methods can be stub implementations. Note that the method should not handle the passed object as an exception, and the method is free to call the provider's implementation. The following example shows the implementation of the `TemperatureReporter` class. [!code-csharp[Conceptual.ObserverDesign.HowTo#11](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.observerdesign.howto/cs/observer.cs#11)] [!code-vb[Conceptual.ObserverDesign.HowTo#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.observerdesign.howto/vb/observer.vb#11)] diff --git a/docs/standard/events/index.md b/docs/standard/events/index.md index c0b502b743e79..0be6cbecdac35 100644 --- a/docs/standard/events/index.md +++ b/docs/standard/events/index.md @@ -50,9 +50,9 @@ Events in the .NET Framework are based on the delegate model. The delegate model [!code-vb[EventsOverview#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/eventsoverview/vb/module1truncated.vb#4)] ## Event Data - Data that is associated with an event can be provided through an event data class. The .NET Framework provides many event data classes that you can use in your applications. For example, the class is the event data class for the event. The .NET Framework follows a naming pattern of ending all event data classes with `EventArgs`. You determine which event data class is associated with an event by looking at the delegate for the event. For example, the delegate includes the class as one of its parameters. + Data that is associated with an event can be provided through an event data class. The .NET Framework provides many event data classes that you can use in your applications. For example, the class is the event data class for the event. The .NET Framework follows a naming pattern of ending all event data classes with `EventArgs`. You determine which event data class is associated with an event by looking at the delegate for the event. For example, the delegate includes the class as one of its parameters. - The class is the base type for all event data classes. is also the class you use when an event does not have any data associated with it. When you create an event that is only meant to notify other classes that something happened and does not need to pass any data, include the class as the second parameter in the delegate. You can pass the value when no data is provided. The delegate includes the class as a parameter. + The class is the base type for all event data classes. is also the class you use when an event does not have any data associated with it. When you create an event that is only meant to notify other classes that something happened and does not need to pass any data, include the class as the second parameter in the delegate. You can pass the value when no data is provided. The delegate includes the class as a parameter. When you want to create a customized event data class, create a class that derives from , and then provide any members needed to pass data that is related to the event. Typically, you should use the same naming pattern as the .NET Framework and end your event data class name with `EventArgs`. diff --git a/docs/standard/events/observer-design-pattern-best-practices.md b/docs/standard/events/observer-design-pattern-best-practices.md index 24857afb25bd5..3651eb54384a1 100644 --- a/docs/standard/events/observer-design-pattern-best-practices.md +++ b/docs/standard/events/observer-design-pattern-best-practices.md @@ -18,10 +18,10 @@ ms.author: "ronpet" manager: "wpickett" --- # Observer Design Pattern Best Practices -In the .NET Framework, the observer design pattern is implemented as a set of interfaces. The interface represents the data provider, which is also responsible for providing an implementation that lets observers unsubscribe from notifications. The interface represents the observer. This topic describes the best practices that developers should follow when implementing the observer design pattern using these interfaces. +In the .NET Framework, the observer design pattern is implemented as a set of interfaces. The interface represents the data provider, which is also responsible for providing an implementation that lets observers unsubscribe from notifications. The interface represents the observer. This topic describes the best practices that developers should follow when implementing the observer design pattern using these interfaces. ## Threading - Typically, a provider implements the method by adding a particular observer to a subscriber list that is represented by some collection object, and it implements the method by removing a particular observer from the subscriber list. An observer can call these methods at any time. In addition, because the provider/observer contract does not specify who is responsible for unsubscribing after the callback method, the provider and observer may both try to remove the same member from the list. Because of this possibility, both the and methods should be thread-safe. Typically, this involves using a [concurrent collection](../../../docs/standard/parallel-programming/data-structures-for-parallel-programming.md) or a lock. Implementations that are not thread-safe should explicitly document that they are not. + Typically, a provider implements the method by adding a particular observer to a subscriber list that is represented by some collection object, and it implements the method by removing a particular observer from the subscriber list. An observer can call these methods at any time. In addition, because the provider/observer contract does not specify who is responsible for unsubscribing after the callback method, the provider and observer may both try to remove the same member from the list. Because of this possibility, both the and methods should be thread-safe. Typically, this involves using a [concurrent collection](../../../docs/standard/parallel-programming/data-structures-for-parallel-programming.md) or a lock. Implementations that are not thread-safe should explicitly document that they are not. Any additional guarantees have to be specified in a layer on top of the provider/observer contract. Implementers should clearly call out when they impose additional requirements to avoid user confusion about the observer contract. @@ -29,7 +29,7 @@ In the .NET Framework, the observer design pattern is implemented as a set of in Because of the loose coupling between a data provider and an observer, exceptions in the observer design pattern are intended to be informational. This affects how providers and observers handle exceptions in the observer design pattern. ### The Provider -- Calling the OnError Method - The method is intended as an informational message to observers, much like the method. However, the method is designed to provide an observer with current or updated data, whereas the method is designed to indicate that the provider is unable to provide valid data. + The method is intended as an informational message to observers, much like the method. However, the method is designed to provide an observer with current or updated data, whereas the method is designed to indicate that the provider is unable to provide valid data. The provider should follow these best practices when handling exceptions and calling the method: @@ -39,7 +39,7 @@ In the .NET Framework, the observer design pattern is implemented as a set of in - The provider should call the method when it handles an exception that compromises its ability to provide updates. Information on such exceptions can be passed to the observer. In other cases, there is no need to notify observers of an exception. - Once the provider calls the or method, there should be no further notifications, and the provider can unsubscribe its observers. However, the observers can also unsubscribe themselves at any time, including both before and after they receive an or notification. The observer design pattern does not dictate whether the provider or the observer is responsible for unsubscribing; therefore, there is a possibility that both may attempt to unsubscribe. Typically, when observers unsubscribe, they are removed from a subscribers collection. In a single-threaded application, the implementation should ensure that an object reference is valid and that the object is a member of the subscribers collection before attempting to remove it. In a multithreaded application, a thread-safe collection object, such as a object, should be used. + Once the provider calls the or method, there should be no further notifications, and the provider can unsubscribe its observers. However, the observers can also unsubscribe themselves at any time, including both before and after they receive an or notification. The observer design pattern does not dictate whether the provider or the observer is responsible for unsubscribing; therefore, there is a possibility that both may attempt to unsubscribe. Typically, when observers unsubscribe, they are removed from a subscribers collection. In a single-threaded application, the implementation should ensure that an object reference is valid and that the object is a member of the subscribers collection before attempting to remove it. In a multithreaded application, a thread-safe collection object, such as a object, should be used. ### The Observer -- Implementing the OnError Method When an observer receives an error notification from a provider, the observer should treat the exception as informational and should not be required to take any particular action. @@ -51,7 +51,7 @@ In the .NET Framework, the observer design pattern is implemented as a set of in - To preserve the call stack, an observer that wishes to throw an object that was passed to its method should wrap the exception before throwing it. A standard exception object should be used for this purpose. ## Additional Best Practices - Attempting to unregister in the method may result in a null reference. Therefore, we recommend that you avoid this practice. + Attempting to unregister in the method may result in a null reference. Therefore, we recommend that you avoid this practice. Although it is possible to attach an observer to multiple providers, the recommended pattern is to attach an instance to only one instance. diff --git a/docs/standard/events/observer-design-pattern.md b/docs/standard/events/observer-design-pattern.md index 47e1742d48b30..a9a5f549b6229 100644 --- a/docs/standard/events/observer-design-pattern.md +++ b/docs/standard/events/observer-design-pattern.md @@ -21,26 +21,26 @@ ms.author: "ronpet" manager: "wpickett" --- # Observer Design Pattern -The observer design pattern enables a subscriber to register with and receive notifications from a provider. It is suitable for any scenario that requires push-based notification. The pattern defines a *provider* (also known as a *subject* or an *observable*) and zero, one, or more *observers*. Observers register with the provider, and whenever a predefined condition, event, or state change occurs, the provider automatically notifies all observers by calling one of their methods. In this method call, the provider can also provide current state information to observers. In the .NET Framework, the observer design pattern is applied by implementing the generic and interfaces. The generic type parameter represents the type that provides notification information. +The observer design pattern enables a subscriber to register with and receive notifications from a provider. It is suitable for any scenario that requires push-based notification. The pattern defines a *provider* (also known as a *subject* or an *observable*) and zero, one, or more *observers*. Observers register with the provider, and whenever a predefined condition, event, or state change occurs, the provider automatically notifies all observers by calling one of their methods. In this method call, the provider can also provide current state information to observers. In the .NET Framework, the observer design pattern is applied by implementing the generic and interfaces. The generic type parameter represents the type that provides notification information. ## Applying the Pattern The observer design pattern is suitable for distributed push-based notifications, because it supports a clean separation between two different components or application layers, such as a data source (business logic) layer and a user interface (display) layer. The pattern can be implemented whenever a provider uses callbacks to supply its clients with current information. Implementing the pattern requires that you provide the following: -- A provider or subject, which is the object that sends notifications to observers. A provider is a class or structure that implements the interface. The provider must implement a single method, , which is called by observers that wish to receive notifications from the provider. +- A provider or subject, which is the object that sends notifications to observers. A provider is a class or structure that implements the interface. The provider must implement a single method, , which is called by observers that wish to receive notifications from the provider. - An observer, which is an object that receives notifications from a provider. An observer is a class or structure that implements the interface. The observer must implement three methods, all of which are called by the provider: - - , which supplies the observer with new or current information. + - , which supplies the observer with new or current information. - - , which informs the observer that an error has occurred. + - , which informs the observer that an error has occurred. - - , which indicates that the provider has finished sending notifications. + - , which indicates that the provider has finished sending notifications. -- A mechanism that allows the provider to keep track of observers. Typically, the provider uses a container object, such as a object, to hold references to the implementations that have subscribed to notifications. Using a storage container for this purpose enables the provider to handle zero to an unlimited number of observers. The order in which observers receive notifications is not defined; the provider is free to use any method to determine the order. +- A mechanism that allows the provider to keep track of observers. Typically, the provider uses a container object, such as a object, to hold references to the implementations that have subscribed to notifications. Using a storage container for this purpose enables the provider to handle zero to an unlimited number of observers. The order in which observers receive notifications is not defined; the provider is free to use any method to determine the order. -- An implementation that enables the provider to remove observers when notification is complete. Observers receive a reference to the implementation from the method, so they can also call the method to unsubscribe before the provider has finished sending notifications. +- An implementation that enables the provider to remove observers when notification is complete. Observers receive a reference to the implementation from the method, so they can also call the method to unsubscribe before the provider has finished sending notifications. - An object that contains the data that the provider sends to its observers. The type of this object corresponds to the generic type parameter of the and interfaces. Although this object can be the same as the implementation, most commonly it is a separate type. diff --git a/docs/standard/framework-libraries.md b/docs/standard/framework-libraries.md index a59a152f79ecd..2599e0a5eaf44 100644 --- a/docs/standard/framework-libraries.md +++ b/docs/standard/framework-libraries.md @@ -26,15 +26,15 @@ The BCL provides the most foundational types and utility functionality and are t .NET includes a set of primitive types, which are used (to varying degrees) in all programs. These types contain data, such as numbers, strings, bytes and arbitrary objects. The C# language includes keywords for these types. A sample set of these types is listed below, with the matching C# keywords. -* ([object](../csharp/language-reference/keywords/object.md)) - The ultimate base class in the CLR type system. It is the root of the type hierarchy. -* ([short](../csharp/language-reference/keywords/short.md)) - A 16-bit signed integer type. The unsigned also exists. -* ([int](../csharp/language-reference/keywords/int.md)) - A 32-bit signed integer type. The unsigned [UInt32](../csharp/language-reference/keywords/uint.md) also exists. -* ([float](../csharp/language-reference/keywords/float.md)) - A 32-bit floating-point type. -* ([decimal](../csharp/language-reference/keywords/decimal.md)) - A 128-bit decimal type. -* ([byte](../csharp/language-reference/keywords/byte.md)) - An unsigned 8-bit integer that represents a byte of memory. -* ([bool](../csharp/language-reference/keywords/bool.md)) - A boolean type that represents `true` or `false`. -* ([char](../csharp/language-reference/keywords/char.md)) - A 16-bit numeric type that represents a Unicode character. -* ([string](../csharp/language-reference/keywords/string.md)) - Represents a series of characters. Different than a `char[]`, but enables indexing into each individual `char` in the `string`. +* ([object](../csharp/language-reference/keywords/object.md)) - The ultimate base class in the CLR type system. It is the root of the type hierarchy. +* ([short](../csharp/language-reference/keywords/short.md)) - A 16-bit signed integer type. The unsigned also exists. +* ([int](../csharp/language-reference/keywords/int.md)) - A 32-bit signed integer type. The unsigned [UInt32](../csharp/language-reference/keywords/uint.md) also exists. +* ([float](../csharp/language-reference/keywords/float.md)) - A 32-bit floating-point type. +* ([decimal](../csharp/language-reference/keywords/decimal.md)) - A 128-bit decimal type. +* ([byte](../csharp/language-reference/keywords/byte.md)) - An unsigned 8-bit integer that represents a byte of memory. +* ([bool](../csharp/language-reference/keywords/bool.md)) - A boolean type that represents `true` or `false`. +* ([char](../csharp/language-reference/keywords/char.md)) - A 16-bit numeric type that represents a Unicode character. +* ([string](../csharp/language-reference/keywords/string.md)) - Represents a series of characters. Different than a `char[]`, but enables indexing into each individual `char` in the `string`. ## Data Structures diff --git a/docs/standard/garbage-collection/app-domain-resource-monitoring.md b/docs/standard/garbage-collection/app-domain-resource-monitoring.md index b6e4ed64cf6cf..c1960f89f81a5 100644 --- a/docs/standard/garbage-collection/app-domain-resource-monitoring.md +++ b/docs/standard/garbage-collection/app-domain-resource-monitoring.md @@ -35,7 +35,7 @@ Application domain resource monitoring (ARM) enables hosts to monitor CPU and me - The host can enable ARM by requesting the [ICLRAppDomainResourceMonitor](../../../docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-interface.md) hosting interface. Once this interface is successfully obtained, ARM is enabled. -- Managed code can enable ARM by setting the static (`Shared` in Visual Basic) property to `true`. As soon as the property is set, ARM is enabled. +- Managed code can enable ARM by setting the static (`Shared` in Visual Basic) property to `true`. As soon as the property is set, ARM is enabled. - You can enable ARM after startup by listening to ETW events. ARM is enabled and begins raising events for all application domains when you enable the public provider `Microsoft-Windows-DotNETRuntime` by using the `AppDomainResourceManagementKeyword` keyword. To correlate data with application domains and threads, you must also enable the `Microsoft-Windows-DotNETRuntimeRundown` provider with the `ThreadingKeyword` keyword. @@ -44,7 +44,7 @@ Application domain resource monitoring (ARM) enables hosts to monitor CPU and me - **Total processor time for an application domain, in seconds**: This is calculated by adding up the thread times reported by the operating system for all threads that spent time executing in the application domain during its lifetime. Blocked or sleeping threads do not use processor time. When a thread calls into native code, the time that the thread spends in native code is included in the count for the application domain where the call was made. - - Managed API: property. + - Managed API: property. - Hosting API: [ICLRAppDomainResourceMonitor::GetCurrentCpuTime](../../../docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentcputime-method.md) method. @@ -52,15 +52,15 @@ Application domain resource monitoring (ARM) enables hosts to monitor CPU and me - **Total managed allocations made by an application domain during its lifetime, in bytes**: Total allocations do not always reflect memory use by an application domain, because the allocated objects might be short-lived. However, if an application allocates and frees huge numbers of objects, the cost of the allocations could be significant. - - Managed API: property. + - Managed API: property. - Hosting API: [ICLRAppDomainResourceMonitor::GetCurrentAllocated](../../../docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentallocated-method.md) method. - ETW events: `AppDomainMemAllocated` event, `Allocated` field. -- **Managed memory, in bytes, that is referenced by an application domain and that survived the most recent full, blocking collection**: This number is accurate only after a full, blocking collection. (This is in contrast to concurrent collections, which occur in the background and do not block the application.) For example, the method overload causes a full, blocking collection. +- **Managed memory, in bytes, that is referenced by an application domain and that survived the most recent full, blocking collection**: This number is accurate only after a full, blocking collection. (This is in contrast to concurrent collections, which occur in the background and do not block the application.) For example, the method overload causes a full, blocking collection. - - Managed API: property. + - Managed API: property. - Hosting API: [ICLRAppDomainResourceMonitor::GetCurrentSurvived](../../../docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentsurvived-method.md) method, `pAppDomainBytesSurvived` parameter. @@ -68,7 +68,7 @@ Application domain resource monitoring (ARM) enables hosts to monitor CPU and me - **Total managed memory, in bytes, that is referenced by the process and that survived the most recent full, blocking collection**: The survived memory for individual application domains can be compared to this number. - - Managed API: property. + - Managed API: property. - Hosting API: [ICLRAppDomainResourceMonitor::GetCurrentSurvived](../../../docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-getcurrentsurvived-method.md) method, `pTotalBytesSurvived` parameter. @@ -78,15 +78,15 @@ Application domain resource monitoring (ARM) enables hosts to monitor CPU and me To determine when counts of survived memory are accurate, you need to know when a full, blocking collection has just occurred. The method for doing this depends on the API you use to examine ARM statistics. #### Managed API - If you use the properties of the class, you can use the method to register for notification of full collections. The threshold you use is not important, because you are waiting for the completion of a collection rather than the approach of a collection. You can then call the method, which blocks until a full collection has completed. You can create a thread that calls the method in a loop and does any necessary analysis whenever the method returns. + If you use the properties of the class, you can use the method to register for notification of full collections. The threshold you use is not important, because you are waiting for the completion of a collection rather than the approach of a collection. You can then call the method, which blocks until a full collection has completed. You can create a thread that calls the method in a loop and does any necessary analysis whenever the method returns. - Alternatively, you can call the method periodically to see if the count of generation 2 collections has increased. Depending on the polling frequency, this technique might not provide as accurate an indication of the occurrence of a full collection. + Alternatively, you can call the method periodically to see if the count of generation 2 collections has increased. Depending on the polling frequency, this technique might not provide as accurate an indication of the occurrence of a full collection. #### Hosting API If you use the unmanaged hosting API, your host must pass the CLR an implementation of the [IHostGCManager](../../../docs/framework/unmanaged-api/hosting/ihostgcmanager-interface.md) interface. The CLR calls the [IHostGCManager::SuspensionEnding](../../../docs/framework/unmanaged-api/hosting/ihostgcmanager-suspensionending-method.md) method when it resumes execution of threads that have been suspended while a collection occurs. The CLR passes the generation of the completed collection as a parameter of the method, so the host can determine whether the collection was full or partial. Your implementation of the [IHostGCManager::SuspensionEnding](../../../docs/framework/unmanaged-api/hosting/ihostgcmanager-suspensionending-method.md) method can query for survived memory, to ensure that the counts are retrieved as soon as they are updated. ## See Also - + [ICLRAppDomainResourceMonitor Interface](../../../docs/framework/unmanaged-api/hosting/iclrappdomainresourcemonitor-interface.md) [\](../../../docs/framework/configure-apps/file-schema/runtime/appdomainresourcemonitoring-element.md) [CLR ETW Events](../../../docs/framework/performance/clr-etw-events.md) diff --git a/docs/standard/garbage-collection/fundamentals.md b/docs/standard/garbage-collection/fundamentals.md index 0f46a2197ab73..b7b0da1407805 100644 --- a/docs/standard/garbage-collection/fundamentals.md +++ b/docs/standard/garbage-collection/fundamentals.md @@ -90,7 +90,7 @@ manager: "wpickett" - The memory that is used by allocated objects on the managed heap surpasses an acceptable threshold. This threshold is continuously adjusted as the process runs. -- The method is called. In almost all cases, you do not have to call this method, because the garbage collector runs continuously. This method is primarily used for unique situations and testing. +- The method is called. In almost all cases, you do not have to call this method, because the garbage collector runs continuously. This method is primarily used for unique situations and testing. [Back to top](#top) @@ -170,7 +170,7 @@ manager: "wpickett" Because generation 2 collections can occupy multiple segments, objects that are promoted into generation 2 can be moved into an older segment. Both generation 1 and generation 2 survivors can be moved to a different segment, because they are promoted to generation 2. - Ordinarily, the large object heap is not compacted, because copying large objects imposes a performance penalty. However, starting with the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)], you can use the property to compact the large object heap on demand. + Ordinarily, the large object heap is not compacted, because copying large objects imposes a performance penalty. However, starting with the [!INCLUDE[net_v451](../../../includes/net-v451-md.md)], you can use the property to compact the large object heap on demand. The garbage collector uses the following information to determine whether objects are live: diff --git a/docs/standard/garbage-collection/implementing-dispose.md b/docs/standard/garbage-collection/implementing-dispose.md index 68a8b5481ae22..3b8f3f16d6f72 100644 --- a/docs/standard/garbage-collection/implementing-dispose.md +++ b/docs/standard/garbage-collection/implementing-dispose.md @@ -26,23 +26,23 @@ The pattern for disposing an object, referred to as a [dispose pattern](../../.. The dispose pattern has two variations: -* You wrap each unmanaged resource that a type uses in a safe handle (that is, in a class derived from ). In this case, you implement the interface and an additional `Dispose(Boolean)` method. This is the recommended variation and doesn't require overriding the method. +* You wrap each unmanaged resource that a type uses in a safe handle (that is, in a class derived from ). In this case, you implement the interface and an additional `Dispose(Boolean)` method. This is the recommended variation and doesn't require overriding the method. > [!NOTE] - > The namespace provides a set of classes derived from , which are listed in the [Using safe handles](#SafeHandles) section. If you can't find a class that is suitable for releasing your unmanaged resource, you can implement your own subclass of . + > The namespace provides a set of classes derived from , which are listed in the [Using safe handles](#SafeHandles) section. If you can't find a class that is suitable for releasing your unmanaged resource, you can implement your own subclass of . -* You implement the interface and an additional `Dispose(Boolean)` method, and you also override the method. You must override to ensure that unmanaged resources are disposed of if your implementation is not called by a consumer of your type. If you use the recommended technique discussed in the previous bullet, the class does this on your behalf. +* You implement the interface and an additional `Dispose(Boolean)` method, and you also override the method. You must override to ensure that unmanaged resources are disposed of if your implementation is not called by a consumer of your type. If you use the recommended technique discussed in the previous bullet, the class does this on your behalf. To help ensure that resources are always cleaned up appropriately, a method should be callable multiple times without throwing an exception. -The code example provided for the method shows how aggressive garbage collection can cause a finalizer to run while a member of the reclaimed object is still executing. It is a good idea to call the method at the end of a lengthy method. +The code example provided for the method shows how aggressive garbage collection can cause a finalizer to run while a member of the reclaimed object is still executing. It is a good idea to call the method at the end of a lengthy method. ## Dispose() and Dispose(Boolean) The interface requires the implementation of a single parameterless method, . However, the dispose pattern requires two `Dispose` methods to be implemented: -* A public non-virtual (`NonInheritable` in Visual Basic) implementation that has no parameters. +* A public non-virtual (`NonInheritable` in Visual Basic) implementation that has no parameters. * A protected virtual (`Overridable` in Visual Basic) `Dispose` method whose signature is: @@ -56,7 +56,7 @@ Because the public, non-virtual (`NonInheritable` in Visual Basic), parameterles [!code-csharp[Conceptual.Disposable#7](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.disposable/cs/dispose1.cs#7)] [!code-vb[Conceptual.Disposable#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.disposable/vb/dispose1.vb#7)] -The `Dispose` method performs all object cleanup, so the garbage collector no longer needs to call the objects' override. Therefore, the call to the method prevents the garbage collector from running the finalizer. If the type has no finalizer, the call to has no effect. Note that the actual work of releasing unmanaged resources is performed by the second overload of the `Dispose` method. +The `Dispose` method performs all object cleanup, so the garbage collector no longer needs to call the objects' override. Therefore, the call to the method prevents the garbage collector from running the finalizer. If the type has no finalizer, the call to has no effect. Note that the actual work of releasing unmanaged resources is performed by the second overload of the `Dispose` method. ### The Dispose(Boolean) overload @@ -68,7 +68,7 @@ The body of the method consists of two blocks of code: * A conditional block that frees managed resources. This block executes if the value of `disposing` is `true`. The managed resources that it frees can include: - **Managed objects that implement .** The conditional block can be used to call their implementation. If you have used a safe handle to wrap your unmanaged resource, you should call the implementation here. + **Managed objects that implement .** The conditional block can be used to call their implementation. If you have used a safe handle to wrap your unmanaged resource, you should call the implementation here. **Managed objects that consume large amounts of memory or consume scarce resources.** Freeing these objects explicitly in the `Dispose` method releases them faster than if they were reclaimed non-deterministically by the garbage collector. @@ -85,7 +85,7 @@ If you implement the dispose pattern for a base class, you must provide the foll * A `Dispose(Boolean)` method that performs the actual work of releasing resources. -* Either a class derived from that wraps your unmanaged resource (recommended), or an override to the method. The class provides a finalizer that frees you from having to code one. +* Either a class derived from that wraps your unmanaged resource (recommended), or an override to the method. The class provides a finalizer that frees you from having to code one. Here's the general pattern for implementing the dispose pattern for a base class that uses a safe handle. @@ -95,21 +95,21 @@ Here's the general pattern for implementing the dispose pattern for a base class > [!NOTE] > The previous example uses a object to illustrate the pattern; any object derived from could be used instead. Note that the example does not properly instantiate its object. -Here's the general pattern for implementing the dispose pattern for a base class that overrides . +Here's the general pattern for implementing the dispose pattern for a base class that overrides . [!code-csharp[System.IDisposable#5](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.idisposable/cs/base2.cs#5)] [!code-vb[System.IDisposable#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.idisposable/vb/base2.vb#5)] > [!NOTE] -> In C#, you override by defining a [destructor](~/docs/csharp/programming-guide/classes-and-structs/destructors.md). +> In C#, you override by defining a [destructor](~/docs/csharp/programming-guide/classes-and-structs/destructors.md). ## Implementing the dispose pattern for a derived class -A class derived from a class that implements the interface shouldn't implement , because the base class implementation of is inherited by its derived classes. Instead, to implement the dispose pattern for a derived class, you provide the following: +A class derived from a class that implements the interface shouldn't implement , because the base class implementation of is inherited by its derived classes. Instead, to implement the dispose pattern for a derived class, you provide the following: * A `protected``Dispose(Boolean)` method that overrides the base class method and performs the actual work of releasing the resources of the derived class. This method should also call the `Dispose(Boolean)` method of the base class and pass it a value of `true` for the *disposing* argument. -* Either a class derived from that wraps your unmanaged resource (recommended), or an override to the method. The class provides a finalizer that frees you from having to code one. If you do provide a finalizer, it should call the `Dispose(Boolean)` overload with a *disposing* argument of `false`. +* Either a class derived from that wraps your unmanaged resource (recommended), or an override to the method. The class provides a finalizer that frees you from having to code one. If you do provide a finalizer, it should call the `Dispose(Boolean)` overload with a *disposing* argument of `false`. Here's the general pattern for implementing the dispose pattern for a derived class that uses a safe handle: @@ -119,20 +119,20 @@ Here's the general pattern for implementing the dispose pattern for a derived cl > [!NOTE] > The previous example uses a object to illustrate the pattern; any object derived from could be used instead. Note that the example does not properly instantiate its object. -Here's the general pattern for implementing the dispose pattern for a derived class that overrides : +Here's the general pattern for implementing the dispose pattern for a derived class that overrides : [!code-csharp[System.IDisposable#6](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.idisposable/cs/derived2.cs#6)] [!code-vb[System.IDisposable#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.idisposable/vb/derived2.vb#6)] > [!NOTE] -> In C#, you override by defining a [destructor](~/docs/csharp/programming-guide/classes-and-structs/destructors.md). +> In C#, you override by defining a [destructor](~/docs/csharp/programming-guide/classes-and-structs/destructors.md). ## Using safe handles -Writing code for an object's finalizer is a complex task that can cause problems if not done correctly. Therefore, we recommend that you construct objects instead of implementing a finalizer. +Writing code for an object's finalizer is a complex task that can cause problems if not done correctly. Therefore, we recommend that you construct objects instead of implementing a finalizer. -Classes derived from the class simplify object lifetime issues by assigning and releasing handles without interruption. They contain a critical finalizer that is guaranteed to run while an application domain is unloading. For more information about the advantages of using a safe handle, see . The following derived classes in the namespace provide safe handles: +Classes derived from the class simplify object lifetime issues by assigning and releasing handles without interruption. They contain a critical finalizer that is guaranteed to run while an application domain is unloading. For more information about the advantages of using a safe handle, see . The following derived classes in the namespace provide safe handles: * The , , and class, for files, memory mapped files, and pipes. @@ -164,9 +164,9 @@ The following example illustrates the dispose pattern for a derived class, `Disp - + - - + + [How to: Define and Consume Classes and Structs (C++/CLI)](/cpp/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli) [Dispose Pattern](../../../docs/standard/design-guidelines/dispose-pattern.md) diff --git a/docs/standard/garbage-collection/index.md b/docs/standard/garbage-collection/index.md index ac75ec10eb6ac..426737e8a1a9e 100644 --- a/docs/standard/garbage-collection/index.md +++ b/docs/standard/garbage-collection/index.md @@ -47,21 +47,21 @@ manager: "wpickett" |[Weak References](../../../docs/standard/garbage-collection/weak-references.md)|Describes features that permit the garbage collector to collect an object while still allowing the application to access that object.| ## Reference - + - + - + - + - + - + - + - + ## See Also [Cleaning Up Unmanaged Resources](../../../docs/standard/garbage-collection/unmanaged.md) diff --git a/docs/standard/garbage-collection/induced.md b/docs/standard/garbage-collection/induced.md index 7ec77171a7927..b57000734e800 100644 --- a/docs/standard/garbage-collection/induced.md +++ b/docs/standard/garbage-collection/induced.md @@ -17,21 +17,21 @@ ms.author: "ronpet" manager: "wpickett" --- # Induced Collections -In most cases, the garbage collector can determine the best time to perform a collection, and you should let it run independently. There are rare situations when a forced collection might improve your application's performance. In these cases, you can induce garbage collection by using the method to force a garbage collection. +In most cases, the garbage collector can determine the best time to perform a collection, and you should let it run independently. There are rare situations when a forced collection might improve your application's performance. In these cases, you can induce garbage collection by using the method to force a garbage collection. - Use the method when there is a significant reduction in the amount of memory being used at a specific point in your application's code. For example, if your application uses a complex dialog box that has several controls, calling when the dialog box is closed could improve performance by immediately reclaiming the memory used by the dialog box. Be sure that your application is not inducing garbage collection too frequently, because that can decrease performance if the garbage collector is trying to reclaim objects at non-optimal times. You can supply a enumeration value to the method to collect only when collection would be productive, as discussed in the next section. + Use the method when there is a significant reduction in the amount of memory being used at a specific point in your application's code. For example, if your application uses a complex dialog box that has several controls, calling when the dialog box is closed could improve performance by immediately reclaiming the memory used by the dialog box. Be sure that your application is not inducing garbage collection too frequently, because that can decrease performance if the garbage collector is trying to reclaim objects at non-optimal times. You can supply a enumeration value to the method to collect only when collection would be productive, as discussed in the next section. ## GC collection mode - You can use one of the method overloads that includes a value to specify the behavior for a forced collection as follows. + You can use one of the method overloads that includes a value to specify the behavior for a forced collection as follows. |`GCCollectionMode` value|Description| |------------------------------|-----------------| ||Uses the default garbage collection setting for the running version of .NET.| -||Forces garbage collection to occur immediately. This is equivalent to calling the overload. It results in a full blocking collection of all generations.

You can also compact the large object heap by setting the property to before forcing an immediate full blocking garbage collection.| +||Forces garbage collection to occur immediately. This is equivalent to calling the overload. It results in a full blocking collection of all generations.

You can also compact the large object heap by setting the property to before forcing an immediate full blocking garbage collection.| ||Enables the garbage collector to determine whether the current time is optimal to reclaim objects.

The garbage collector could determine that a collection would not be productive enough to be justified, in which case it will return without reclaiming objects.| ## Background or blocking collections - You can call the method overload to specify whether an induced collection is blocking or not. The type of collection performed depends on a combination of the method's `mode` and `blocking` parameters. `mode` is a member of the enumeration, and `blocking` is a value. The following table summarizes the interaction of the `mode` and `blocking` arguments. + You can call the method overload to specify whether an induced collection is blocking or not. The type of collection performed depends on a combination of the method's `mode` and `blocking` parameters. `mode` is a member of the enumeration, and `blocking` is a value. The following table summarizes the interaction of the `mode` and `blocking` arguments. |`mode`|`blocking` = `true`|`blocking` = `false`| |------------|--------------------------|---------------------------| diff --git a/docs/standard/garbage-collection/latency.md b/docs/standard/garbage-collection/latency.md index 3ab7d62cbbd9f..72f4f0775abaf 100644 --- a/docs/standard/garbage-collection/latency.md +++ b/docs/standard/garbage-collection/latency.md @@ -18,9 +18,9 @@ ms.author: "ronpet" manager: "wpickett" --- # Latency Modes -To reclaim objects, the garbage collector must stop all the executing threads in an application. In some situations, such as when an application retrieves data or displays content, a full garbage collection can occur at a critical time and impede performance. You can adjust the intrusiveness of the garbage collector by setting the property to one of the values. +To reclaim objects, the garbage collector must stop all the executing threads in an application. In some situations, such as when an application retrieves data or displays content, a full garbage collection can occur at a critical time and impede performance. You can adjust the intrusiveness of the garbage collector by setting the property to one of the values. - Latency refers to the time that the garbage collector intrudes in your application. During low latency periods, the garbage collector is more conservative and less intrusive in reclaiming objects. The enumeration provides two low latency settings: + Latency refers to the time that the garbage collector intrudes in your application. During low latency periods, the garbage collector is more conservative and less intrusive in reclaiming objects. The enumeration provides two low latency settings: - suppresses generation 2 collections and performs only generation 0 and 1 collections. It can be used only for short periods of time. Over longer periods, if the system is under memory pressure, the garbage collector will trigger a collection, which can briefly pause the application and disrupt a time-critical operation. This setting is available only for workstation garbage collection. @@ -30,7 +30,7 @@ To reclaim objects, the garbage collector must stop all the executing threads in - The system receives a low memory notification from the operating system. -- Your application code induces a collection by calling the method and specifying 2 for the `generation` parameter. +- Your application code induces a collection by calling the method and specifying 2 for the `generation` parameter. The following table lists the application scenarios for using the values. @@ -54,9 +54,9 @@ To reclaim objects, the garbage collector must stop all the executing threads in - Wrap the low latency code in constrained execution regions (for more information, see [Constrained Execution Regions](../../../docs/framework/performance/constrained-execution-regions.md)). -- You can force generation 2 collections during a low latency period by calling the method. +- You can force generation 2 collections during a low latency period by calling the method. ## See Also - + [Induced Collections](../../../docs/standard/garbage-collection/induced.md) [Garbage Collection](../../../docs/standard/garbage-collection/index.md) diff --git a/docs/standard/garbage-collection/performance.md b/docs/standard/garbage-collection/performance.md index 1b88852f15bbc..dad735cb28760 100644 --- a/docs/standard/garbage-collection/performance.md +++ b/docs/standard/garbage-collection/performance.md @@ -445,7 +445,7 @@ manager: "wpickett" … ``` - Using an integer instead of a string for an ID can be more efficient. If the same string is being repeated thousands of times, consider string interning. For more information about string interning, see the reference topic for the method. + Using an integer instead of a string for an ID can be more efficient. If the same string is being repeated thousands of times, consider string interning. For more information about string interning, see the reference topic for the method. ##### To determine references to objects @@ -491,7 +491,7 @@ manager: "wpickett" GC.Collect(); ``` - If the test resolves the problem, this means that the garbage collector was not reclaiming objects, because the finalizers for those objects had been suspended. The method enables the finalizers to complete their tasks, and fixes the problem. + If the test resolves the problem, this means that the garbage collector was not reclaiming objects, because the finalizers for those objects had been suspended. The method enables the finalizers to complete their tasks, and fixes the problem. ##### To determine whether there are objects waiting to be finalized diff --git a/docs/standard/garbage-collection/unmanaged.md b/docs/standard/garbage-collection/unmanaged.md index 150afa899652e..b6a9f94c0cb67 100644 --- a/docs/standard/garbage-collection/unmanaged.md +++ b/docs/standard/garbage-collection/unmanaged.md @@ -28,17 +28,17 @@ For the majority of the objects that your app creates, you can rely on .NET's ga If your types use unmanaged resources, you should do the following: -- Implement the [dispose pattern](../../../docs/standard/design-guidelines/dispose-pattern.md). This requires that you provide an implementation to enable the deterministic release of unmanaged resources. A consumer of your type calls when the object (and the resources it uses) is no longer needed. The method immediately releases the unmanaged resources. +- Implement the [dispose pattern](../../../docs/standard/design-guidelines/dispose-pattern.md). This requires that you provide an implementation to enable the deterministic release of unmanaged resources. A consumer of your type calls when the object (and the resources it uses) is no longer needed. The method immediately releases the unmanaged resources. - Provide for your unmanaged resources to be released in the event that a consumer of your type forgets to call . There are two ways to do this: - - Use a safe handle to wrap your unmanaged resource. This is the recommended technique. Safe handles are derived from the class and include a robust method. When you use a safe handle, you simply implement the interface and call your safe handle's method in your implementation. The safe handle's finalizer is called automatically by the garbage collector if its method is not called. + - Use a safe handle to wrap your unmanaged resource. This is the recommended technique. Safe handles are derived from the class and include a robust method. When you use a safe handle, you simply implement the interface and call your safe handle's method in your implementation. The safe handle's finalizer is called automatically by the garbage collector if its method is not called. —or— - - Override the method. Finalization enables the non-deterministic release of unmanaged resources when the consumer of a type fails to call to dispose of them deterministically. However, because object finalization can be a complex and error-prone operation, we recommend that you use a safe handle instead of providing your own finalizer. + - Override the method. Finalization enables the non-deterministic release of unmanaged resources when the consumer of a type fails to call to dispose of them deterministically. However, because object finalization can be a complex and error-prone operation, we recommend that you use a safe handle instead of providing your own finalizer. - Consumers of your type can then call your implementation directly to free memory used by unmanaged resources. When you properly implement a method, either your safe handle's method or your own override of the method becomes a safeguard to clean up resources in the event that the method is not called. + Consumers of your type can then call your implementation directly to free memory used by unmanaged resources. When you properly implement a method, either your safe handle's method or your own override of the method becomes a safeguard to clean up resources in the event that the method is not called. ## In This Section [Implementing a Dispose Method](../../../docs/standard/garbage-collection/implementing-dispose.md) @@ -48,11 +48,11 @@ For the majority of the objects that your app creates, you can rely on .NET's ga Describes how consumers of a type ensure that its implementation is called. We recommend using the C# `using` statement or the Visual Basic `Using` statement to do this. ## Reference - + Defines the method for releasing unmanaged resources. - + Provides for object finalization if unmanaged resources are not released by the method. - + Suppresses finalization. This method is customarily called from a `Dispose` method to prevent a finalizer from executing. diff --git a/docs/standard/garbage-collection/using-objects.md b/docs/standard/garbage-collection/using-objects.md index 1ed280643c3b0..1daf7b525cbd5 100644 --- a/docs/standard/garbage-collection/using-objects.md +++ b/docs/standard/garbage-collection/using-objects.md @@ -21,7 +21,7 @@ manager: "wpickett" # Using objects that implement IDisposable -The common language runtime's garbage collector reclaims the memory used by managed objects, but types that use unmanaged resources implement the interface to allow the memory allocated to these unmanaged resources to be reclaimed. When you finish using an object that implements , you should call the object's implementation. You can do this in one of two ways: +The common language runtime's garbage collector reclaims the memory used by managed objects, but types that use unmanaged resources implement the interface to allow the memory allocated to these unmanaged resources to be reclaimed. When you finish using an object that implements , you should call the object's implementation. You can do this in one of two ways: * With the C# `using` statement or the Visual Basic `Using` statement. @@ -31,12 +31,12 @@ The common language runtime's garbage collector reclaims the memory used by mana The `using` statement in C# and the `Using` statement in Visual Basic simplify the code that you must write to create and clean up an object. The `using` statement obtains one or more resources, executes the statements that you specify, and automatically disposes of the object. However, the `using` statement is useful only for objects that are used within the scope of the method in which they are constructed. -The following example uses the `using` statement to create and release a object. +The following example uses the `using` statement to create and release a object. [!code-csharp[Conceptual.Disposable#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.disposable/cs/using1.cs#1)] [!code-vb[Conceptual.Disposable#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.disposable/vb/using1.vb#1)] -Note that although the class implements the interface, which indicates that it uses an unmanaged resource, the example doesn't explicitly call the method. When the C# or Visual Basic compiler encounters the `using` statement, it emits intermediate language (IL) that is equivalent to the following code that explicitly contains a `try/finally` block. +Note that although the class implements the interface, which indicates that it uses an unmanaged resource, the example doesn't explicitly call the method. When the C# or Visual Basic compiler encounters the `using` statement, it emits intermediate language (IL) that is equivalent to the following code that explicitly contains a `try/finally` block. [!code-csharp[Conceptual.Disposable#3](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.disposable/cs/using3.cs#3)] [!code-vb[Conceptual.Disposable#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.disposable/vb/using3.vb#3)] diff --git a/docs/standard/generics/collections.md b/docs/standard/generics/collections.md index a07b0d1872af2..b9b9bc4c6dc62 100644 --- a/docs/standard/generics/collections.md +++ b/docs/standard/generics/collections.md @@ -50,8 +50,8 @@ This topic provides an overview of the generic collection classes and other gene [!code-vb[Conceptual.Generics.Overview#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.generics.overview/vb/source2.vb#7)] ## See Also - - + + [Generics](../../../docs/standard/generics/index.md) [Generic Delegates for Manipulating Arrays and Lists](../../../docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md) [Generic Interfaces](../../../docs/standard/generics/interfaces.md) diff --git a/docs/standard/generics/covariance-and-contravariance.md b/docs/standard/generics/covariance-and-contravariance.md index 278b79e16ad1b..01f7098c33baa 100644 --- a/docs/standard/generics/covariance-and-contravariance.md +++ b/docs/standard/generics/covariance-and-contravariance.md @@ -93,7 +93,7 @@ manager: "wpickett" ## Generic Interfaces with Contravariant Generic Type Parameters Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], several generic interfaces have contravariant type parameters; for example: , , and . These interfaces have only contravariant type parameters, so the type parameters are used only as parameter types in the members of the interfaces. - The following example illustrates contravariant type parameters. The example defines an abstract (`MustInherit` in Visual Basic) `Shape` class with an `Area` property. The example also defines a `ShapeAreaComparer` class that implements `IComparer` (`IComparer(Of Shape)` in Visual Basic). The implementation of the method is based on the value of the `Area` property, so `ShapeAreaComparer` can be used to sort `Shape` objects by area. + The following example illustrates contravariant type parameters. The example defines an abstract (`MustInherit` in Visual Basic) `Shape` class with an `Area` property. The example also defines a `ShapeAreaComparer` class that implements `IComparer` (`IComparer(Of Shape)` in Visual Basic). The implementation of the method is based on the value of the `Area` property, so `ShapeAreaComparer` can be used to sort `Shape` objects by area. The `Circle` class inherits `Shape` and overrides `Area`. The example creates a of `Circle` objects, using a constructor that takes an `IComparer` (`IComparer(Of Circle)` in Visual Basic). However, instead of passing an `IComparer`, the example passes a `ShapeAreaComparer` object, which implements `IComparer`. The example can pass a comparer of a less derived type (`Shape`) when the code calls for a comparer of a more derived type (`Circle`), because the type parameter of the generic interface is contravariant. diff --git a/docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md b/docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md index d5298f3d37c24..2595ffebcc54c 100644 --- a/docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md +++ b/docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md @@ -25,27 +25,27 @@ manager: "wpickett" This topic provides an overview of generic delegates for conversions, search predicates, and actions to be taken on elements of an array or collection. ## Generic Delegates for Manipulating Arrays and Lists - The generic delegate represents a method that performs some action on an element of the specified type. You can create a method that performs the desired action on the element, create an instance of the delegate to represent that method, and then pass the array and the delegate to the static generic method. The method is called for every element of the array. + The generic delegate represents a method that performs some action on an element of the specified type. You can create a method that performs the desired action on the element, create an instance of the delegate to represent that method, and then pass the array and the delegate to the static generic method. The method is called for every element of the array. The generic class also provides a method that uses the delegate. This method is not generic. > [!NOTE] -> This makes an interesting point about generic types and methods. The method must be static (`Shared` in Visual Basic) and generic because is not a generic type; the only reason you can specify a type for to operate on is that the method has its own type parameter list. By contrast, the nongeneric method belongs to the generic class , so it simply uses the type parameter of its class. The class is strongly typed, so the method can be an instance method. +> This makes an interesting point about generic types and methods. The method must be static (`Shared` in Visual Basic) and generic because is not a generic type; the only reason you can specify a type for to operate on is that the method has its own type parameter list. By contrast, the nongeneric method belongs to the generic class , so it simply uses the type parameter of its class. The class is strongly typed, so the method can be an instance method. The generic delegate represents a method that determines whether a particular element meets criteria you define. You can use it with the following static generic methods of to search for an element or a set of elements: , , , , , , and . also works with the corresponding nongeneric instance methods of the generic class. - The generic delegate allows you to provide a sort order for array or list elements that do not have a native sort order, or to override the native sort order. Create a method that performs the comparison, create an instance of the delegate to represent your method, and then pass the array and the delegate to the static generic method. The generic class provides a corresponding instance method overload, . + The generic delegate allows you to provide a sort order for array or list elements that do not have a native sort order, or to override the native sort order. Create a method that performs the comparison, create an instance of the delegate to represent your method, and then pass the array and the delegate to the static generic method. The generic class provides a corresponding instance method overload, . - The generic delegate allows you to define a conversion between two types, and to convert an array of one type into an array of the other, or to convert a list of one type to a list of the other. Create a method that converts the elements of the existing list to a new type, create a delegate instance to represent the method, and use the generic static method to produce an array of the new type from the original array, or the generic instance method to produce a list of the new type from the original list. + The generic delegate allows you to define a conversion between two types, and to convert an array of one type into an array of the other, or to convert a list of one type to a list of the other. Create a method that converts the elements of the existing list to a new type, create a delegate instance to represent the method, and use the generic static method to produce an array of the new type from the original array, or the generic instance method to produce a list of the new type from the original list. ### Chaining Delegates Many of the methods that use these delegates return an array or list, which can be passed to another method. For example, if you want to select certain elements of an array, convert those elements to a new type, and save them in a new array, you can pass the array returned by the generic method to the generic method. If the new element type lacks a natural sort order, you can pass the array returned by the generic method to the generic method. ## See Also - - + + [Generics](../../../docs/standard/generics/index.md) [Generic Collections in the .NET Framework](../../../docs/standard/generics/collections.md) [Generic Interfaces](../../../docs/standard/generics/interfaces.md) diff --git a/docs/standard/generics/index.md b/docs/standard/generics/index.md index a961047600789..439b334499491 100644 --- a/docs/standard/generics/index.md +++ b/docs/standard/generics/index.md @@ -68,9 +68,9 @@ manager: "wpickett" ### Generics terminology The following terms are used to discuss generics in the .NET Framework: -- A *generic type definition* is a class, structure, or interface declaration that functions as a template, with placeholders for the types that it can contain or use. For example, the class can contain two types: keys and values. Because a generic type definition is only a template, you cannot create instances of a class, structure, or interface that is a generic type definition. +- A *generic type definition* is a class, structure, or interface declaration that functions as a template, with placeholders for the types that it can contain or use. For example, the class can contain two types: keys and values. Because a generic type definition is only a template, you cannot create instances of a class, structure, or interface that is a generic type definition. -- *Generic type parameters*, or *type parameters*, are the placeholders in a generic type or method definition. The generic type has two type parameters, `TKey` and `TValue`, that represent the types of its keys and values. +- *Generic type parameters*, or *type parameters*, are the placeholders in a generic type or method definition. The generic type has two type parameters, `TKey` and `TValue`, that represent the types of its keys and values. - A *constructed generic type*, or *constructed type*, is the result of specifying types for the generic type parameters of a generic type definition. @@ -80,7 +80,7 @@ manager: "wpickett" - *Covariance* and *contravariance* of generic type parameters enable you to use constructed generic types whose type arguments are more derived (covariance) or less derived (contravariance) than a target constructed type. Covariance and contravariance are collectively referred to as *variance*. For more information, see [Covariance and Contravariance](../../../docs/standard/generics/covariance-and-contravariance.md). -- *Constraints* are limits placed on generic type parameters. For example, you might limit a type parameter to types that implement the generic interface, to ensure that instances of the type can be ordered. You can also constrain type parameters to types that have a particular base class, that have a default constructor, or that are reference types or value types. Users of the generic type cannot substitute type arguments that do not satisfy the constraints. +- *Constraints* are limits placed on generic type parameters. For example, you might limit a type parameter to types that implement the generic interface, to ensure that instances of the type can be ordered. You can also constrain type parameters to types that have a particular base class, that have a default constructor, or that are reference types or value types. Users of the generic type cannot substitute type arguments that do not satisfy the constraints. - A *generic method definition* is a method with two parameter lists: a list of generic type parameters and a list of formal parameters. Type parameters can appear as the return type or as the types of the formal parameters, as the following code shows. @@ -177,6 +177,6 @@ manager: "wpickett" - + [Back to top](#top) diff --git a/docs/standard/generics/interfaces.md b/docs/standard/generics/interfaces.md index b0a2ee0f6ed5f..ec4e0d554d247 100644 --- a/docs/standard/generics/interfaces.md +++ b/docs/standard/generics/interfaces.md @@ -29,11 +29,11 @@ This topic provides an overview of generic interfaces that provide common functi > Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], the type parameters of several generic interfaces are marked covariant or contravariant, providing greater flexibility in assigning and using types that implement these interfaces. See [Covariance and Contravariance](../../../docs/standard/generics/covariance-and-contravariance.md). ### Equality and Ordering Comparisons - In the namespace, the and generic interfaces, like their nongeneric counterparts, define methods for ordering comparisons and equality comparisons, respectively. Types implement these interfaces to provide the ability to perform such comparisons. + In the namespace, the and generic interfaces, like their nongeneric counterparts, define methods for ordering comparisons and equality comparisons, respectively. Types implement these interfaces to provide the ability to perform such comparisons. - In the namespace, the and generic interfaces offer a way to define an ordering or equality comparison for types that do not implement the or generic interface, and they provide a way to redefine those relationships for types that do. These interfaces are used by methods and constructors of many of the generic collection classes. For example, you can pass a generic object to the constructor of the class to specify a sort order for a type that does not implement generic . There are overloads of the generic static method and the instance method for sorting arrays and lists using generic implementations. + In the namespace, the and generic interfaces offer a way to define an ordering or equality comparison for types that do not implement the or generic interface, and they provide a way to redefine those relationships for types that do. These interfaces are used by methods and constructors of many of the generic collection classes. For example, you can pass a generic object to the constructor of the class to specify a sort order for a type that does not implement generic . There are overloads of the generic static method and the instance method for sorting arrays and lists using generic implementations. - The and generic classes provide base classes for implementations of the and generic interfaces, and also provide default ordering and equality comparisons through their respective and properties. + The and generic classes provide base classes for implementations of the and generic interfaces, and also provide default ordering and equality comparisons through their respective and properties. ### Collection Functionality The generic interface is the basic interface for generic collection types. It provides basic functionality for adding, removing, copying, and enumerating elements. inherits from both generic and nongeneric . @@ -45,8 +45,8 @@ This topic provides an overview of generic interfaces that provide common functi The generic interface provides a generic enumerator structure. The generic interface implemented by generic enumerators inherits the nongeneric interface; the and members, which do not depend on the type parameter `T`, appear only on the nongeneric interface. This means that any consumer of the nongeneric interface can also consume the generic interface. ## See Also - - + + [Generics](../../../docs/standard/generics/index.md) [Generic Collections in the .NET Framework](../../../docs/standard/generics/collections.md) [Generic Delegates for Manipulating Arrays and Lists](../../../docs/standard/generics/delegates-for-manipulating-arrays-and-lists.md) diff --git a/docs/standard/globalization-localization/best-practices-for-developing-world-ready-apps.md b/docs/standard/globalization-localization/best-practices-for-developing-world-ready-apps.md index 9434de63a0af7..6a68fce1db34e 100644 --- a/docs/standard/globalization-localization/best-practices-for-developing-world-ready-apps.md +++ b/docs/standard/globalization-localization/best-practices-for-developing-world-ready-apps.md @@ -38,7 +38,7 @@ This section describes the best practices to follow when developing world-ready - For Gregorian and non-Gregorian calendars, use the class or one of the specific calendar implementations. -3. Use the culture property settings provided by the class in the appropriate situations. Use the property for formatting tasks, such as date and time or numeric formatting. Use the property to retrieve resources. Note that the `CurrentCulture` and `CurrentUICulture` properties can be set per thread. +3. Use the culture property settings provided by the class in the appropriate situations. Use the property for formatting tasks, such as date and time or numeric formatting. Use the property to retrieve resources. Note that the `CurrentCulture` and `CurrentUICulture` properties can be set per thread. 4. Enable your application to read and write data to and from a variety of encodings by using the encoding classes in the namespace. Do not assume ASCII data. Assume that international characters will be supplied anywhere a user can enter text. For example, the application should accept international characters in server names, directories, file names, user names, and URLs. @@ -70,7 +70,7 @@ This section describes the best practices to follow when developing world-ready 7. Allow plenty of room for the length of strings to expand in the user interface. In some languages, phrases can require 50-75 percent more space than they need in other languages. -8. Use the class to retrieve resources based on culture. +8. Use the class to retrieve resources based on culture. 9. Use Visual Studio to create Windows Forms dialog boxes, so that they can be localized using the [Windows Forms Resource Editor (Winres.exe)](../../../docs/framework/tools/winres-exe-windows-forms-resource-editor.md). Do not code Windows Forms dialog boxes by hand. diff --git a/docs/standard/globalization-localization/globalization.md b/docs/standard/globalization-localization/globalization.md index 084c5d9aa98af..c679d4d1ecfa3 100644 --- a/docs/standard/globalization-localization/globalization.md +++ b/docs/standard/globalization-localization/globalization.md @@ -87,7 +87,7 @@ Globalization involves designing and developing a world-ready app that supports - You can include non-string resources, such as images or binary data, in the resource file instead of storing them in a separate standalone file, so they can be retrieved easily. - Using resource files has particular advantages if you are creating a localized app. When you deploy resources in satellite assemblies, the common language runtime automatically selects a culture-appropriate resource based on the user's current UI culture as defined by the property. As long as you provide an appropriate culture-specific resource and correctly instantiate a object or use a strongly typed resource class, the runtime handles the details of retrieving the appropriate resources. + Using resource files has particular advantages if you are creating a localized app. When you deploy resources in satellite assemblies, the common language runtime automatically selects a culture-appropriate resource based on the user's current UI culture as defined by the property. As long as you provide an appropriate culture-specific resource and correctly instantiate a object or use a strongly typed resource class, the runtime handles the details of retrieving the appropriate resources. For more information about creating resource files, see [Creating Resource Files](../../../docs/framework/resources/creating-resource-files-for-desktop-apps.md). For information about creating and deploying satellite assemblies, see [Creating Satellite Assemblies](../../../docs/framework/resources/creating-satellite-assemblies-for-desktop-apps.md) and [Packaging and Deploying Resources](../../../docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md). @@ -98,22 +98,22 @@ Globalization involves designing and developing a world-ready app that supports > [!TIP] > You can use the class to work with the text elements rather than the individual characters in a string. - In string searches and comparisons, a common mistake is to treat the string as a collection of characters, each of which is represented by a object. In fact, a single character may be formed by one, two, or more objects. Such characters are found most frequently in strings from cultures whose alphabets consist of characters outside the Unicode Basic Latin character range (U+0021 through U+007E). The following example tries to find the index of the LATIN CAPITAL LETTER A WITH GRAVE character (U+00C0) in a string. However, this character can be represented in two different ways: as a single code unit (U+00C0) or as a composite character (two code units: U+0021 and U+007E). In this case, the character is represented in the string instance by two objects, U+0021 and U+007E. The example code calls the and overloads to find the position of this character in the string instance, but these return different results. The first method call has a argument; it performs an ordinal comparison and therefore cannot find a match. The second call has a argument; it performs a culture-sensitive comparison and therefore finds a match. + In string searches and comparisons, a common mistake is to treat the string as a collection of characters, each of which is represented by a object. In fact, a single character may be formed by one, two, or more objects. Such characters are found most frequently in strings from cultures whose alphabets consist of characters outside the Unicode Basic Latin character range (U+0021 through U+007E). The following example tries to find the index of the LATIN CAPITAL LETTER A WITH GRAVE character (U+00C0) in a string. However, this character can be represented in two different ways: as a single code unit (U+00C0) or as a composite character (two code units: U+0021 and U+007E). In this case, the character is represented in the string instance by two objects, U+0021 and U+007E. The example code calls the and overloads to find the position of this character in the string instance, but these return different results. The first method call has a argument; it performs an ordinal comparison and therefore cannot find a match. The second call has a argument; it performs a culture-sensitive comparison and therefore finds a match. [!code-csharp[Conceptual.Globalization#18](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.globalization/cs/search1.cs#18)] [!code-vb[Conceptual.Globalization#18](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.globalization/vb/search1.vb#18)] - You can avoid some of the ambiguity of this example (calls to two similar overloads of a method returning different results) by calling an overload that includes a parameter, such as the or method. + You can avoid some of the ambiguity of this example (calls to two similar overloads of a method returning different results) by calling an overload that includes a parameter, such as the or method. However, searches are not always culture-sensitive. If the purpose of the search is to make a security decision or to allow or disallow access to some resource, the comparison should be ordinal, as discussed in the next section. ### Testing Strings for Equality - If you want to test two strings for equality rather than determining how they compare in the sort order, use the method instead of a string comparison method such as or . + If you want to test two strings for equality rather than determining how they compare in the sort order, use the method instead of a string comparison method such as or . - Comparisons for equality are typically performed to access some resource conditionally. For example, you might perform a comparison for equality to verify a password or to confirm that a file exists. Such non-linguistic comparisons should always be ordinal rather than culture-sensitive. In general, you should call the instance method or the static method with a value of for strings such as passwords, and a value of for strings such as file names or URIs. + Comparisons for equality are typically performed to access some resource conditionally. For example, you might perform a comparison for equality to verify a password or to confirm that a file exists. Such non-linguistic comparisons should always be ordinal rather than culture-sensitive. In general, you should call the instance method or the static method with a value of for strings such as passwords, and a value of for strings such as file names or URIs. - Comparisons for equality sometimes involve searches or substring comparisons rather than calls to the method. In some cases, you may use a substring search to determine whether that substring equals another string. If the purpose of this comparison is non-linguistic, the search should also be ordinal rather than culture-sensitive. + Comparisons for equality sometimes involve searches or substring comparisons rather than calls to the method. In some cases, you may use a substring search to determine whether that substring equals another string. If the purpose of this comparison is non-linguistic, the search should also be ordinal rather than culture-sensitive. The following example illustrates the danger of a culture-sensitive search on non-linguistic data. The `AccessesFileSystem` method is designed to prohibit file system access for URIs that begin with the substring "FILE". To do this, it performs a culture-sensitive, case-insensitive comparison of the beginning of the URI with the string "FILE". Because a URI that accesses the file system can begin with either "FILE:" or "file:", the implicit assumption is that that "i" (U+0069) is always the lowercase equivalent of "I" (U+0049). However, in Turkish and Azerbaijani, the uppercase version of "i" is "İ" (U+0130). Because of this discrepancy, the culture-sensitive comparison allows file system access when it should be prohibited. @@ -127,12 +127,12 @@ Globalization involves designing and developing a world-ready app that supports ### Ordering and Sorting Strings - Typically, ordered strings that are to be displayed in the user interface should be sorted based on culture. For the most part, such string comparisons are handled implicitly by the .NET Framework when you call a method that sorts strings, such as or . By default, strings are sorted by using the sorting conventions of the current culture. The following example illustrates the difference when an array of strings is sorted by using the conventions of the English (United States) culture and the Swedish (Sweden) culture. + Typically, ordered strings that are to be displayed in the user interface should be sorted based on culture. For the most part, such string comparisons are handled implicitly by the .NET Framework when you call a method that sorts strings, such as or . By default, strings are sorted by using the sorting conventions of the current culture. The following example illustrates the difference when an array of strings is sorted by using the conventions of the English (United States) culture and the Swedish (Sweden) culture. [!code-csharp[Conceptual.Globalization#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.globalization/cs/sort1.cs#14)] [!code-vb[Conceptual.Globalization#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.globalization/vb/sort1.vb#14)] - Culture-sensitive string comparison is defined by the object, which is returned by each culture's property. Culture-sensitive string comparisons that use the method overloads also use the object. + Culture-sensitive string comparison is defined by the object, which is returned by each culture's property. Culture-sensitive string comparisons that use the method overloads also use the object. The .NET Framework uses tables to perform culture-sensitive sorts on string data. The content of these tables, which contain data on sort weights and string normalization, is determined by the version of the Unicode standard implemented by a particular version of the .NET Framework. The following table lists the versions of Unicode implemented by the specified versions of the .NET Framework. Note that this list of supported Unicode versions applies to character comparison and sorting only; it does not apply to classification of Unicode characters by category. For more information, see the "Strings and The Unicode Standard" section in the article. @@ -147,9 +147,9 @@ Globalization involves designing and developing a world-ready app that supports In the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)], string comparison and sorting depends on the operating system. The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] running on [!INCLUDE[win7](../../../includes/win7-md.md)] retrieves data from its own tables that implement Unicode 5.0. The [!INCLUDE[net_v45](../../../includes/net-v45-md.md)] running on [!INCLUDE[win8](../../../includes/win8-md.md)] retrieves data from operating system tables that implement Unicode 6.0. If you serialize culture-sensitive sorted data, you can use the class to determine when your serialized data needs to be sorted so that it is consistent with the .NET Framework and the operating system's sort order. For an example, see the class topic. - If your app performs extensive culture-specific sorts of string data, you can work with the class to compare strings. A sort key reflects the culture-specific sort weights, including the alphabetic, case, and diacritic weights of a particular string. Because comparisons using sort keys are binary, they are faster than comparisons that use a object either implicitly or explicitly. You create a culture-specific sort key for a particular string by passing the string to the method. + If your app performs extensive culture-specific sorts of string data, you can work with the class to compare strings. A sort key reflects the culture-specific sort weights, including the alphabetic, case, and diacritic weights of a particular string. Because comparisons using sort keys are binary, they are faster than comparisons that use a object either implicitly or explicitly. You create a culture-specific sort key for a particular string by passing the string to the method. - The following example is similar to the previous example. However, instead of calling the method, which implicitly calls the method, it defines an implementation that compares sort keys, which it instantiates and passes to the method. + The following example is similar to the previous example. However, instead of calling the method, which implicitly calls the method, it defines an implementation that compares sort keys, which it instantiates and passes to the method. [!code-csharp[Conceptual.Globalization#15](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.globalization/cs/sortkey1.cs#15)] [!code-vb[Conceptual.Globalization#15](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.globalization/vb/sortkey1.vb#15)] @@ -164,15 +164,15 @@ Globalization involves designing and developing a world-ready app that supports ### Displaying Dates and Times - Typically, when dates and times are displayed in the user interface, you should use the formatting conventions of the user's culture, which is defined by the property and by the object returned by the `CultureInfo.CurrentCulture.DateTimeFormat` property. The formatting conventions of the current culture are automatically used when you format a date by using any of these methods: + Typically, when dates and times are displayed in the user interface, you should use the formatting conventions of the user's culture, which is defined by the property and by the object returned by the `CultureInfo.CurrentCulture.DateTimeFormat` property. The formatting conventions of the current culture are automatically used when you format a date by using any of these methods: -- The parameterless method +- The parameterless method -- The method, which includes a format string +- The method, which includes a format string -- The parameterless method +- The parameterless method -- The , which includes a format string +- The , which includes a format string - The [composite formatting](../../../docs/standard/base-types/composite-formatting.md) feature, when it is used with dates @@ -196,7 +196,7 @@ Globalization involves designing and developing a world-ready app that supports - Save the string by using the formatting conventions of the invariant culture. - The following example illustrates the last approach. It uses the formatting conventions of the invariant culture returned by the static property. + The following example illustrates the last approach. It uses the formatting conventions of the invariant culture returned by the static property. [!code-csharp[Conceptual.Globalization#4](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.globalization/cs/dates3.cs#4)] [!code-vb[Conceptual.Globalization#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.globalization/vb/dates3.vb#4)] @@ -303,7 +303,7 @@ Globalization involves designing and developing a world-ready app that supports ### Displaying Numeric Values - Typically, when numbers are displayed in the user interface, you should use the formatting conventions of the user's culture, which is defined by the property and by the object returned by the `CultureInfo.CurrentCulture.NumberFormat` property. The formatting conventions of the current culture are automatically used when you format a date by using any of the following methods: + Typically, when numbers are displayed in the user interface, you should use the formatting conventions of the user's culture, which is defined by the property and by the object returned by the `CultureInfo.CurrentCulture.NumberFormat` property. The formatting conventions of the current culture are automatically used when you format a date by using any of the following methods: - The parameterless `ToString` method of any numeric type @@ -311,7 +311,7 @@ Globalization involves designing and developing a world-ready app that supports - The [composite formatting](../../../docs/standard/base-types/composite-formatting.md) feature, when it is used with numeric values - The following example displays the average temperature per month in Paris, France. It first sets the current culture to French (France) before displaying the data, and then sets it to English (United States). In each case, the month names and temperatures are displayed in the format that is appropriate for that culture. Note that the two cultures use different decimal separators in the temperature value. Also note that the example uses the "MMMM" custom date and time format string to display the full month name, and that it allocates the appropriate amount of space for the month name in the result string by determining the length of the longest month name in the array. + The following example displays the average temperature per month in Paris, France. It first sets the current culture to French (France) before displaying the data, and then sets it to English (United States). In each case, the month names and temperatures are displayed in the format that is appropriate for that culture. Note that the two cultures use different decimal separators in the temperature value. Also note that the example uses the "MMMM" custom date and time format string to display the full month name, and that it allocates the appropriate amount of space for the month name in the result string by determining the length of the longest month name in the array. [!code-csharp[Conceptual.Globalization#5](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.globalization/cs/numbers1.cs#5)] [!code-vb[Conceptual.Globalization#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.globalization/vb/numbers1.vb#5)] @@ -327,7 +327,7 @@ Globalization involves designing and developing a world-ready app that supports - Save and parse the string representation of the number by using a custom format string that is the same regardless of the user's culture. -- Save the number as a string by using the formatting conventions of the invariant culture, which is returned by the property. +- Save the number as a string by using the formatting conventions of the invariant culture, which is returned by the property. - Serialize the number in binary instead of string format. @@ -350,13 +350,13 @@ Globalization involves designing and developing a world-ready app that supports ## Working with Culture-Specific Settings In the .NET Framework, the class represents a particular culture or region. Some of its properties return objects that provide specific information about some aspect of a culture: -- The property returns a object that contains information about how the culture compares and orders strings. +- The property returns a object that contains information about how the culture compares and orders strings. -- The property returns a object that provides culture-specific information used in formatting date and time data. +- The property returns a object that provides culture-specific information used in formatting date and time data. -- The property returns a object that provides culture-specific information used in formatting numeric data. +- The property returns a object that provides culture-specific information used in formatting numeric data. -- The property returns a object that provides information about the culture's writing system. +- The property returns a object that provides information about the culture's writing system. In general, do not make any assumptions about the values of specific properties and their related objects. Instead, you should view culture-specific data as subject to change, for these reasons: @@ -366,7 +366,7 @@ Globalization involves designing and developing a world-ready app that supports - The .NET Framework supports replacement cultures. This makes it possible to define a new custom culture that either supplements existing standard cultures or completely replaces an existing standard culture. -- The user can customize culture-specific settings by using the **Region and Language** app in Control Panel. When you instantiate a object, you can determine whether it reflects these user customizations by calling the constructor. Typically, for end-user apps, you should respect user preferences so that the user is presented with data in a format that he or she expects. +- The user can customize culture-specific settings by using the **Region and Language** app in Control Panel. When you instantiate a object, you can determine whether it reflects these user customizations by calling the constructor. Typically, for end-user apps, you should respect user preferences so that the user is presented with data in a format that he or she expects. ## See Also [Globalization and Localization](../../../docs/standard/globalization-localization/index.md) diff --git a/docs/standard/globalization-localization/index.md b/docs/standard/globalization-localization/index.md index b456dcd4eb288..2c9cff4cee774 100644 --- a/docs/standard/globalization-localization/index.md +++ b/docs/standard/globalization-localization/index.md @@ -61,7 +61,7 @@ Developing a [world-ready application](http://msdn.microsoft.com/goglobal/bb9784 Describes the best practices to follow for globalization, localization, and developing world-ready ASP.NET applications. ## Reference - namespace + namespace Contains classes that define culture-related information, including the language, the country/region, the calendars in use, the format patterns for dates, currency, and numbers, and the sort order for strings. namespace diff --git a/docs/standard/globalization-localization/localizability-review.md b/docs/standard/globalization-localization/localizability-review.md index 10f1521669d86..96823ebaeefb3 100644 --- a/docs/standard/globalization-localization/localizability-review.md +++ b/docs/standard/globalization-localization/localizability-review.md @@ -49,7 +49,7 @@ The localizability review is an intermediate step in the development of a world- - Paper sizes. -- Units of measure used for lengths, weights, area, volume, and temperatures. Although the .NET Framework does not offer built-in support for converting between units of measure, you can use the property to determine whether a particular country or region uses the metric system, as the following example illustrates. +- Units of measure used for lengths, weights, area, volume, and temperatures. Although the .NET Framework does not offer built-in support for converting between units of measure, you can use the property to determine whether a particular country or region uses the metric system, as the following example illustrates. [!code-csharp[Conceptual.Localizability#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.localizability/cs/ismetric1.cs#1)] [!code-vb[Conceptual.Localizability#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.localizability/vb/ismetric1.vb#1)] diff --git a/docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md b/docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md index 070a174d49485..7e91fa6d43586 100644 --- a/docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md +++ b/docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md @@ -24,9 +24,9 @@ ms.author: "ronpet" manager: "wpickett" --- # Performing Culture-Insensitive Case Changes -The , , , and methods provide overloads that do not accept any parameters. By default, these overloads without parameters perform case changes based on the value of the . This produces case-sensitive results that can vary by culture. To make it clear whether you want case changes to be culture-sensitive or culture-insensitive, you should use the overloads of these methods that require you to explicitly specify a `culture` parameter. For culture-sensitive case changes, specify `CultureInfo.CurrentCulture` for the `culture` parameter. For culture-insensitive case changes, specify `CultureInfo.InvariantCulture` for the `culture` parameter. +The , , , and methods provide overloads that do not accept any parameters. By default, these overloads without parameters perform case changes based on the value of the . This produces case-sensitive results that can vary by culture. To make it clear whether you want case changes to be culture-sensitive or culture-insensitive, you should use the overloads of these methods that require you to explicitly specify a `culture` parameter. For culture-sensitive case changes, specify `CultureInfo.CurrentCulture` for the `culture` parameter. For culture-insensitive case changes, specify `CultureInfo.InvariantCulture` for the `culture` parameter. - Often, strings are converted to a standard case to enable easier lookup later. When strings are used in this way, you should specify `CultureInfo.InvariantCulture` for the `culture` parameter, because the value of can potentially change between the time that the case is changed and the time that the lookup occurs. + Often, strings are converted to a standard case to enable easier lookup later. When strings are used in this way, you should specify `CultureInfo.InvariantCulture` for the `culture` parameter, because the value of can potentially change between the time that the case is changed and the time that the lookup occurs. If a security decision is based on a case change operation, the operation should be culture-insensitive to ensure that the result is not affected by the value of `CultureInfo.CurrentCulture`. See the "String Comparisons that Use the Current Culture" section of the [Best Practices for Using Strings](../../../docs/standard/base-types/best-practices-strings.md) article for an example that demonstrates how culture-sensitive string operations can produce inconsistent results. @@ -67,8 +67,8 @@ static object LookupKey(string key) Although the `Char.ToUpper` and `Char.ToLower` methods have the same characteristics as the `String.ToUpper` and `String.ToLower` methods, the only cultures that are affected are Turkish (Turkey) and Azerbaijani (Latin, Azerbaijan). These are the only two cultures with single-character casing differences. For more details about this unique case mapping, see the "Casing" section in the class topic. For code clarity and to ensure consistent results, it is recommended that you always use the overloads of these methods that allow you to explicitly specify a `culture` parameter. ## See Also - - - - + + + + [Performing Culture-Insensitive String Operations](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md) diff --git a/docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md b/docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md index 144d48926fb4d..3317689001f2c 100644 --- a/docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md +++ b/docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md @@ -22,16 +22,16 @@ ms.author: "ronpet" manager: "wpickett" --- # Performing Culture-Insensitive String Comparisons -By default, the method performs culture-sensitive and case-sensitive comparisons. This method also includes several overloads that provide a `culture` parameter that lets you specify the culture to use, and a `comparisonType` parameter that lets you specify the comparison rules to use. Calling these methods instead of the default overload removes any ambiguity about the rules used in a particular method call, and makes it clear whether a particular comparison is culture-sensitive or culture-insensitive. +By default, the method performs culture-sensitive and case-sensitive comparisons. This method also includes several overloads that provide a `culture` parameter that lets you specify the culture to use, and a `comparisonType` parameter that lets you specify the comparison rules to use. Calling these methods instead of the default overload removes any ambiguity about the rules used in a particular method call, and makes it clear whether a particular comparison is culture-sensitive or culture-insensitive. > [!NOTE] -> Both overloads of the method perform culture-sensitive and case-sensitive comparisons; you cannot use this method to perform culture-insensitive comparisons. For code clarity, we recommend that you use the method instead. +> Both overloads of the method perform culture-sensitive and case-sensitive comparisons; you cannot use this method to perform culture-insensitive comparisons. For code clarity, we recommend that you use the method instead. - For culture-sensitive operations, specify the or enumeration value as the `comparisonType` parameter. If you want to perform a culture-sensitive comparison using a designated culture other than the current culture, specify the object that represents that culture as the `culture` parameter. + For culture-sensitive operations, specify the or enumeration value as the `comparisonType` parameter. If you want to perform a culture-sensitive comparison using a designated culture other than the current culture, specify the object that represents that culture as the `culture` parameter. - The culture-insensitive string comparisons supported by the method are either linguistic (based on the sorting conventions of the invariant culture) or non-linguistic (based on the ordinal value of the characters in the string). Most culture-insensitive string comparisons are non-linguistic. For these comparisons, specify the or enumeration value as the `comparisonType` parameter. For example, if a security decision (such as a user name or password comparison) is based on the result of a string comparison, the operation should be culture-insensitive and non-linguistic to ensure that the result is not affected by the conventions of a particular culture or language. + The culture-insensitive string comparisons supported by the method are either linguistic (based on the sorting conventions of the invariant culture) or non-linguistic (based on the ordinal value of the characters in the string). Most culture-insensitive string comparisons are non-linguistic. For these comparisons, specify the or enumeration value as the `comparisonType` parameter. For example, if a security decision (such as a user name or password comparison) is based on the result of a string comparison, the operation should be culture-insensitive and non-linguistic to ensure that the result is not affected by the conventions of a particular culture or language. - Use culture-insensitive linguistic string comparison if you want to handle linguistically relevant strings from multiple cultures in a consistent way. For example, if your application displays words that use multiple character sets in a list box, you might want to display words in the same order regardless of the current culture. For culture-insensitive linguistic comparisons, the .NET Framework defines an invariant culture that is based on the linguistic conventions of English. To perform a culture-insensitive linguistic comparison, specify or as the `comparisonType` parameter. + Use culture-insensitive linguistic string comparison if you want to handle linguistically relevant strings from multiple cultures in a consistent way. For example, if your application displays words that use multiple character sets in a list box, you might want to display words in the same order regardless of the current culture. For culture-insensitive linguistic comparisons, the .NET Framework defines an invariant culture that is based on the linguistic conventions of English. To perform a culture-insensitive linguistic comparison, specify or as the `comparisonType` parameter. The following example performs two culture-insensitive, non-linguistic string comparisons. The first is case-sensitive, but the second is not. @@ -39,7 +39,7 @@ By default, the method [!code-vb[Conceptual.Strings.CultureInsensitiveComparison#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.cultureinsensitivecomparison/vb/cultureinsensitive1.vb#1)] ## See Also - - + + [Performing Culture-Insensitive String Operations](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md) [Best Practices for Using Strings](../../../docs/standard/base-types/best-practices-strings.md) diff --git a/docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-arrays.md b/docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-arrays.md index 1fc6a132f007f..6b848185eae80 100644 --- a/docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-arrays.md +++ b/docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-arrays.md @@ -19,12 +19,12 @@ ms.author: "ronpet" manager: "wpickett" --- # Performing Culture-Insensitive String Operations in Arrays -Overloads of the and methods perform culture-sensitive sorts by default using the property. Culture-sensitive results returned by these methods can vary by culture due to differences in sort orders. To eliminate culture-sensitive behavior, use one of the overloads of this method that accepts a `comparer` parameter. The `comparer` parameter specifies the implementation to use when comparing elements in the array. For the parameter, specify a custom invariant comparer class that uses . An example of a custom invariant comparer class is provided in the "Using the SortedList Class" subtopic of the [Performing Culture-Insensitive String Operations in Collections](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-collections.md) topic. +Overloads of the and methods perform culture-sensitive sorts by default using the property. Culture-sensitive results returned by these methods can vary by culture due to differences in sort orders. To eliminate culture-sensitive behavior, use one of the overloads of this method that accepts a `comparer` parameter. The `comparer` parameter specifies the implementation to use when comparing elements in the array. For the parameter, specify a custom invariant comparer class that uses . An example of a custom invariant comparer class is provided in the "Using the SortedList Class" subtopic of the [Performing Culture-Insensitive String Operations in Collections](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-collections.md) topic. **Note** Passing **CultureInfo.InvariantCulture** to a comparison method does perform a culture-insensitive comparison. However, it does not cause a non-linguistic comparison, for example, for file paths, registry keys, and environment variables. Neither does it support security decisions based on the comparison result. For a non-linguistic comparison or support for result-based security decisions, the application should use a comparison method that accepts a value. The application should then pass . ## See Also - - + + [Performing Culture-Insensitive String Operations](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md) diff --git a/docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-collections.md b/docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-collections.md index 7f220970372dc..b6329138e4099 100644 --- a/docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-collections.md +++ b/docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-collections.md @@ -24,9 +24,9 @@ ms.author: "ronpet" manager: "wpickett" --- # Performing Culture-Insensitive String Operations in Collections -There are classes and members in the namespace that provide culture-sensitive behavior by default. The default constructors for the and classes initialize a new instance using the property. All overloads of the method create a new instance of the class using the `Thread.CurrentCulture` property by default. Overloads of the method perform culture-sensitive sorts by default using `Thread.CurrentCulture`. Sorting and lookup in a can be affected by `Thread.CurrentCulture` when strings are used as the keys. Follow the usage recommendations provided in this section to obtain culture-insensitive results from these classes and methods in the `Collections` namespace. +There are classes and members in the namespace that provide culture-sensitive behavior by default. The default constructors for the and classes initialize a new instance using the property. All overloads of the method create a new instance of the class using the `Thread.CurrentCulture` property by default. Overloads of the method perform culture-sensitive sorts by default using `Thread.CurrentCulture`. Sorting and lookup in a can be affected by `Thread.CurrentCulture` when strings are used as the keys. Follow the usage recommendations provided in this section to obtain culture-insensitive results from these classes and methods in the `Collections` namespace. - **Note** Passing to a comparison method does perform a culture-insensitive comparison. However, it does not cause a non-linguistic comparison, for example, for file paths, registry keys, and environment variables. Neither does it support security decisions based on the comparison result. For a non-linguistic comparison or support for result-based security decisions, the application should use a comparison method that accepts a value. The application should then pass . + **Note** Passing to a comparison method does perform a culture-insensitive comparison. However, it does not cause a non-linguistic comparison, for example, for file paths, registry keys, and environment variables. Neither does it support security decisions based on the comparison result. For a non-linguistic comparison or support for result-based security decisions, the application should use a comparison method that accepts a value. The application should then pass . ## Using the CaseInsensitiveComparer and CaseInsensitiveHashCodeProvider Classes The default constructors for `CaseInsensitiveHashCodeProvider` and `CaseInsensitiveComparer` initialize a new instance of the class using the `Thread.CurrentCulture`, resulting in culture-sensitive behavior. The following code example demonstrates the constructor for a `Hashtable` that is culture-sensitive because it uses the default constructors for `CaseInsensitiveHashCodeProvider` and `CaseInsensitiveComparer`. @@ -39,7 +39,7 @@ internalHashtable = New Hashtable(CaseInsensitiveHashCodeProvider.Default, CaseI internalHashtable = new Hashtable(CaseInsensitiveHashCodeProvider.Default, CaseInsensitiveComparer.Default); ``` - If you want to create a culture-insensitive `Hashtable` using the `CaseInsensitiveComparer` and `CaseInsensitiveHashCodeProvider` classes, initialize new instances of these classes using the constructors that accept a `culture` parameter. For the `culture` parameter, specify . The following code example demonstrates the constructor for a culture-insensitive `Hashtable`. + If you want to create a culture-insensitive `Hashtable` using the `CaseInsensitiveComparer` and `CaseInsensitiveHashCodeProvider` classes, initialize new instances of these classes using the constructors that accept a `culture` parameter. For the `culture` parameter, specify . The following code example demonstrates the constructor for a culture-insensitive `Hashtable`. ```vb internalHashtable = New Hashtable(New @@ -135,9 +135,9 @@ internal class InvariantComparer : IComparer ## See Also - + [Performing Culture-Insensitive String Operations](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md) - + diff --git a/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md b/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md index afe51548b9a4c..7af91df22f9ee 100644 --- a/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md +++ b/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md @@ -29,16 +29,16 @@ Most .NET Framework methods that perform culture-sensitive string operations by ## In This Section [Performing Culture-Insensitive String Comparisons](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-comparisons.md) - Describes how to use the and methods to perform culture-insensitive string comparisons. + Describes how to use the and methods to perform culture-insensitive string comparisons. [Performing Culture-Insensitive Case Changes](../../../docs/standard/globalization-localization/performing-culture-insensitive-case-changes.md) - Describes how to use the , , , and methods to perform culture-insensitive case changes. + Describes how to use the , , , and methods to perform culture-insensitive case changes. [Performing Culture-Insensitive String Operations in Collections](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-collections.md) - Describes how to use the , class, , and to perform culture-insensitive operations in collections. + Describes how to use the , class, , and to perform culture-insensitive operations in collections. [Performing Culture-Insensitive String Operations in Arrays](../../../docs/standard/globalization-localization/performing-culture-insensitive-string-operations-in-arrays.md) - Describes how to use the and methods to perform culture-insensitive operations in arrays. + Describes how to use the and methods to perform culture-insensitive operations in arrays. ## Related Sections [Culture-Insensitive String Operations](../../../docs/standard/globalization-localization/culture-insensitive-string-operations.md) diff --git a/docs/standard/io/common-i-o-tasks.md b/docs/standard/io/common-i-o-tasks.md index dd0bc721b2d8b..f0c676e1d894e 100644 --- a/docs/standard/io/common-i-o-tasks.md +++ b/docs/standard/io/common-i-o-tasks.md @@ -23,37 +23,37 @@ The namespace provides several classes that allow for various a |To do this...|See the example in this topic...| |-------------------|--------------------------------------| -|Create a text file| method

method

method

method| +|Create a text file| method

method

method

method| |Write to a text file|[How to: Write Text to a File](../../../docs/standard/io/how-to-write-text-to-a-file.md)

[How to: Write a Text File (C++/CLI)](/cpp/dotnet/how-to-write-a-text-file-cpp-cli)| |Read from a text file|[How to: Read Text from a File](../../../docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file|[How to: Open and Append to a Log File](../../../docs/standard/io/how-to-open-and-append-to-a-log-file.md)

method

method| -|Rename or move a file| method

method| -|Delete a file| method

method| -|Copy a file| method

method| -|Get the size of a file| property| -|Get the attributes of a file| method| -|Set the attributes of a file| method| -|Determine whether a file exists| method| +|Append text to a file|[How to: Open and Append to a Log File](../../../docs/standard/io/how-to-open-and-append-to-a-log-file.md)

method

method| +|Rename or move a file| method

method| +|Delete a file| method

method| +|Copy a file| method

method| +|Get the size of a file| property| +|Get the attributes of a file| method| +|Set the attributes of a file| method| +|Determine whether a file exists| method| |Read from a binary file|[How to: Read and Write to a Newly Created Data File](../../../docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file|[How to: Read and Write to a Newly Created Data File](../../../docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| -|Retrieve a file name extension| method| -|Retrieve the fully qualified path of a file| method| -|Retrieve the file name and extension from a path| method| -|Change the extension of a file| method| +|Retrieve a file name extension| method| +|Retrieve the fully qualified path of a file| method| +|Retrieve the file name and extension from a path| method| +|Change the extension of a file| method| ## Common Directory Tasks |To do this...|See the example in this topic...| |-------------------|--------------------------------------| |Access a file in a special folder such as My Documents|[How to: Write Text to a File](../../../docs/standard/io/how-to-write-text-to-a-file.md)| -|Create a directory| method

property| -|Create a subdirectory| method| -|Rename or move a directory| method

method| +|Create a directory| method

property| +|Create a subdirectory| method| +|Rename or move a directory| method

method| |Copy a directory|[How to: Copy Directories](../../../docs/standard/io/how-to-copy-directories.md)| -|Delete a directory| method

method| +|Delete a directory| method

method| |See the files and subdirectories in a directory|[How to: Enumerate Directories and Files](../../../docs/standard/io/how-to-enumerate-directories-and-files.md)| -|Find the size of a directory| class| -|Determine whether a directory exists| method| +|Find the size of a directory| class| +|Determine whether a directory exists| method| ## See Also [File and Stream I-O](../../../docs/standard/io/index.md) diff --git a/docs/standard/io/composing-streams.md b/docs/standard/io/composing-streams.md index bc2bef47b9a83..bf604e0c26eda 100644 --- a/docs/standard/io/composing-streams.md +++ b/docs/standard/io/composing-streams.md @@ -39,9 +39,9 @@ A backing store is a storage medium, such as a disk or memory. Each different ba ## See Also - - + + - - + + diff --git a/docs/standard/io/how-to-compress-and-extract-files.md b/docs/standard/io/how-to-compress-and-extract-files.md index 039d128b2a58a..4eeacede093e4 100644 --- a/docs/standard/io/how-to-compress-and-extract-files.md +++ b/docs/standard/io/how-to-compress-and-extract-files.md @@ -40,7 +40,7 @@ The namespace contains the following types for comp [!code-vb[System.IO.Compression.ZipFile#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.zipfile/vb/program1.vb#1)] ## Example - The next example shows how to iterate through the contents of an existing .zip file and extract files that have a .txt extension. It uses the class to access an existing .zip file, and the class to inspect the individual entries in the compressed file. It uses an extension method () for the object. The extension method is available in the class. To use the class, you must reference the `System.IO.Compression.FileSystem` assembly in your project. + The next example shows how to iterate through the contents of an existing .zip file and extract files that have a .txt extension. It uses the class to access an existing .zip file, and the class to inspect the individual entries in the compressed file. It uses an extension method () for the object. The extension method is available in the class. To use the class, you must reference the `System.IO.Compression.FileSystem` assembly in your project. [!code-csharp[System.IO.Compression.ZipArchive#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchive/cs/program1.cs#1)] [!code-vb[System.IO.Compression.ZipArchive#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchive/vb/program1.vb#1)] diff --git a/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md b/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md index cdd72ec4d3f59..57d9c9945bc4e 100644 --- a/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md +++ b/docs/standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md @@ -69,7 +69,7 @@ The .NET Framework for Windows Store apps is a subset of the full .NET Framework - Use the [AsRandomAccessStream](../../../docs/standard/cross-platform/windowsruntimestreamextensions-asrandomaccessstream-method.md) method, as shown in the following example. > [!IMPORTANT] - > Ensure that the .NET Framework stream you are using supports seeking, or copy it to a stream that does. You can use the property to determine this. + > Ensure that the .NET Framework stream you are using supports seeking, or copy it to a stream that does. You can use the property to determine this. To run this example, you must create a Windows Store XAML app that targets the .NET Framework 4.5.1 and contains a text block named `TextBlock2` and a button named `Button2`. The button click event must be associated with the `button2_Click` method shown in this example. diff --git a/docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md b/docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md index 041f58be4e05b..611f05763378a 100644 --- a/docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md +++ b/docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md @@ -25,9 +25,9 @@ manager: "wpickett" # How to: Create Files and Directories in Isolated Storage After you have obtained an isolated store, you can create directories and files for storing data. Within a store, file and directory names are specified with respect to the root of the virtual file system. - To create a directory, use the instance method. If you specify a subdirectory of an directory that doesn't exist, both directories are created. If you specify a directory that already exists, the method returns without creating a directory, and no exception is thrown. However, if you specify a directory name that contains invalid characters, an exception is thrown. + To create a directory, use the instance method. If you specify a subdirectory of an directory that doesn't exist, both directories are created. If you specify a directory that already exists, the method returns without creating a directory, and no exception is thrown. However, if you specify a directory name that contains invalid characters, an exception is thrown. - To create a file, use the method. + To create a file, use the method. In the Windows operating system, isolated storage file and directory names are case-insensitive. That is, if you create a file named `ThisFile.txt`, and then create another file named `THISFILE.TXT`, only one file is created. The file name keeps its original casing for display purposes. diff --git a/docs/standard/io/how-to-delete-files-and-directories-in-isolated-storage.md b/docs/standard/io/how-to-delete-files-and-directories-in-isolated-storage.md index a9bd6ab72908e..a7c2509783444 100644 --- a/docs/standard/io/how-to-delete-files-and-directories-in-isolated-storage.md +++ b/docs/standard/io/how-to-delete-files-and-directories-in-isolated-storage.md @@ -27,7 +27,7 @@ manager: "wpickett" # How to: Delete Files and Directories in Isolated Storage You can delete directories and files within an isolated storage file. Within a store, file and directory names are operating-system dependent and are specified as relative to the root of the virtual file system. They are not case-sensitive on Windows operating systems. - The class supplies two methods for deleting directories and files: and . An exception is thrown if you try to delete a file or directory that does not exist. If you include a wildcard character in the name, throws an exception, and throws an exception. + The class supplies two methods for deleting directories and files: and . An exception is thrown if you try to delete a file or directory that does not exist. If you include a wildcard character in the name, throws an exception, and throws an exception. The method fails if the directory contains any files or subdirectories. You can use the and methods to retrieve the existing files and directories. For more information about searching the virtual file system of a store, see [How to: Find Existing Files and Directories in Isolated Storage](../../../docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md). @@ -39,5 +39,5 @@ You can delete directories and files within an isolated storage file. Within a s [!code-vb[Conceptual.IsolatedStorage#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.isolatedstorage/vb/source4.vb#4)] ## See Also - + [Isolated Storage](../../../docs/standard/io/isolated-storage.md) diff --git a/docs/standard/io/how-to-enumerate-directories-and-files.md b/docs/standard/io/how-to-enumerate-directories-and-files.md index c980203215050..6c6edcacae71c 100644 --- a/docs/standard/io/how-to-enumerate-directories-and-files.md +++ b/docs/standard/io/how-to-enumerate-directories-and-files.md @@ -27,39 +27,39 @@ You can enumerate directories and files by using methods that return an enumerab |To enumerate|Enumerable collection to return|Method to use| |------------------|-------------------------------------|-------------------| -|Directories|Directory names|| -||Directory information ()|| -|Files|File names|| -||File information ()|| -|File system information|File system entries|| -||File system information ()|| +|Directories|Directory names|| +||Directory information ()|| +|Files|File names|| +||File information ()|| +|File system information|File system entries|| +||File system information ()|| Although you can immediately enumerate all the files in the subdirectories of a parent directory by using the search option provided by the enumeration, unauthorized access exceptions () may cause the enumeration to be incomplete. If these exceptions are possible, you can catch them and continue by first enumerating directories and then enumerating files. ### To enumerate directory names -- Use the method to obtain a list of the top-level directory names in a specified path. +- Use the method to obtain a list of the top-level directory names in a specified path. [!code-csharp[System.IO.EnumDirs1#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.enumdirs1/cs/program.cs#1)] [!code-vb[System.IO.EnumDirs1#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.enumdirs1/vb/program.vb#1)] ### To enumerate file names in a directory and subdirectories -- Use the method to search a directory and (optionally) its subdirectories, and to obtain a list of file names that match a specified search pattern. +- Use the method to search a directory and (optionally) its subdirectories, and to obtain a list of file names that match a specified search pattern. [!code-csharp[System.IO.Directory.EnumerateFiles#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/cs/program.cs#1)] [!code-vb[System.IO.Directory.EnumerateFiles#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directory.enumeratefiles/vb/program.vb#1)] ### To enumerate a collection of DirectoryInfo objects -- Use the method to obtain a collection of top-level directories. +- Use the method to obtain a collection of top-level directories. [!code-csharp[System.IO.DirectoryInfo.EnumDirs#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directoryinfo.enumdirs/cs/program.cs#1)] [!code-vb[System.IO.DirectoryInfo.EnumDirs#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumdirs/vb/module1.vb#1)] ### To enumerate a collection of FileInfo objects in all directories -- Use the method to obtain a collection of files that match a specified search pattern in all directories. This example first enumerates the top-level directories to catch possible unauthorized access exceptions, and then enumerates the files. +- Use the method to obtain a collection of files that match a specified search pattern in all directories. This example first enumerates the top-level directories to catch possible unauthorized access exceptions, and then enumerates the files. [!code-csharp[System.IO.DirectoryInfo.EnumerateDirectories#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directoryinfo.enumeratedirectories/cs/program.cs#1)] [!code-vb[System.IO.DirectoryInfo.EnumerateDirectories#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumeratedirectories/vb/program.vb#1)] diff --git a/docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md b/docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md index 64d2cbc9cac7d..0f5256c2e1b25 100644 --- a/docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md +++ b/docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md @@ -22,7 +22,7 @@ ms.author: "mairaw" manager: "wpickett" --- # How to: Enumerate Stores for Isolated Storage -You can enumerate all isolated stores for the current user by using the static method. This method takes an value and returns an enumerator. To enumerate stores, you must have the permission that specifies the value. If you call the method with the value, it returns an array of objects that are defined for the current user. +You can enumerate all isolated stores for the current user by using the static method. This method takes an value and returns an enumerator. To enumerate stores, you must have the permission that specifies the value. If you call the method with the value, it returns an array of objects that are defined for the current user. ## Example The following code example obtains a store that is isolated by user and assembly, creates a few files, and retrieves those files by using the method. diff --git a/docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md b/docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md index d53b6d928d877..3cb4b17b0acb2 100644 --- a/docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md +++ b/docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md @@ -25,9 +25,9 @@ ms.author: "mairaw" manager: "wpickett" --- # How to: Find Existing Files and Directories in Isolated Storage -To search for a directory in isolated storage, use the method. This method takes a string that represents a search pattern. You can use both single-character (?) and multi-character (*) wildcard characters in the search pattern, but the wildcard characters must appear in the final portion of the name. For example, `directory1/*ect*` is a valid search string, but `*ect*/directory2` is not. +To search for a directory in isolated storage, use the method. This method takes a string that represents a search pattern. You can use both single-character (?) and multi-character (*) wildcard characters in the search pattern, but the wildcard characters must appear in the final portion of the name. For example, `directory1/*ect*` is a valid search string, but `*ect*/directory2` is not. - To search for a file, use the method. The restriction for wildcard characters in search strings that applies to also applies to . + To search for a file, use the method. The restriction for wildcard characters in search strings that applies to also applies to . Neither of these methods is recursive; the class does not supply any methods for listing all directories or files in your store. However, recursive methods are shown in the following code example. diff --git a/docs/standard/io/how-to-obtain-stores-for-isolated-storage.md b/docs/standard/io/how-to-obtain-stores-for-isolated-storage.md index a374f1a0027df..0c282a1fbeebe 100644 --- a/docs/standard/io/how-to-obtain-stores-for-isolated-storage.md +++ b/docs/standard/io/how-to-obtain-stores-for-isolated-storage.md @@ -46,7 +46,7 @@ An isolated store exposes a virtual file system within a data compartment. The < There is no mechanism that prevents code from passing an object to code that does not have sufficient access to get the store itself. Domain and assembly identities and isolated storage permissions are checked only when a reference to an object is obtained, typically in the , , or method. Protecting references to objects is, therefore, the responsibility of the code that uses these references. ## Example - The following code provides a simple example of a class obtaining a store that is isolated by user and assembly. The code can be changed to retrieve a store that is isolated by user, domain, and assembly by adding to the arguments that the method passes. + The following code provides a simple example of a class obtaining a store that is isolated by user and assembly. The code can be changed to retrieve a store that is isolated by user, domain, and assembly by adding to the arguments that the method passes. After you run the code, you can confirm that a store was created by typing **StoreAdm /LIST** at the command line. This runs the [Isolated Storage tool (Storeadm.exe)](../../../docs/framework/tools/storeadm-exe-isolated-storage-tool.md) and lists all the current isolated stores for the user. diff --git a/docs/standard/io/how-to-open-and-append-to-a-log-file.md b/docs/standard/io/how-to-open-and-append-to-a-log-file.md index 0ce444fa18f26..d69c6afde4452 100644 --- a/docs/standard/io/how-to-open-and-append-to-a-log-file.md +++ b/docs/standard/io/how-to-open-and-append-to-a-log-file.md @@ -32,9 +32,9 @@ manager: "wpickett" ## See Also - - - + + + [How to: Enumerate Directories and Files](../../../docs/standard/io/how-to-enumerate-directories-and-files.md) [How to: Read and Write to a Newly Created Data File](../../../docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md) [How to: Read Text from a File](../../../docs/standard/io/how-to-read-text-from-a-file.md) diff --git a/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md b/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md index 450c8c6208b2c..b190ffe2656ef 100644 --- a/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md +++ b/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md @@ -21,7 +21,7 @@ ms.author: "mairaw" manager: "wpickett" --- # How to: Read and Write to a Newly Created Data File -The and classes are used for writing and reading data rather than character strings. The following example demonstrates how to write data to, and read data from, a new, empty file stream called `Test.data`. After creating the data file in the current directory, the associated and objects are created, and the object is used to write the integers 0 through 10 to `Test.data`, which leaves the file pointer at the end of the file. After setting the file pointer back to the origin, the object reads out the specified content. +The and classes are used for writing and reading data rather than character strings. The following example demonstrates how to write data to, and read data from, a new, empty file stream called `Test.data`. After creating the data file in the current directory, the associated and objects are created, and the object is used to write the integers 0 through 10 to `Test.data`, which leaves the file pointer at the end of the file. After setting the file pointer back to the origin, the object reads out the specified content. ## Example [!code-cpp[System.IO.BinaryReaderWriter#7](../../../samples/snippets/cpp/VS_Snippets_CLR_System/system.IO.BinaryReaderWriter/CPP/source6.cpp#7)] @@ -29,13 +29,13 @@ The and exception is thrown. Use the file mode option when you initialize the file stream to always create a new file without throwing an exception. + If `Test.data` already exists in the current directory, an exception is thrown. Use the file mode option when you initialize the file stream to always create a new file without throwing an exception. ## See Also - + [How to: Enumerate Directories and Files](../../../docs/standard/io/how-to-enumerate-directories-and-files.md) [How to: Open and Append to a Log File](../../../docs/standard/io/how-to-open-and-append-to-a-log-file.md) diff --git a/docs/standard/io/how-to-read-and-write-to-files-in-isolated-storage.md b/docs/standard/io/how-to-read-and-write-to-files-in-isolated-storage.md index 2139c50b4c3dc..4f25ddd0ec9f9 100644 --- a/docs/standard/io/how-to-read-and-write-to-files-in-isolated-storage.md +++ b/docs/standard/io/how-to-read-and-write-to-files-in-isolated-storage.md @@ -36,9 +36,9 @@ To read from, or write to, a file in an isolated store, use an - - - - + + + + [File and Stream I-O](../../../docs/standard/io/index.md) [Isolated Storage](../../../docs/standard/io/isolated-storage.md) diff --git a/docs/standard/io/how-to-read-characters-from-a-string.md b/docs/standard/io/how-to-read-characters-from-a-string.md index ed10def6f0e9f..fc5d56a2acd03 100644 --- a/docs/standard/io/how-to-read-characters-from-a-string.md +++ b/docs/standard/io/how-to-read-characters-from-a-string.md @@ -38,7 +38,7 @@ The following code examples show how to read characters synchronously and asynch ## See Also - + [Asynchronous File I/O](../../../docs/standard/io/asynchronous-file-i-o.md) [NIB: How to: Create a Directory Listing](http://msdn.microsoft.com/en-us/4d2772b1-b991-4532-a8a6-6ef733277e69) [How to: Read and Write to a Newly Created Data File](../../../docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md) diff --git a/docs/standard/io/how-to-read-text-from-a-file.md b/docs/standard/io/how-to-read-text-from-a-file.md index 27eff711ed54a..d7f04509dabce 100644 --- a/docs/standard/io/how-to-read-text-from-a-file.md +++ b/docs/standard/io/how-to-read-text-from-a-file.md @@ -39,8 +39,8 @@ The following examples show how to read text synchronously and asynchronously fr ## See Also - - + + [Asynchronous File I/O](../../../docs/standard/io/asynchronous-file-i-o.md) [NIB: How to: Create a Directory Listing](http://msdn.microsoft.com/en-us/4d2772b1-b991-4532-a8a6-6ef733277e69) [Quickstart: Reading and writing files](http://msdn.microsoft.com/library/windows/apps/hh758325.aspx) diff --git a/docs/standard/io/how-to-write-characters-to-a-string.md b/docs/standard/io/how-to-write-characters-to-a-string.md index 56cf37588e7a2..eff7c1efe9189 100644 --- a/docs/standard/io/how-to-write-characters-to-a-string.md +++ b/docs/standard/io/how-to-write-characters-to-a-string.md @@ -36,7 +36,7 @@ The following code examples write characters synchronously and asynchronously fr ## See Also - + [File and Stream I-O](../../../docs/standard/io/index.md) [Asynchronous File I/O](../../../docs/standard/io/asynchronous-file-i-o.md) diff --git a/docs/standard/io/how-to-write-text-to-a-file.md b/docs/standard/io/how-to-write-text-to-a-file.md index 5e11e1695b79a..3ed9db35eb484 100644 --- a/docs/standard/io/how-to-write-text-to-a-file.md +++ b/docs/standard/io/how-to-write-text-to-a-file.md @@ -84,7 +84,7 @@ This topic shows different ways you can write text to a file for .NET Framework ## See Also - + [How to: Enumerate Directories and Files](../../../docs/standard/io/how-to-enumerate-directories-and-files.md) [How to: Read and Write to a Newly Created Data File](../../../docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md) [How to: Open and Append to a Log File](../../../docs/standard/io/how-to-open-and-append-to-a-log-file.md) diff --git a/docs/standard/io/index.md b/docs/standard/io/index.md index 1b3035fe7d85e..c348e2ccd6a45 100644 --- a/docs/standard/io/index.md +++ b/docs/standard/io/index.md @@ -27,7 +27,7 @@ File and stream I/O (input/output) refers to the transfer of data either to or f A file is an ordered and named collection of bytes that has persistent storage. When you work with files, you work with directory paths, disk storage, and file and directory names. In contrast, a stream is a sequence of bytes that you can use to read from and write to a backing store, which can be one of several storage mediums (for example, disks or memory). Just as there are several backing stores other than disks, there are several kinds of streams other than file streams, such as network, memory, and pipe streams. ## Files and Directories - You can use the types in the namespace to interact with files and directories. For example, you can get and set properties for files and directories, and retrieve collections of files and directories based on search criteria. + You can use the types in the namespace to interact with files and directories. For example, you can get and set properties for files and directories, and retrieve collections of files and directories based on search criteria. Here are some commonly used file and directory classes: @@ -41,7 +41,7 @@ File and stream I/O (input/output) refers to the transfer of data either to or f - - provides methods and properties for processing directory strings in a cross-platform manner. - In addition to using these classes, Visual Basic users can use the methods and properties provided by the class for file I/O. + In addition to using these classes, Visual Basic users can use the methods and properties provided by the class for file I/O. See [How to: Copy Directories](../../../docs/standard/io/how-to-copy-directories.md), [How to: Create a Directory Listing](http://msdn.microsoft.com/en-us/4d2772b1-b991-4532-a8a6-6ef733277e69), and [How to: Enumerate Directories and Files](../../../docs/standard/io/how-to-enumerate-directories-and-files.md). @@ -77,7 +77,7 @@ File and stream I/O (input/output) refers to the transfer of data either to or f For an example of working with streams asynchronously, see [Asynchronous File I/O](../../../docs/standard/io/asynchronous-file-i-o.md). ## Readers and Writers - The namespace also provides types for reading encoded characters from streams and writing them to streams. Typically, streams are designed for byte input and output. The reader and writer types handle the conversion of the encoded characters to and from bytes so the stream can complete the operation. Each reader and writer class is associated with a stream, which can be retrieved through the class's `BaseStream` property. + The namespace also provides types for reading encoded characters from streams and writing them to streams. Typically, streams are designed for byte input and output. The reader and writer types handle the conversion of the encoded characters to and from bytes so the stream can complete the operation. Each reader and writer class is associated with a stream, which can be retrieved through the class's `BaseStream` property. Here are some commonly used reader and writer classes: @@ -99,7 +99,7 @@ File and stream I/O (input/output) refers to the transfer of data either to or f For more information, see [Asynchronous File I/O](../../../docs/standard/io/asynchronous-file-i-o.md). ## Compression - Compression refers to the process of reducing the size of a file for storage. Decompression is the process of extracting the contents of a compressed file so they are in a usable format. The namespace contains types for compressing and decompressing files and streams. + Compression refers to the process of reducing the size of a file for storage. Decompression is the process of extracting the contents of a compressed file so they are in a usable format. The namespace contains types for compressing and decompressing files and streams. The following classes are frequently used when compressing and decompressing files and streams: @@ -150,7 +150,7 @@ File and stream I/O (input/output) refers to the transfer of data either to or f For more information about I/O operations in a [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] app, see [Quickstart: Reading and writing a file](http://go.microsoft.com/fwlink/p/?LinkId=243072) in the Windows Dev Center. ## I/O and Security - When you use the classes in the namespace, you must follow operating system security requirements such as access control lists (ACLs) to control access to files and directories. This requirement is in addition to any requirements. You can manage ACLs programmatically. For more information, see [How to: Add or Remove Access Control List Entries](../../../docs/standard/io/how-to-add-or-remove-access-control-list-entries.md). + When you use the classes in the namespace, you must follow operating system security requirements such as access control lists (ACLs) to control access to files and directories. This requirement is in addition to any requirements. You can manage ACLs programmatically. For more information, see [How to: Add or Remove Access Control List Entries](../../../docs/standard/io/how-to-add-or-remove-access-control-list-entries.md). Default security policies prevent Internet or intranet applications from accessing files on the user’s computer. Therefore, do not use the I/O classes that require a path to a physical file when writing code that will be downloaded over the Internet or intranet. Instead, use [isolated storage](../../../docs/standard/io/isolated-storage.md) for traditional .NET Framework applications, or use [application data](http://go.microsoft.com/fwlink/?LinkId=229175) for [!INCLUDE[win8_appname_long](../../../includes/win8-appname-long-md.md)] apps. diff --git a/docs/standard/io/isolated-storage.md b/docs/standard/io/isolated-storage.md index e7267dfd1986e..8a71b4edb6380 100644 --- a/docs/standard/io/isolated-storage.md +++ b/docs/standard/io/isolated-storage.md @@ -121,9 +121,9 @@ manager: "wpickett" ## Creating, Enumerating, and Deleting Isolated Storage The .NET Framework provides three classes in the namespace to help you perform tasks that involve isolated storage: -- , derives from and provides basic management of stored assembly and application files. An instance of the class represents a single store located in the file system. +- , derives from and provides basic management of stored assembly and application files. An instance of the class represents a single store located in the file system. -- derives from and provides access to the files in a store. +- derives from and provides access to the files in a store. - is an enumeration that enables you to create and select a store with the appropriate isolation type. @@ -162,8 +162,8 @@ manager: "wpickett" |-----------|-----------------| |[Types of Isolation](../../../docs/standard/io/types-of-isolation.md)|Describes the different types of isolation.| |[How to: Obtain Stores for Isolated Storage](../../../docs/standard/io/how-to-obtain-stores-for-isolated-storage.md)|Provides an example of using the class to obtain a store isolated by user and assembly.| -|[How to: Enumerate Stores for Isolated Storage](../../../docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md)|Shows how to use the method to calculate the size of all isolated storage for the user.| -|[How to: Delete Stores in Isolated Storage](../../../docs/standard/io/how-to-delete-stores-in-isolated-storage.md)|Shows how to use the method in two different ways to delete isolated stores.| +|[How to: Enumerate Stores for Isolated Storage](../../../docs/standard/io/how-to-enumerate-stores-for-isolated-storage.md)|Shows how to use the method to calculate the size of all isolated storage for the user.| +|[How to: Delete Stores in Isolated Storage](../../../docs/standard/io/how-to-delete-stores-in-isolated-storage.md)|Shows how to use the method in two different ways to delete isolated stores.| |[How to: Anticipate Out-of-Space Conditions with Isolated Storage](../../../docs/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage.md)|Shows how to measure the remaining space in an isolated store.| |[How to: Create Files and Directories in Isolated Storage](../../../docs/standard/io/how-to-create-files-and-directories-in-isolated-storage.md)|Provides some examples of creating files and directories in an isolated store.| |[How to: Find Existing Files and Directories in Isolated Storage](../../../docs/standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md)|Demonstrates how to read the directory structure and files in isolated storage.| @@ -173,10 +173,10 @@ manager: "wpickett" ## Reference - + - + - + - + diff --git a/docs/standard/io/memory-mapped-files.md b/docs/standard/io/memory-mapped-files.md index a2b6b61787ce3..8d49429a693c5 100644 --- a/docs/standard/io/memory-mapped-files.md +++ b/docs/standard/io/memory-mapped-files.md @@ -51,22 +51,22 @@ Multiple and overlapped views to a memory-mapped file |Task|Methods or properties to use| |----------|----------------------------------| -|To obtain a object that represents a persisted memory-mapped file from a file on disk.| method.| -|To obtain a object that represents a non-persisted memory-mapped file (not associated with a file on disk).| method.

- or -

method.| -|To obtain a object of an existing memory-mapped file (either persisted or non-persisted).| method.| -|To obtain a object for a sequentially accessed view to the memory-mapped file.| method.| -|To obtain a object for a random access view to a memory-mapped fie.| method.| -|To obtain a object to use with unmanaged code.| property.

- or -

property.

- or -

property.| -|To delay allocating memory until a view is created (non-persisted files only).

(To determine the current system page size, use the property.)| method with the value.

- or -

methods that have a enumeration as a parameter.| +|To obtain a object that represents a persisted memory-mapped file from a file on disk.| method.| +|To obtain a object that represents a non-persisted memory-mapped file (not associated with a file on disk).| method.

- or -

method.| +|To obtain a object of an existing memory-mapped file (either persisted or non-persisted).| method.| +|To obtain a object for a sequentially accessed view to the memory-mapped file.| method.| +|To obtain a object for a random access view to a memory-mapped fie.| method.| +|To obtain a object to use with unmanaged code.| property.

- or -

property.

- or -

property.| +|To delay allocating memory until a view is created (non-persisted files only).

(To determine the current system page size, use the property.)| method with the value.

- or -

methods that have a enumeration as a parameter.| ### Security You can apply access rights when you create a memory-mapped file, by using the following methods that take a enumeration as a parameter: -- +- -- +- -- +- You can specify access rights for opening an existing memory-mapped file by using the methods that take an as a parameter. diff --git a/docs/standard/io/types-of-isolation.md b/docs/standard/io/types-of-isolation.md index 28ac0212085ff..fcf2a63aed006 100644 --- a/docs/standard/io/types-of-isolation.md +++ b/docs/standard/io/types-of-isolation.md @@ -34,7 +34,7 @@ Access to isolated storage is always restricted to the user who created it. To i - Assembly identity is the evidence of the assembly. This might come from a cryptographic digital signature, which can be the assembly's [strong name](../../../docs/framework/app-domains/strong-named-assemblies.md), the software publisher of the assembly, or its URL identity. If an assembly has both a strong name and a software publisher identity, then the software publisher identity is used. If the assembly comes from the Internet and is unsigned, the URL identity is used. For more information about assemblies and strong names, see [Programming with Assemblies](../../../docs/framework/app-domains/programming-with-assemblies.md). -- Roaming stores move with a user that has a roaming user profile. Files are written to a network directory and are downloaded to any computer the user logs into. For more information about roaming user profiles, see . +- Roaming stores move with a user that has a roaming user profile. Files are written to a network directory and are downloaded to any computer the user logs into. For more information about roaming user profiles, see . By combining the concepts of user, domain, and assembly identity, isolated storage can isolate data in the following ways, each of which has its own usage scenarios: @@ -56,7 +56,7 @@ Types of isolated storage ## Isolation by User and Assembly - When the assembly that uses the data store needs to be accessible from any application's domain, isolation by user and assembly is appropriate. Typically, in this situation, isolated storage is used to store data that applies across multiple applications and is not tied to any particular application, such as the user's name or license information. To access storage isolated by user and assembly, code must be trusted to transfer information between applications. Typically, isolation by user and assembly is allowed on intranets but not on the Internet. Calling the static method and passing in a user and an assembly returns storage with this kind of isolation. + When the assembly that uses the data store needs to be accessible from any application's domain, isolation by user and assembly is appropriate. Typically, in this situation, isolated storage is used to store data that applies across multiple applications and is not tied to any particular application, such as the user's name or license information. To access storage isolated by user and assembly, code must be trusted to transfer information between applications. Typically, isolation by user and assembly is allowed on intranets but not on the Internet. Calling the static method and passing in a user and an assembly returns storage with this kind of isolation. The following code example retrieves a store that is isolated by user and assembly. The store can be accessed through the `isoFile` object. diff --git a/docs/standard/language-independence-and-language-independent-components.md b/docs/standard/language-independence-and-language-independent-components.md index cefd86f862c9d..e5a75818fa319 100644 --- a/docs/standard/language-independence-and-language-independent-components.md +++ b/docs/standard/language-independence-and-language-independent-components.md @@ -106,20 +106,20 @@ The .NET Framework is language independent. This means that, as a developer, you |Accessibility|[Member accessibility](#MemberAccess)|Accessibility shall not be changed when overriding inherited methods, except when overriding a method inherited from a different assembly with accessibility `family-or-assembly`. In this case, the override shall have accessibility `family`.|10| |Accessibility|[Member accessibility](#MemberAccess)|The visibility and accessibility of types and members shall be such that types in the signature of any member shall be visible and accessible whenever the member itself is visible and accessible. For example, a public method that is visible outside its assembly shall not have an argument whose type is visible only within the assembly. The visibility and accessibility of types composing an instantiated generic type used in the signature of any member shall be visible and accessible whenever the member itself is visible and accessible. For example, an instantiated generic type present in the signature of a member that is visible outside its assembly shall not have a generic argument whose type is visible only within the assembly.|12| |Arrays|[Arrays](#arrays)|Arrays shall have elements with a CLS-compliant type, and all dimensions of the array shall have lower bounds of zero. Only the fact that an item is an array and the element type of the array shall be required to distinguish between overloads. When overloading is based on two or more array types the element types shall be named types.|16| -|Attributes|[Attributes](#attributes)|Attributes shall be of type , or a type inheriting from it.|41| -|Attributes|[Attributes](#attributes)|The CLS only allows a subset of the encodings of custom attributes. The only types that shall appear in these encodings are (see Partition IV): , , , , , , , , , , and any enumeration type based on a CLS-compliant base integer type.|34| +|Attributes|[Attributes](#attributes)|Attributes shall be of type , or a type inheriting from it.|41| +|Attributes|[Attributes](#attributes)|The CLS only allows a subset of the encodings of custom attributes. The only types that shall appear in these encodings are (see Partition IV): , , , , , , , , , , and any enumeration type based on a CLS-compliant base integer type.|34| |Attributes|[Attributes](#attributes)|The CLS does not allow publicly visible required modifiers (`modreq`, see Partition II), but does allow optional modifiers (`modopt`, see Partition II) it does not understand.|35| |Constructors|[Constructors](#ctors)|An object constructor shall call some instance constructor of its base class before any access occurs to inherited instance data. (This does not apply to value types, which need not have constructors.)|21| |Constructors|[Constructors](#ctors)|An object constructor shall not be called except as part of the creation of an object, and an object shall not be initialized twice.|22| |Enumerations|[Enumerations](#enums)|The underlying type of an enum shall be a built-in CLS integer type, the name of the field shall be "value__", and that field shall be marked `RTSpecialName`.|7| -|Enumerations|[Enumerations](#enums)|There are two distinct kinds of enums, indicated by the presence or absence of the (see Partition IV Library) custom attribute. One represents named integer values; the other represents named bit flags that can be combined to generate an unnamed value. The value of an `enum` is not limited to the specified values.|8| +|Enumerations|[Enumerations](#enums)|There are two distinct kinds of enums, indicated by the presence or absence of the (see Partition IV Library) custom attribute. One represents named integer values; the other represents named bit flags that can be combined to generate an unnamed value. The value of an `enum` is not limited to the specified values.|8| |Enumerations|[Enumerations](#enums)|Literal static fields of an enum shall have the type of the enum itself.|9| |Events|[Events](#events)|The methods that implement an event shall be marked `SpecialName` in themetadata.|29| |Events|[Events](#events)|The accessibility of an event and of its accessors shall be identical.|30| |Events|[Events](#events)|The `add` and `remove` methods for an event shall both either be present or absent.|31| -|Events|[Events](#events)|The `add` and `remove` methods for an event shall each take one parameter whose type defines the type of the event and that shall be derived from .|32| +|Events|[Events](#events)|The `add` and `remove` methods for an event shall each take one parameter whose type defines the type of the event and that shall be derived from .|32| |Events|[Events](#events)|Events shall adhere to a specific naming pattern. The `SpecialName` attribute referred to in CLS rule 29 shall be ignored in appropriate name comparisons and shall adhere to identifier rules.|33| -|Exceptions|[Exceptions](#exceptions)|Objects that are thrown shall be of type or a type inheriting from it. Nonetheless, CLS-compliant methods are not required to block the propagation of other types of exceptions.|40| +|Exceptions|[Exceptions](#exceptions)|Objects that are thrown shall be of type or a type inheriting from it. Nonetheless, CLS-compliant methods are not required to block the propagation of other types of exceptions.|40| |General|[CLS compliance: the Rules](#Rules)|CLS rules apply only to those parts of a type that are accessible or visible outsideof the defining assembly.|1| |General|[CLS compliance: the Rules](#Rules)|Members of non-CLS compliant types shall not be marked CLS-compliant.|2| |Generics|[Generic types and members](#Generics)|Nested types shall have at least as many generic parameters as the enclosing type. Generic parameters in a nested type correspond by position to the generic parameters in its enclosing type.|42| @@ -139,7 +139,7 @@ The .NET Framework is language independent. This means that, as a developer, you |Overloading|[Overloads](#overloads)|Only properties and methods can be overloaded.|37| |Overloading|[Overloads](#overloads)|Properties and methods can be overloaded based only on the number and types of their parameters, except the conversion operators named `op_Implicit` and `op_Explicit`, which can also be overloaded based on their return type.|38| |Overloading|--|If two or more CLS-compliant methods declared in a type have the same nameand, for a specific set of type instantiations, they have the same parameter and return types, thenall these methods shall be semantically equivalent at those type instantiations.|48| -|Types|[Type and type member signatures](#Types)| is CLS-compliant. Any other CLS-compliant class shall inherit from a CLS-compliant class.|23| +|Types|[Type and type member signatures](#Types)| is CLS-compliant. Any other CLS-compliant class shall inherit from a CLS-compliant class.|23| |Properties|[Properties](#properties)|The methods that implement the getter and setter methods of a property shallbe marked `SpecialName` in the metadata.|24| |Properties|[Properties](#properties)|A property’s accessors shall all be static, all be virtual, or all be instance.|26| |Properties|[Properties](#properties)|The type of a property shall be the return type of the getter and the type of the last argument of the setter. The types of the parameters of the property shall be the types of the parameters to the getter and the types of all but the final parameter of the setter. All of these types shall be CLS-compliant, and shall not be managed pointers (i.e., shall not be passed by reference).|27| @@ -153,7 +153,7 @@ The .NET Framework is language independent. This means that, as a developer, you ### Types and type member signatures - The type is CLS-compliant and is the base type of all object types in the .NET Framework type system. Inheritance in the .NET Framework is either implicit (for example, the class implicitly inherits from the class) or explicit (for example, the class explicitly inherits from the class, which explicitly inherits from the class, which explicitly inherits from the class). For a derived type to be CLS compliant, its base type must also be CLS-compliant. + The type is CLS-compliant and is the base type of all object types in the .NET Framework type system. Inheritance in the .NET Framework is either implicit (for example, the class implicitly inherits from the class) or explicit (for example, the class explicitly inherits from the class, which explicitly inherits from the class, which explicitly inherits from the class). For a derived type to be CLS compliant, its base type must also be CLS-compliant. The following example shows a derived type whose base type is not CLS-compliant. It defines a base `Counter` class that uses an unsigned 32-bit integer as a counter. Because the class provides counter functionality by wrapping an unsigned integer, the class is marked as non-CLS-compliant. As a result, a derived class, `NonZeroCounter`, is also not CLS-compliant. @@ -227,7 +227,7 @@ The .NET Framework is language independent. This means that, as a developer, you Programming language identifiers, such as the names of namespaces, types, and members, must conform to the [Unicode Standard 3.0, Technical Report 15, Annex 7](http://www.unicode.org/reports/tr15/tr15-18.html). This means that: -- The first character of an identifier can be any Unicode uppercase letter, lowercase letter, title case letter, modifier letter, other letter, or letter number. For information on Unicode character categories, see the enumeration. +- The first character of an identifier can be any Unicode uppercase letter, lowercase letter, title case letter, modifier letter, other letter, or letter number. For information on Unicode character categories, see the enumeration. - Subsequent characters can be from any of the categories as the first character, and can also include non-spacing marks, spacing combining marks, decimal numbers, connector punctuations, and formatting codes. @@ -318,19 +318,19 @@ The .NET Framework is language independent. This means that, as a developer, you [!code-csharp[Conceptual.CLSCompliant#7](../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.clscompliant/cs/enum3.cs#7)] [!code-vb[Conceptual.CLSCompliant#7](../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.clscompliant/vb/enum3.vb#7)] -- An enumeration type must have a single instance field named `Value__` that is marked with the attribute. This enables you to reference the field value implicitly. +- An enumeration type must have a single instance field named `Value__` that is marked with the attribute. This enables you to reference the field value implicitly. - An enumeration includes literal static fields whose types match the type of the enumeration itself. For example, if you define a `State` enumeration with values of `State.On` and `State.Off`, `State.On` and `State.Off` are both literal static fields whose type is `State`. - There are two kinds of enumerations: - - An enumeration that represents a set of mutually exclusive, named integer values. This type of enumeration is indicated by the absence of the custom attribute. + - An enumeration that represents a set of mutually exclusive, named integer values. This type of enumeration is indicated by the absence of the custom attribute. - - An enumeration that represents a set of bit flags that can combine to generate an unnamed value. This type of enumeration is indicated by the presence of the custom attribute. + - An enumeration that represents a set of bit flags that can combine to generate an unnamed value. This type of enumeration is indicated by the presence of the custom attribute. For more information, see the documentation for the structure. -- The value of an enumeration is not limited to the range of its specified values. In other words, the range of values in an enumeration is the range of its underlying value. You can use the method to determine whether a specified value is a member of an enumeration. +- The value of an enumeration is not limited to the range of its specified values. In other words, the range of values in an enumeration is the range of its underlying value. You can use the method to determine whether a specified value is a member of an enumeration. ### Type members in general @@ -356,7 +356,7 @@ The .NET Framework is language independent. This means that, as a developer, you ### Generic types and members Nested types always have at least as many generic parameters as their enclosing type. These correspond by position to the generic parameters in the enclosing type. The generic type can also include new generic parameters. - The relationship between the generic type parameters of a containing type and its nested types may be hidden by the syntax of individual languages. In the following example, a generic type `Outer` contains two nested classes, `Inner1A` and `Inner1B`. The calls to the `ToString` method, which each class inherits from , show that each nested class includes the type parameters of its containing class. + The relationship between the generic type parameters of a containing type and its nested types may be hidden by the syntax of individual languages. In the following example, a generic type `Outer` contains two nested classes, `Inner1A` and `Inner1B`. The calls to the `ToString` method, which each class inherits from , show that each nested class includes the type parameters of its containing class. [!code-csharp[Conceptual.CLSCompliant#29](../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.clscompliant/cs/nestedgenerics2.cs#29)] [!code-vb[Conceptual.CLSCompliant#29](../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.clscompliant/vb/nestedgenerics2.vb#29)] @@ -396,7 +396,7 @@ The .NET Framework is language independent. This means that, as a developer, you [!code-csharp[Conceptual.CLSCompliant#11](../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.clscompliant/cs/ctor1.cs#11)] [!code-vb[Conceptual.CLSCompliant#11](../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.clscompliant/vb/ctor1.vb#11)] -- An object constructor cannot be called except to create an object. In addition, an object cannot be initialized twice. For example, this means that and deserialization methods such as must not call constructors. +- An object constructor cannot be called except to create an object. In addition, an object cannot be initialized twice. For example, this means that and deserialization methods such as must not call constructors. ### Properties @@ -410,11 +410,11 @@ The .NET Framework is language independent. This means that, as a developer, you ### Events - An event is defined by its name and its type. The event type is a delegate that is used to indicate the event. For example, the event is of type . In addition to the event itself, three methods with names based on the event name provide the event's implementation and are marked as `SpecialName` in the assembly's metadata: + An event is defined by its name and its type. The event type is a delegate that is used to indicate the event. For example, the event is of type . In addition to the event itself, three methods with names based on the event name provide the event's implementation and are marked as `SpecialName` in the assembly's metadata: -- A method for adding an event handler, named `add_`*EventName*. For example, the event subscription method for the event is named `add_AssemblyResolve`. +- A method for adding an event handler, named `add_`*EventName*. For example, the event subscription method for the event is named `add_AssemblyResolve`. -- A method for removing an event handler, named `remove_`*EventName*. For example, the removal method for the event is named `remove_AssemblyResolve`. +- A method for removing an event handler, named `remove_`*EventName*. For example, the removal method for the event is named `remove_AssemblyResolve`. - A method for indicating that the event has occurred, named `raise_`*EventName*. @@ -443,21 +443,21 @@ The .NET Framework is language independent. This means that, as a developer, you ### Exceptions - Exception objects must derive from or from another type derived from . The following example illustrates the compiler error that results when a custom class named `ErrorClass` is used for exception handling. + Exception objects must derive from or from another type derived from . The following example illustrates the compiler error that results when a custom class named `ErrorClass` is used for exception handling. [!code-csharp[Conceptual.CLSCompliant#13](../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.clscompliant/cs/exceptions1.cs#13)] [!code-vb[Conceptual.CLSCompliant#13](../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.clscompliant/vb/exceptions1.vb#13)] - To correct this error, the `ErrorClass` class must inherit from . In addition, the `Message` property must be overridden. The following example corrects these errors to define an `ErrorClass` class that is CLS-compliant. + To correct this error, the `ErrorClass` class must inherit from . In addition, the `Message` property must be overridden. The following example corrects these errors to define an `ErrorClass` class that is CLS-compliant. [!code-csharp[Conceptual.CLSCompliant#14](../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.clscompliant/cs/exceptions2.cs#14)] [!code-vb[Conceptual.CLSCompliant#14](../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.clscompliant/vb/exceptions2.vb#14)] ### Attributes - In.NET Framework assemblies, custom attributes provide an extensible mechanism for storing custom attributes and retrieving metadata about programming objects, such as assemblies, types, members, and method parameters. Custom attributes must derive from or from a type derived from . + In.NET Framework assemblies, custom attributes provide an extensible mechanism for storing custom attributes and retrieving metadata about programming objects, such as assemblies, types, members, and method parameters. Custom attributes must derive from or from a type derived from . - The following example violates this rule. It defines a `NumericAttribute` class that does not derive from . Note that a compiler error results only when the non-CLS-compliant attribute is applied, not when the class is defined. + The following example violates this rule. It defines a `NumericAttribute` class that does not derive from . Note that a compiler error results only when the non-CLS-compliant attribute is applied, not when the class is defined. [!code-csharp[Conceptual.CLSCompliant#18](../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.clscompliant/cs/attribute1.cs#18)] [!code-vb[Conceptual.CLSCompliant#18](../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.clscompliant/vb/attribute1.vb#18)] @@ -493,7 +493,7 @@ The .NET Framework is language independent. This means that, as a developer, you ## The CLSCompliantAttribute attribute - The attribute is used to indicate whether a program element complies with the Common Language Specification. The constructor includes a single required parameter, `isCompliant`, that indicates whether the program element is CLS-compliant. + The attribute is used to indicate whether a program element complies with the Common Language Specification. The constructor includes a single required parameter, `isCompliant`, that indicates whether the program element is CLS-compliant. At compile time, the compiler detects non-compliant elements that are presumed to be CLS-compliant and emits a warning. The compiler does not emit warnings for types or members that are explicitly declared to be non-compliant. @@ -506,7 +506,7 @@ The .NET Framework is language independent. This means that, as a developer, you > [!WARNING] > In some cases, language compilers enforce CLS-compliant rules regardless of whether the attribute is used. For example, defining a static member in an interface violates a CLS rule. However, if you define a `static` (in C#) or `Shared` (in Visual Basic) member in an interface, both the C# and Visual Basic compilers display an error message and fail to compile the app. - The attribute is marked with an attribute that has a value of . This value allows you to apply the attribute to any program element, including assemblies, modules, types (classes, structures, enumerations, interfaces, and delegates), type members (constructors, methods, properties, fields, and events), parameters, generic parameters, and return values. However, in practice, you should apply the attribute only to assemblies, types, and type members. Otherwise, compilers ignore the attribute and continue to generate compiler warnings whenever they encounter a non-compliant parameter, generic parameter, or return value in your library's public interface. + The attribute is marked with an attribute that has a value of . This value allows you to apply the attribute to any program element, including assemblies, modules, types (classes, structures, enumerations, interfaces, and delegates), type members (constructors, methods, properties, fields, and events), parameters, generic parameters, and return values. However, in practice, you should apply the attribute only to assemblies, types, and type members. Otherwise, compilers ignore the attribute and continue to generate compiler warnings whenever they encounter a non-compliant parameter, generic parameter, or return value in your library's public interface. The value of the attribute is inherited by contained program elements. For example, if an assembly is marked as CLS-compliant, its types are also CLS-compliant. If a type is marked as CLS-compliant, its nested types and members are also CLS-compliant. diff --git a/docs/standard/numerics.md b/docs/standard/numerics.md index 4c10b3f4f73ef..cf4d55a637b03 100644 --- a/docs/standard/numerics.md +++ b/docs/standard/numerics.md @@ -32,14 +32,14 @@ The .NET Framework supports the standard numeric integral and floating-point pri |Type|Signed/Unsigned|Size (bytes)|Minimum value|Maximum Value| |----------|----------------------|--------------------|-------------------|-------------------| -||Unsigned|1|0|255| -||Signed|2|-32,768|32,767| -||Signed|4|-2,147,483,648|2,147,483,647| -||Signed|8|-9,223,372,036,854,775,808|9,223,372,036,854,775,807| -||Signed|1|-128|127| -||Unsigned|2|0|65,535| -||Unsigned|4|0|4,294,967,295| -||Unsigned|8|0|18,446,744,073,709,551,615| +||Unsigned|1|0|255| +||Signed|2|-32,768|32,767| +||Signed|4|-2,147,483,648|2,147,483,647| +||Signed|8|-9,223,372,036,854,775,808|9,223,372,036,854,775,807| +||Signed|1|-128|127| +||Unsigned|2|0|65,535| +||Unsigned|4|0|4,294,967,295| +||Unsigned|8|0|18,446,744,073,709,551,615| Each integral type supports a standard set of arithmetic, comparison, equality, explicit conversion, and implicit conversion operators. Each integer also includes methods to perform equality comparisons and relative comparisons, to convert the string representation of a number to that integer, and to convert an integer to its string representation. Some additional mathematical operations beyond those handled by the standard operators, such as rounding and identifying the smaller or larger value of two integers, are available from the class. You can also work with the individual bits in an integer value by using the class. @@ -50,16 +50,16 @@ The .NET Framework supports the standard numeric integral and floating-point pri |Type|Size (in bytes)|Minimum|Maximum| |----------|-----------------------|-------------|-------------| -||8|-1.79769313486232e308|1.79769313486232e308| -||4|-3.402823e38|3.402823e38| -||16|-79,228,162,514,264,337,593,543,950,335|79,228,162,514,264,337,593,543,950,335| +||8|-1.79769313486232e308|1.79769313486232e308| +||4|-3.402823e38|3.402823e38| +||16|-79,228,162,514,264,337,593,543,950,335|79,228,162,514,264,337,593,543,950,335| - Each floating-point type supports a standard set of arithmetic, comparison, equality, explicit conversion, and implicit conversion operators. Each also includes methods to perform equality comparisons and relative comparisons, to convert the string representation of a floating-point number, and to convert a floating-point number to its string representation. Some additional mathematical, algebraic, and trigonometric operations are available from the class. You can also work with the individual bits in and values by using the class. The structure has its own methods, and , for working with a decimal value's individual bits, as well as its own set of methods for performing some additional mathematical operations. + Each floating-point type supports a standard set of arithmetic, comparison, equality, explicit conversion, and implicit conversion operators. Each also includes methods to perform equality comparisons and relative comparisons, to convert the string representation of a floating-point number, and to convert a floating-point number to its string representation. Some additional mathematical, algebraic, and trigonometric operations are available from the class. You can also work with the individual bits in and values by using the class. The structure has its own methods, and , for working with a decimal value's individual bits, as well as its own set of methods for performing some additional mathematical operations. - The and types are intended to be used for values that by their nature are imprecise (such as the distance between two stars in the solar system) and for applications in which a high degree of precision and small rounding error is not required. You should use the type for cases in which greater precision is required and rounding error is undesirable, + The and types are intended to be used for values that by their nature are imprecise (such as the distance between two stars in the solar system) and for applications in which a high degree of precision and small rounding error is not required. You should use the type for cases in which greater precision is required and rounding error is undesirable, ## BigInteger - is an immutable type that represents an arbitrarily large integer whose value in theory has no upper or lower bounds. The methods of the type closely parallel those of the other integral types. + is an immutable type that represents an arbitrarily large integer whose value in theory has no upper or lower bounds. The methods of the type closely parallel those of the other integral types. ## Complex The type represents a complex number, that is, a number with a real number part and an imaginary number part. It supports a standard set of arithmetic, comparison, equality, explicit conversion, and implicit conversion operators, as well as mathematical, algebraic, and trigonometric methods. diff --git a/docs/standard/parallel-programming/attached-and-detached-child-tasks.md b/docs/standard/parallel-programming/attached-and-detached-child-tasks.md index 87eff2425eef8..1a652d72ada58 100644 --- a/docs/standard/parallel-programming/attached-and-detached-child-tasks.md +++ b/docs/standard/parallel-programming/attached-and-detached-child-tasks.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Attached and Detached Child Tasks -A *child task* (or *nested task*) is a instance that is created in the user delegate of another task, which is known as the *parent task*. A child task can be either detached or attached. A *detached child task* is a task that executes independently of its parent. An *attached child task* is a nested task that is created with the option whose parent does not explicitly or by default prohibit it from being attached. A task may create any number of attached and detached child tasks, limited only by system resources. +A *child task* (or *nested task*) is a instance that is created in the user delegate of another task, which is known as the *parent task*. A child task can be either detached or attached. A *detached child task* is a task that executes independently of its parent. An *attached child task* is a nested task that is created with the option whose parent does not explicitly or by default prohibit it from being attached. A task may create any number of attached and detached child tasks, limited only by system resources. The following table lists the basic differences between the two kinds of child tasks. @@ -27,7 +27,7 @@ A *child task* (or *nested task*) is a option to create an attached child task. + In most scenarios, we recommend that you use detached child tasks, because their relationships with other tasks are less complex. That is why tasks created inside parent tasks are detached by default, and you must explicitly specify the option to create an attached child task. ## Detached child tasks Although a child task is created by a parent task, by default it is independent of the parent task. In the following example, a parent task creates one simple child task. If you run the example code multiple times, you may notice that the output from the example differs from that shown, and also that the output may change each time you run the code. This occurs because the parent task and child tasks execute independently of each other; the child is a detached task. The example waits only for the parent task to complete, and the child task may not execute or complete before the console app terminates. @@ -35,26 +35,26 @@ A *child task* (or *nested task*) is a object rather than a object, you can ensure that the parent task will wait for the child to complete by accessing the property of the child even if it is a detached child task. The property blocks until its task completes, as the following example shows. + If the child task is represented by a object rather than a object, you can ensure that the parent task will wait for the child to complete by accessing the property of the child even if it is a detached child task. The property blocks until its task completes, as the following example shows. [!code-csharp[TPL_ChildTasks#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_childtasks/cs/childtasks.cs#4)] [!code-vb[TPL_ChildTasks#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/tpl_childtasks.vb#4)] ## Attached child tasks - Unlike detached child tasks, attached child tasks are closely synchronized with the parent. You can change the detached child task in the previous example to an attached child task by using the option in the task creation statement, as shown in the following example. In this code, the attached child task completes before its parent. As a result, the output from the example is the same each time you run the code. + Unlike detached child tasks, attached child tasks are closely synchronized with the parent. You can change the detached child task in the previous example to an attached child task by using the option in the task creation statement, as shown in the following example. In this code, the attached child task completes before its parent. As a result, the output from the example is the same each time you run the code. [!code-csharp[TPL_ChildTasks#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_childtasks/cs/child1.cs#2)] [!code-vb[TPL_ChildTasks#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/child1.vb#2)] You can use attached child tasks to create tightly synchronized graphs of asynchronous operations. - However, a child task can attach to its parent only if its parent does not prohibit attached child tasks. Parent tasks can explicitly prevent child tasks from attaching to them by specifying the option in the parent task's class constructor or the method. Parent tasks implicitly prevent child tasks from attaching to them if they are created by calling the method. The following example illustrates this. It is identical to the previous example, except that the parent task is created by calling the method rather than the method. Because the child task is not able to attach to its parent, the output from the example is unpredictable. Because the default task creation options for the overloads include , this example is functionally equivalent to the first example in the "Detached child tasks" section. + However, a child task can attach to its parent only if its parent does not prohibit attached child tasks. Parent tasks can explicitly prevent child tasks from attaching to them by specifying the option in the parent task's class constructor or the method. Parent tasks implicitly prevent child tasks from attaching to them if they are created by calling the method. The following example illustrates this. It is identical to the previous example, except that the parent task is created by calling the method rather than the method. Because the child task is not able to attach to its parent, the output from the example is unpredictable. Because the default task creation options for the overloads include , this example is functionally equivalent to the first example in the "Detached child tasks" section. [!code-csharp[TPL_ChildTasks#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_childtasks/cs/child1a.cs#3)] [!code-vb[TPL_ChildTasks#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_childtasks/vb/child1a.vb#3)] ## Exceptions in child tasks - If a detached child task throws an exception, that exception must be observed or handled directly in the parent task just as with any non-nested task. If an attached child task throws an exception, the exception is automatically propagated to the parent task and back to the thread that waits or tries to access the task's property. Therefore, by using attached child tasks, you can handle all exceptions at just one point in the call to on the calling thread. For more information, see [Exception Handling](../../../docs/standard/parallel-programming/exception-handling-task-parallel-library.md). + If a detached child task throws an exception, that exception must be observed or handled directly in the parent task just as with any non-nested task. If an attached child task throws an exception, the exception is automatically propagated to the parent task and back to the thread that waits or tries to access the task's property. Therefore, by using attached child tasks, you can handle all exceptions at just one point in the call to on the calling thread. For more information, see [Exception Handling](../../../docs/standard/parallel-programming/exception-handling-task-parallel-library.md). ## Cancellation and child tasks Task cancellation is cooperative. That is, to be cancelable, every attached or detached child task must monitor the status of the cancellation token. If you want to cancel a parent and all its children by using one cancellation request, you pass the same token as an argument to all tasks and provide in each task the logic to respond to the request in each task. For more information, see [Task Cancellation](../../../docs/standard/parallel-programming/task-cancellation.md) and [How to: Cancel a Task and Its Children](../../../docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md). @@ -71,9 +71,9 @@ A *child task* (or *nested task*) is a object. If the third-party library component also creates a object and specifies to attach it to the parent task, any unhandled exceptions that occur in the child task propagate to the parent. This could lead to unexpected behavior in the main app. + An unhandled exception that is thrown by a child task is propagated to the parent task. You can use this behavior to observe all child task exceptions from one root task instead of traversing a tree of tasks. However, exception propagation can be problematic when a parent task does not expect attachment from other code. For example, consider an app that calls a third-party library component from a object. If the third-party library component also creates a object and specifies to attach it to the parent task, any unhandled exceptions that occur in the child task propagate to the parent. This could lead to unexpected behavior in the main app. - To prevent a child task from attaching to its parent task, specify the option when you create the parent or object. When a task tries to attach to its parent and the parent specifies the option, the child task will not be able to attach to a parent and will execute just as if the option was not specified. + To prevent a child task from attaching to its parent task, specify the option when you create the parent or object. When a task tries to attach to its parent and the parent specifies the option, the child task will not be able to attach to a parent and will execute just as if the option was not specified. You might also want to prevent a child task from attaching to its parent when the child task does not finish in a timely manner. Because a parent task does not finish until all child tasks finish, a long-running child task can cause the overall app to perform poorly. For an example that shows how to improve app performance by preventing a task from attaching to its parent task, see [How to: Prevent a Child Task from Attaching to its Parent](../../../docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md). diff --git a/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md b/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md index b7f5c8a84ae74..fb87716db4681 100644 --- a/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md +++ b/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md @@ -38,61 +38,61 @@ In asynchronous programming, it is very common for one asynchronous operation, o - Use a continuation to handle exceptions thrown by the antecedent. ## About continuations - A continuation is a task that is created in the state. It is activated automatically when its antecedent task or tasks complete. Calling on a continuation in user code throws an exception. + A continuation is a task that is created in the state. It is activated automatically when its antecedent task or tasks complete. Calling on a continuation in user code throws an exception. - A continuation is itself a and does not block the thread on which it is started. Call the method to block until the continuation task finishes. + A continuation is itself a and does not block the thread on which it is started. Call the method to block until the continuation task finishes. ## Creating a continuation for a single antecedent - You create a continuation that executes when its antecedent has completed by calling the method. The following example shows the basic pattern, (for clarity, exception handling is omitted). It executes an antecedent task, `taskA`, that returns a object that indicates the name of the current day of the week. When the antecedent finishes, the continuation task, `taskB`, is passed the antecedent and displays a string that includes its result. + You create a continuation that executes when its antecedent has completed by calling the method. The following example shows the basic pattern, (for clarity, exception handling is omitted). It executes an antecedent task, `taskA`, that returns a object that indicates the name of the current day of the week. When the antecedent finishes, the continuation task, `taskB`, is passed the antecedent and displays a string that includes its result. [!code-csharp[TPL_Continuations#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/simple1.cs#1)] [!code-vb[TPL_Continuations#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/simple1.vb#1)] ## Creating a continuation for multiple antecedents - You can also create a continuation that will run when any or all of a group of tasks has completed. To execute a continuation when all antecedent tasks have completed, you call the static (`Shared` in Visual Basic) method or the instance method. To execute a continuation when any of the antecedent tasks has completed, you call the static (`Shared` in Visual Basic) method or the instance method. + You can also create a continuation that will run when any or all of a group of tasks has completed. To execute a continuation when all antecedent tasks have completed, you call the static (`Shared` in Visual Basic) method or the instance method. To execute a continuation when any of the antecedent tasks has completed, you call the static (`Shared` in Visual Basic) method or the instance method. - Note that calls to the and overloads do not block the calling thread. However, you typically call all but the and methods to retrieve the returned property, which does block the calling thread. + Note that calls to the and overloads do not block the calling thread. However, you typically call all but the and methods to retrieve the returned property, which does block the calling thread. - The following example calls the method to create a continuation task that reflects the results of its ten antecedent tasks. Each antecedent task squares an index value that ranges from one to ten. If the antecedents complete successfully (their property is ), the property of the continuation is an array of the values returned by each antecedent. The example adds them to compute the sum of squares for all numbers between one and ten. + The following example calls the method to create a continuation task that reflects the results of its ten antecedent tasks. Each antecedent task squares an index value that ranges from one to ten. If the antecedents complete successfully (their property is ), the property of the continuation is an array of the values returned by each antecedent. The example adds them to compute the sum of squares for all numbers between one and ten. [!code-csharp[TPL_Continuations#5](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/whenall1.cs#5)] [!code-vb[TPL_Continuations#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/whenall1.vb#5)] ## Continuation options - When you create a single-task continuation, you can use a overload that takes a enumeration value to specify the conditions under which the continuation starts. For example, you can specify that the continuation is to run only if the antecedent completes successfully, or only if it completes in a faulted state. If the condition is not true when the antecedent is ready to invoke the continuation, the continuation transitions directly to the state and cannot be started after that. + When you create a single-task continuation, you can use a overload that takes a enumeration value to specify the conditions under which the continuation starts. For example, you can specify that the continuation is to run only if the antecedent completes successfully, or only if it completes in a faulted state. If the condition is not true when the antecedent is ready to invoke the continuation, the continuation transitions directly to the state and cannot be started after that. - A number of multi-task continuation methods, such as overloads of the method, also include a parameter. Only a subset of all enumeration members are valid, however. You can specify values that have counterparts in the enumeration, such as , , and . If you specify any of the `NotOn` or `OnlyOn` options with a multi-task continuation, an exception will be thrown at run time. + A number of multi-task continuation methods, such as overloads of the method, also include a parameter. Only a subset of all enumeration members are valid, however. You can specify values that have counterparts in the enumeration, such as , , and . If you specify any of the `NotOn` or `OnlyOn` options with a multi-task continuation, an exception will be thrown at run time. For more information on task continuation options, see the topic. ## Passing Data to a Continuation - The method passes a reference to the antecedent to the user delegate of the continuation as an argument. If the antecedent is a object, and the task ran until it was completed, then the continuation can access the property of the task. + The method passes a reference to the antecedent to the user delegate of the continuation as an argument. If the antecedent is a object, and the task ran until it was completed, then the continuation can access the property of the task. - The property blocks until the task has completed. However, if the task was canceled or faulted, attempting to access the property throws an exception. You can avoid this problem by using the option, as shown in the following example. + The property blocks until the task has completed. However, if the task was canceled or faulted, attempting to access the property throws an exception. You can avoid this problem by using the option, as shown in the following example. [!code-csharp[TPL_Continuations#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/result1.cs#2)] [!code-vb[TPL_Continuations#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/result1.vb#2)] - If you want the continuation to run even if the antecedent did not run to successful completion, you must guard against the exception. One approach is to test the property of the antecedent, and only attempt to access the property if the status is not or . You can also examine the property of the antecedent. For more information, see [Exception Handling](../../../docs/standard/parallel-programming/exception-handling-task-parallel-library.md). The following example modifies the previous example to access antecedent's property only if its status is . + If you want the continuation to run even if the antecedent did not run to successful completion, you must guard against the exception. One approach is to test the property of the antecedent, and only attempt to access the property if the status is not or . You can also examine the property of the antecedent. For more information, see [Exception Handling](../../../docs/standard/parallel-programming/exception-handling-task-parallel-library.md). The following example modifies the previous example to access antecedent's property only if its status is . [!code-csharp[TPL_Continuations#7](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/result2.cs#7)] [!code-vb[TPL_Continuations#7](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/result2.vb#7)] ## Canceling a Continuation - The property of a continuation is set to in the following situations: + The property of a continuation is set to in the following situations: - It throws an exception in response to a cancellation request. Just as with any task, if the exception contains the same token that was passed to the continuation, it is treated as an acknowledgement of cooperative cancellation. -- The continuation is passed a whose property is `true`. In this case, the continuation does not start, and it transitions to the state. +- The continuation is passed a whose property is `true`. In this case, the continuation does not start, and it transitions to the state. -- The continuation never runs because the condition set by its argument was not met. For example, if an antecedent goes into a state, its continuation that was passed the option will not run but will transition to the state. +- The continuation never runs because the condition set by its argument was not met. For example, if an antecedent goes into a state, its continuation that was passed the option will not run but will transition to the state. - If a task and its continuation represent two parts of the same logical operation, you can pass the same cancellation token to both tasks, as shown in the following example. It consists of an antecedent that generates a list of integers that are divisible by 33, which it passes to the continuation. The continuation in turn displays the list. Both the antecedent and the continuation pause regularly for random intervals. In addition, a object is used to execute the `Elapsed` method after a five-second timeout interval. This calls the method, which causes the currently executing task to call the method. Whether the method is called when the antecedent or its continuation is executing depends on the duration of the randomly generated pauses. If the antecedent is canceled, the continuation will not start. If the antecedent is not canceled, the token can still be used to cancel the continuation. + If a task and its continuation represent two parts of the same logical operation, you can pass the same cancellation token to both tasks, as shown in the following example. It consists of an antecedent that generates a list of integers that are divisible by 33, which it passes to the continuation. The continuation in turn displays the list. Both the antecedent and the continuation pause regularly for random intervals. In addition, a object is used to execute the `Elapsed` method after a five-second timeout interval. This calls the method, which causes the currently executing task to call the method. Whether the method is called when the antecedent or its continuation is executing depends on the duration of the randomly generated pauses. If the antecedent is canceled, the continuation will not start. If the antecedent is not canceled, the token can still be used to cancel the continuation. [!code-csharp[TPL_Continuations#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/cancellation1.cs#3)] [!code-vb[TPL_Continuations#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/cancellation1.vb#3)] - You can also prevent a continuation from executing if its antecedent is canceled without supplying the continuation a cancellation token by specifying the option when you create the continuation. The following is a simple example. + You can also prevent a continuation from executing if its antecedent is canceled without supplying the continuation a cancellation token by specifying the option when you create the continuation. The following is a simple example. [!code-csharp[TPL_Continuations#8](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/cancellation2.cs#8)] [!code-vb[TPL_Continuations#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/cancellation2.vb#8)] @@ -102,7 +102,7 @@ In asynchronous programming, it is very common for one asynchronous operation, o Continuations that are disposed will not start. ## Continuations and Child Tasks - A continuation does not run until the antecedent and all of its attached child tasks have completed. The continuation does not wait for detached child tasks to finish. The following two examples illustrate child tasks that are attached to and detached from an antecedent that creates a continuation. In the following example, the continuation runs only after all child tasks have completed, and running the example multiple times produces identical output each time. Note that the example launches the antecedent by calling the method, since by default the method creates a parent task whose default task creation option is . + A continuation does not run until the antecedent and all of its attached child tasks have completed. The continuation does not wait for detached child tasks to finish. The following two examples illustrate child tasks that are attached to and detached from an antecedent that creates a continuation. In the following example, the continuation runs only after all child tasks have completed, and running the example multiple times produces identical output each time. Note that the example launches the antecedent by calling the method, since by default the method creates a parent task whose default task creation option is . [!code-csharp[TPL_Continuations#9](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/attached1.cs#9)] [!code-vb[TPL_Continuations#9](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/attached1.vb#9)] @@ -115,9 +115,9 @@ In asynchronous programming, it is very common for one asynchronous operation, o The final status of the antecedent task depends on the final status of any attached child tasks. The status of detached child tasks does not affect the parent. For more information, see [Attached and Detached Child Tasks](../../../docs/standard/parallel-programming/attached-and-detached-child-tasks.md). ## Associating State with Continuations - You can associate arbitrary state with a task continuation. The method provides overloaded versions that each take an value that represents the state of the continuation. You can later access this state object by using the property. This state object is `null` if you do not provide a value. + You can associate arbitrary state with a task continuation. The method provides overloaded versions that each take an value that represents the state of the continuation. You can later access this state object by using the property. This state object is `null` if you do not provide a value. - Continuation state is useful when you convert existing code that uses the [Asynchronous Programming Model (APM)](../../../docs/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm.md) to use the TPL. In the APM, you typically provide object state in the **Begin*Method*** method and later access that state by using the property. By using the method, you can preserve this state when you convert code that uses the APM to use the TPL. + Continuation state is useful when you convert existing code that uses the [Asynchronous Programming Model (APM)](../../../docs/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm.md) to use the TPL. In the APM, you typically provide object state in the **Begin*Method*** method and later access that state by using the property. By using the method, you can preserve this state when you convert code that uses the APM to use the TPL. Continuation state can also be useful when you work with objects in the [!INCLUDE[vsprvs](../../../includes/vsprvs-md.md)] debugger. For example, in the **Parallel Tasks** window, the **Task** column displays the string representation of the state object for each task. For more information about the **Parallel Tasks** window, see [Using the Tasks Window](/visualstudio/debugger/using-the-tasks-window). @@ -139,14 +139,14 @@ In asynchronous programming, it is very common for one asynchronous operation, o [!code-csharp[TPL_Continuations#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/exception2.cs#4)] [!code-vb[TPL_Continuations#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/exception2.vb#4)] - Because it was run with the option, the continuation executes only if an exception occurs in the antecedent, and therefore it can assume that the antecedent's property is not `null`. If the continuation executes whether or not an exception is thrown in the antecedent, it would have to check whether the antecedent's property is not `null` before attempting to handle the exception, as the following code fragment shows. + Because it was run with the option, the continuation executes only if an exception occurs in the antecedent, and therefore it can assume that the antecedent's property is not `null`. If the continuation executes whether or not an exception is thrown in the antecedent, it would have to check whether the antecedent's property is not `null` before attempting to handle the exception, as the following code fragment shows. [!code-csharp[TPL_Continuations#11](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_continuations/cs/exception2.cs#11)] [!code-vb[TPL_Continuations#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_continuations/vb/exception2.vb#11)] For more information, see [Exception Handling](../../../docs/standard/parallel-programming/exception-handling-task-parallel-library.md) and [NIB: How to: Handle Exceptions Thrown by Tasks](http://msdn.microsoft.com/en-us/d6c47ec8-9de9-4880-beb3-ff19ae51565d). -- If the continuation is an attached child task that was created by using the option, its exceptions will be propagated by the parent back to the calling thread, as is the case in any other attached child. For more information, see [Attached and Detached Child Tasks](../../../docs/standard/parallel-programming/attached-and-detached-child-tasks.md). +- If the continuation is an attached child task that was created by using the option, its exceptions will be propagated by the parent back to the calling thread, as is the case in any other attached child. For more information, see [Attached and Detached Child Tasks](../../../docs/standard/parallel-programming/attached-and-detached-child-tasks.md). ## See Also [Task Parallel Library (TPL)](../../../docs/standard/parallel-programming/task-parallel-library-tpl.md) diff --git a/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md b/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md index 609b715d4dadb..b484188fda282 100644 --- a/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md +++ b/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md @@ -29,7 +29,7 @@ To parallelize an operation on a data source, one of the essential steps is to * The TPL partitioners also support a dynamic number of partitions. This means they can create partitions on-the-fly, for example, when the loop spawns a new task. This feature enables the partitioner to scale together with the loop itself. Dynamic partitioners are also inherently load-balancing. When you create a custom partitioner, you must support dynamic partitioning to be consumable from a loop. ### Configuring Load Balancing Partitioners for PLINQ - Some overloads of the method let you create a partitioner for an array or source and specify whether it should attempt to balance the workload among the threads. When the partitioner is configured to load-balance, chunk partitioning is used, and the elements are handed off to each partition in small chunks as they are requested. This approach helps ensure that all partitions have elements to process until the entire loop or query is completed. An additional overload can be used to provide load-balancing partitioning of any source. + Some overloads of the method let you create a partitioner for an array or source and specify whether it should attempt to balance the workload among the threads. When the partitioner is configured to load-balance, chunk partitioning is used, and the elements are handed off to each partition in small chunks as they are requested. This approach helps ensure that all partitions have elements to process until the entire loop or query is completed. An additional overload can be used to provide load-balancing partitioning of any source. In general, load balancing requires the partitions to request elements relatively frequently from the partitioner. By contrast, a partitioner that does static partitioning can assign the elements to each partitioner all at once by using either range or chunk partitioning. This requires less overhead than load balancing, but it might take longer to execute if one thread ends up with significantly more work than the others. By default when it is passed an IList or an array, PLINQ always uses range partitioning without load balancing. To enable load balancing for PLINQ, use the `Partitioner.Create` method, as shown in the following example. @@ -63,7 +63,7 @@ To parallelize an operation on a data source, one of the essential steps is to * ## Custom Partitioners In some scenarios, it might be worthwhile or even required to implement your own partitioner. For example, you might have a custom collection class that you can partition more efficiently than the default partitioners can, based on your knowledge of the internal structure of the class. Or, you may want to create range partitions of varying sizes based on your knowledge of how long it will take to process elements at different locations in the source collection. - To create a basic custom partitioner, derive a class from and override the virtual methods, as described in the following table. + To create a basic custom partitioner, derive a class from and override the virtual methods, as described in the following table. ||| |-|-| @@ -71,7 +71,7 @@ To parallelize an operation on a data source, one of the essential steps is to * ||Return `true` if you implement , otherwise, `false`.| ||If is `true`, this method can optionally be called instead of .| - If the results must be sortable or you require indexed access into the elements, then derive from and override its virtual methods as described in the following table. + If the results must be sortable or you require indexed access into the elements, then derive from and override its virtual methods as described in the following table. ||| |-|-| @@ -85,14 +85,14 @@ To parallelize an operation on a data source, one of the essential steps is to * |Method/Property|IList / Array without Load Balancing|IList / Array with Load Balancing|IEnumerable| |----------------------|-------------------------------------------|----------------------------------------|-----------------| ||Uses range partitioning|Uses chunk partitioning optimized for Lists for the partitionCount specified|Uses chunk partitioning by creating a static number of partitions.| -||Throws not-supported exception|Uses chunk partitioning optimized for Lists and dynamic partitions|Uses chunk partitioning by creating a dynamic number of partitions.| +||Throws not-supported exception|Uses chunk partitioning optimized for Lists and dynamic partitions|Uses chunk partitioning by creating a dynamic number of partitions.| ||Returns `true`|Returns `true`|Returns `true`| ||Returns `true`|Returns `false`|Returns `false`| ||Returns `true`|Returns `true`|Returns `true`| ||Returns `false`|Returns `true`|Returns `true`| ### Dynamic Partitions - If you intend the partitioner to be used in a method, you must be able to return a dynamic number of partitions. This means that the partitioner can supply an enumerator for a new partition on-demand at any time during loop execution. Basically, whenever the loop adds a new parallel task, it requests a new partition for that task. If you require the data to be orderable, then derive from so that each item in each partition is assigned a unique index. + If you intend the partitioner to be used in a method, you must be able to return a dynamic number of partitions. This means that the partitioner can supply an enumerator for a new partition on-demand at any time during loop execution. Basically, whenever the loop adds a new parallel task, it requests a new partition for that task. If you require the data to be orderable, then derive from so that each item in each partition is assigned a unique index. For more information, and an example, see [How to: Implement Dynamic Partitions](../../../docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). diff --git a/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md b/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md index f522af52e3948..e2823670e0367 100644 --- a/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md +++ b/docs/standard/parallel-programming/data-parallelism-task-parallel-library.md @@ -19,7 +19,7 @@ manager: "wpickett" # Data Parallelism (Task Parallel Library) *Data parallelism* refers to scenarios in which the same operation is performed concurrently (that is, in parallel) on elements in a source collection or array. In data parallel operations, the source collection is partitioned so that multiple threads can operate on different segments concurrently. - The Task Parallel Library (TPL) supports data parallelism through the class. This class provides method-based parallel implementations of [for](~/docs/csharp/language-reference/keywords/for.md) and [foreach](~/docs/csharp/language-reference/keywords/foreach-in.md) loops (`For` and `For Each` in Visual Basic). You write the loop logic for a or loop much as you would write a sequential loop. You do not have to create threads or queue work items. In basic loops, you do not have to take locks. The TPL handles all the low-level work for you. For in-depth information about the use of and , download the document [Patterns for Parallel Programming: Understanding and Applying Parallel Patterns with the .NET Framework 4](http://www.microsoft.com/download/details.aspx?id=19222). The following code example shows a simple `foreach` loop and its parallel equivalent. + The Task Parallel Library (TPL) supports data parallelism through the class. This class provides method-based parallel implementations of [for](~/docs/csharp/language-reference/keywords/for.md) and [foreach](~/docs/csharp/language-reference/keywords/foreach-in.md) loops (`For` and `For Each` in Visual Basic). You write the loop logic for a or loop much as you would write a sequential loop. You do not have to create threads or queue work items. In basic loops, you do not have to take locks. The TPL handles all the low-level work for you. For in-depth information about the use of and , download the document [Patterns for Parallel Programming: Understanding and Applying Parallel Patterns with the .NET Framework 4](http://www.microsoft.com/download/details.aspx?id=19222). The following code example shows a simple `foreach` loop and its parallel equivalent. > [!NOTE] > This documentation uses lambda expressions to define delegates in TPL. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](../../../docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md). @@ -32,7 +32,7 @@ manager: "wpickett" > [!NOTE] > You can also supply your own custom partitioner or scheduler. For more information, see [Custom Partitioners for PLINQ and TPL](../../../docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [Task Schedulers](http://msdn.microsoft.com/library/638f8ea5-21db-47a2-a934-86e1e961bf65). - Both the and methods have several overloads that let you stop or break loop execution, monitor the state of the loop on other threads, maintain thread-local state, finalize thread-local objects, control the degree of concurrency, and so on. The helper types that enable this functionality include , , , , and . + Both the and methods have several overloads that let you stop or break loop execution, monitor the state of the loop on other threads, maintain thread-local state, finalize thread-local objects, control the degree of concurrency, and so on. The helper types that enable this functionality include , , , , and . For more information, see [Patterns of Parallel Programming](http://go.microsoft.com/fwlink/p/?LinkId=265491). @@ -47,7 +47,7 @@ manager: "wpickett" |[How to: Stop or Break from a Parallel.For Loop](http://msdn.microsoft.com/en-us/de52e4f1-9346-4ad5-b582-1a4d54dc7f7e)|Describes how to stop or break from a parallel loop so that all threads are informed of the action.| |[How to: Write a Parallel.For Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md)|Describes how to write a loop in which each thread maintains a private variable that is not visible to any other threads, and how to synchronize the results from all threads when the loop completes.| |[How to: Write a Parallel.ForEach Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md)|Describes how to write a loop in which each thread maintains a private variable that is not visible to any other threads, and how to synchronize the results from all threads when the loop completes.| -|[How to: Cancel a Parallel.For or ForEach Loop](../../../docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md)|Describes how to cancel a parallel loop by using a | +|[How to: Cancel a Parallel.For or ForEach Loop](../../../docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md)|Describes how to cancel a parallel loop by using a | |[How to: Speed Up Small Loop Bodies](../../../docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md)|Describes one way to speed up execution when a loop body is very small.| |[Task Parallel Library (TPL)](../../../docs/standard/parallel-programming/task-parallel-library-tpl.md)|Provides an overview of the Task Parallel Library.| |[Parallel Programming](../../../docs/standard/parallel-programming/index.md)|Introduces Parallel Programming in the .NET Framework.| diff --git a/docs/standard/parallel-programming/data-structures-for-parallel-programming.md b/docs/standard/parallel-programming/data-structures-for-parallel-programming.md index 83a09f1bcdfa4..3008191d28a90 100644 --- a/docs/standard/parallel-programming/data-structures-for-parallel-programming.md +++ b/docs/standard/parallel-programming/data-structures-for-parallel-programming.md @@ -20,33 +20,33 @@ manager: "wpickett" The .NET Framework version 4 introduces several new types that are useful in parallel programming, including a set of concurrent collection classes, lightweight synchronization primitives, and types for lazy initialization. You can use these types with any multithreaded application code, including the Task Parallel Library and PLINQ. ## Concurrent Collection Classes - The collection classes in the namespace provide thread-safe add and remove operations that avoid locks wherever possible and use fine-grained locking where locks are necessary. Unlike collections that were introduced in the .NET Framework versions 1.0 and 2.0, a concurrent collection class does not require user code to take any locks when it accesses items. The concurrent collection classes can significantly improve performance over types such as and (with user-implemented locking) in scenarios where multiple threads add and remove items from a collection. + The collection classes in the namespace provide thread-safe add and remove operations that avoid locks wherever possible and use fine-grained locking where locks are necessary. Unlike collections that were introduced in the .NET Framework versions 1.0 and 2.0, a concurrent collection class does not require user code to take any locks when it accesses items. The concurrent collection classes can significantly improve performance over types such as and (with user-implemented locking) in scenarios where multiple threads add and remove items from a collection. The following table lists the new concurrent collection classes: |Type|Description| |----------|-----------------| -||Provides blocking and bounding capabilities for thread-safe collections that implement . Producer threads block if no slots are available or if the collection is full. Consumer threads block if the collection is empty. This type also supports non-blocking access by consumers and producers. can be used as a base class or backing store to provide blocking and bounding for any collection class that supports .| -||A thread-safe bag implementation that provides scalable add and get operations.| -||A concurrent and scalable dictionary type.| -||A concurrent and scalable FIFO queue.| -||A concurrent and scalable LIFO stack.| +||Provides blocking and bounding capabilities for thread-safe collections that implement . Producer threads block if no slots are available or if the collection is full. Consumer threads block if the collection is empty. This type also supports non-blocking access by consumers and producers. can be used as a base class or backing store to provide blocking and bounding for any collection class that supports .| +||A thread-safe bag implementation that provides scalable add and get operations.| +||A concurrent and scalable dictionary type.| +||A concurrent and scalable FIFO queue.| +||A concurrent and scalable LIFO stack.| For more information, see [Thread-Safe Collections](../../../docs/standard/collections/thread-safe/index.md). ## Synchronization Primitives - The new synchronization primitives in the namespace enable fine-grained concurrency and faster performance by avoiding expensive locking mechanisms found in legacy multithreading code. Some of the new types, such as and have no counterparts in earlier releases of the .NET Framework. + The new synchronization primitives in the namespace enable fine-grained concurrency and faster performance by avoiding expensive locking mechanisms found in legacy multithreading code. Some of the new types, such as and have no counterparts in earlier releases of the .NET Framework. The following table lists the new synchronization types: |Type|Description| |----------|-----------------| -||Enables multiple threads to work on an algorithm in parallel by providing a point at which each task can signal its arrival and then block until some or all tasks have arrived. For more information, see [Barrier](../../../docs/standard/threading/barrier.md).| -||Simplifies fork and join scenarios by providing an easy rendezvous mechanism. For more information, see [CountdownEvent](../../../docs/standard/threading/countdownevent.md).| -||A synchronization primitive similar to . is lighter-weight but can only be used for intra-process communication. For more information, see [ManualResetEvent and ManualResetEventSlim](../../../docs/standard/threading/manualresetevent-and-manualreseteventslim.md).| -||A synchronization primitive that limits the number of threads that can concurrently access a resource or a pool of resources. For more information, see [Semaphore and SemaphoreSlim](../../../docs/standard/threading/semaphore-and-semaphoreslim.md).| -||A mutual exclusion lock primitive that causes the thread that is trying to acquire the lock to wait in a loop, or *spin*, for a period of time before yielding its quantum. In scenarios where the wait for the lock is expected to be short, offers better performance than other forms of locking. For more information, see [SpinLock](../../../docs/standard/threading/spinlock.md).| -||A small, lightweight type that will spin for a specified time and eventually put the thread into a wait state if the spin count is exceeded. For more information, see [SpinWait](../../../docs/standard/threading/spinwait.md).| +||Enables multiple threads to work on an algorithm in parallel by providing a point at which each task can signal its arrival and then block until some or all tasks have arrived. For more information, see [Barrier](../../../docs/standard/threading/barrier.md).| +||Simplifies fork and join scenarios by providing an easy rendezvous mechanism. For more information, see [CountdownEvent](../../../docs/standard/threading/countdownevent.md).| +||A synchronization primitive similar to . is lighter-weight but can only be used for intra-process communication. For more information, see [ManualResetEvent and ManualResetEventSlim](../../../docs/standard/threading/manualresetevent-and-manualreseteventslim.md).| +||A synchronization primitive that limits the number of threads that can concurrently access a resource or a pool of resources. For more information, see [Semaphore and SemaphoreSlim](../../../docs/standard/threading/semaphore-and-semaphoreslim.md).| +||A mutual exclusion lock primitive that causes the thread that is trying to acquire the lock to wait in a loop, or *spin*, for a period of time before yielding its quantum. In scenarios where the wait for the lock is expected to be short, offers better performance than other forms of locking. For more information, see [SpinLock](../../../docs/standard/threading/spinlock.md).| +||A small, lightweight type that will spin for a specified time and eventually put the thread into a wait state if the spin count is exceeded. For more information, see [SpinWait](../../../docs/standard/threading/spinwait.md).| For more information, see: @@ -61,16 +61,16 @@ The .NET Framework version 4 introduces several new types that are useful in par |Type|Description| |----------|-----------------| -||Provides lightweight, thread-safe lazy-initialization.| -||Provides a lazily-initialized value on a per-thread basis, with each thread lazily-invoking the initialization function.| -||Provides static methods that avoid the need to allocate a dedicated, lazy-initialization instance. Instead, they use references to ensure targets have been initialized as they are accessed.| +||Provides lightweight, thread-safe lazy-initialization.| +||Provides a lazily-initialized value on a per-thread basis, with each thread lazily-invoking the initialization function.| +||Provides static methods that avoid the need to allocate a dedicated, lazy-initialization instance. Instead, they use references to ensure targets have been initialized as they are accessed.| For more information, see [Lazy Initialization](../../../docs/framework/performance/lazy-initialization.md). ## Aggregate Exceptions - The type can be used to capture multiple exceptions that are thrown concurrently on separate threads, and return them to the joining thread as a single exception. The and types and PLINQ use extensively for this purpose. For more information, see [NIB: How to: Handle Exceptions Thrown by Tasks](http://msdn.microsoft.com/en-us/d6c47ec8-9de9-4880-beb3-ff19ae51565d) and [How to: Handle Exceptions in a PLINQ Query](../../../docs/standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query.md). + The type can be used to capture multiple exceptions that are thrown concurrently on separate threads, and return them to the joining thread as a single exception. The and types and PLINQ use extensively for this purpose. For more information, see [NIB: How to: Handle Exceptions Thrown by Tasks](http://msdn.microsoft.com/en-us/d6c47ec8-9de9-4880-beb3-ff19ae51565d) and [How to: Handle Exceptions in a PLINQ Query](../../../docs/standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query.md). ## See Also - - + + [Parallel Programming](../../../docs/standard/parallel-programming/index.md) diff --git a/docs/standard/parallel-programming/dataflow-task-parallel-library.md b/docs/standard/parallel-programming/dataflow-task-parallel-library.md index b90f81d79e1df..23064296ee315 100644 --- a/docs/standard/parallel-programming/dataflow-task-parallel-library.md +++ b/docs/standard/parallel-programming/dataflow-task-parallel-library.md @@ -23,7 +23,7 @@ manager: "wpickett" This document provides an overview of the TPL Dataflow Library. It describes the programming model, the predefined dataflow block types, and how to configure dataflow blocks to meet the specific requirements of your applications. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. This document contains the following sections: @@ -40,32 +40,32 @@ manager: "wpickett" The TPL Dataflow Library provides a foundation for message passing and parallelizing CPU-intensive and I/O-intensive applications that have high throughput and low latency. It also gives you explicit control over how data is buffered and moves around the system. To better understand the dataflow programming model, consider an application that asynchronously loads images from disk and creates a composite of those images. Traditional programming models typically require that you use callbacks and synchronization objects, such as locks, to coordinate tasks and access to shared data. By using the dataflow programming model, you can create dataflow objects that process images as they are read from disk. Under the dataflow model, you declare how data is handled when it becomes available, and also any dependencies between data. Because the runtime manages dependencies between data, you can often avoid the requirement to synchronize access to shared data. In addition, because the runtime schedules work based on the asynchronous arrival of data, dataflow can improve responsiveness and throughput by efficiently managing the underlying threads. For an example that uses the dataflow programming model to implement image processing in a Windows Forms application, see [Walkthrough: Using Dataflow in a Windows Forms Application](../../../docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md). ### Sources and Targets - The TPL Dataflow Library consists of *dataflow blocks*, which are data structures that buffer and process data. The TPL defines three kinds of dataflow blocks: *source blocks*, *target blocks*, and *propagator blocks*. A source block acts as a source of data and can be read from. A target block acts as a receiver of data and can be written to. A propagator block acts as both a source block and a target block, and can be read from and written to. The TPL defines the interface to represent sources, to represent targets, and to represent propagators. inherits from both , and . + The TPL Dataflow Library consists of *dataflow blocks*, which are data structures that buffer and process data. The TPL defines three kinds of dataflow blocks: *source blocks*, *target blocks*, and *propagator blocks*. A source block acts as a source of data and can be read from. A target block acts as a receiver of data and can be written to. A propagator block acts as both a source block and a target block, and can be read from and written to. The TPL defines the interface to represent sources, to represent targets, and to represent propagators. inherits from both , and . The TPL Dataflow Library provides several predefined dataflow block types that implement the , , and interfaces. These dataflow block types are described in this document in the section [Predefined Dataflow Block Types](#predefined_types). ### Connecting Blocks - You can connect dataflow blocks to form *pipelines*, which are linear sequences of dataflow blocks, or *networks*, which are graphs of dataflow blocks. A pipeline is one form of network. In a pipeline or network, sources asynchronously propagate data to targets as that data becomes available. The method links a source dataflow block to a target block. A source can be linked to zero or more targets; targets can be linked from zero or more sources. You can add or remove dataflow blocks to or from a pipeline or network concurrently. The predefined dataflow block types handle all thread-safety aspects of linking and unlinking. + You can connect dataflow blocks to form *pipelines*, which are linear sequences of dataflow blocks, or *networks*, which are graphs of dataflow blocks. A pipeline is one form of network. In a pipeline or network, sources asynchronously propagate data to targets as that data becomes available. The method links a source dataflow block to a target block. A source can be linked to zero or more targets; targets can be linked from zero or more sources. You can add or remove dataflow blocks to or from a pipeline or network concurrently. The predefined dataflow block types handle all thread-safety aspects of linking and unlinking. For an example that connects dataflow blocks to form a basic pipeline, see [Walkthrough: Creating a Dataflow Pipeline](../../../docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md). For an example that connects dataflow blocks to form a more complex network, see [Walkthrough: Using Dataflow in a Windows Forms Application](../../../docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md). For an example that unlinks a target from a source after the source offers the target a message, see [How to: Unlink Dataflow Blocks](../../../docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md). #### Filtering - When you call the method to link a source to a target, you can supply a delegate that determines whether the target block accepts or rejects a message based on the value of that message. This filtering mechanism is a useful way to guarantee that a dataflow block receives only certain values. For most of the predefined dataflow block types, if a source block is connected to multiple target blocks, when a target block rejects a message, the source offers that message to the next target. The order in which a source offers messages to targets is defined by the source and can vary according to the type of the source. Most source block types stop offering a message after one target accepts that message. One exception to this rule is the class, which offers each message to all targets, even if some targets reject the message. For an example that uses filtering to process only certain messages, see [Walkthrough: Using Dataflow in a Windows Forms Application](../../../docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md). + When you call the method to link a source to a target, you can supply a delegate that determines whether the target block accepts or rejects a message based on the value of that message. This filtering mechanism is a useful way to guarantee that a dataflow block receives only certain values. For most of the predefined dataflow block types, if a source block is connected to multiple target blocks, when a target block rejects a message, the source offers that message to the next target. The order in which a source offers messages to targets is defined by the source and can vary according to the type of the source. Most source block types stop offering a message after one target accepts that message. One exception to this rule is the class, which offers each message to all targets, even if some targets reject the message. For an example that uses filtering to process only certain messages, see [Walkthrough: Using Dataflow in a Windows Forms Application](../../../docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md). > [!IMPORTANT] > Because each predefined source dataflow block type guarantees that messages are propagated out in the order in which they are received, every message must be read from the source block before the source block can process the next message. Therefore, when you use filtering to connect multiple targets to a source, make sure that at least one target block receives each message. Otherwise, your application might deadlock. ### Message Passing - The dataflow programming model is related to the concept of *message passing*, where independent components of a program communicate with one another by sending messages. One way to propagate messages among application components is to call the and methods to send messages to target dataflow blocks post ( acts synchronously; acts asynchronously) and the , , and methods to receive messages from source blocks. You can combine these methods with dataflow pipelines or networks by sending input data to the head node (a target block), and receiving output data from the terminal node of the pipeline or the terminal nodes of the network (one or more source blocks). You can also use the method to read from the first of the provided sources that has data available and perform action on that data. + The dataflow programming model is related to the concept of *message passing*, where independent components of a program communicate with one another by sending messages. One way to propagate messages among application components is to call the and methods to send messages to target dataflow blocks post ( acts synchronously; acts asynchronously) and the , , and methods to receive messages from source blocks. You can combine these methods with dataflow pipelines or networks by sending input data to the head node (a target block), and receiving output data from the terminal node of the pipeline or the terminal nodes of the network (one or more source blocks). You can also use the method to read from the first of the provided sources that has data available and perform action on that data. - Source blocks offer data to target blocks by calling the method. The target block responds to an offered message in one of three ways: it can accept the message, decline the message, or postpone the message. When the target accepts the message, the method returns . When the target declines the message, the method returns . When the target requires that it no longer receives any messages from the source, returns . The predefined source block types do not offer messages to linked targets after such a return value is received, and they automatically unlink from such targets. + Source blocks offer data to target blocks by calling the method. The target block responds to an offered message in one of three ways: it can accept the message, decline the message, or postpone the message. When the target accepts the message, the method returns . When the target declines the message, the method returns . When the target requires that it no longer receives any messages from the source, returns . The predefined source block types do not offer messages to linked targets after such a return value is received, and they automatically unlink from such targets. - When a target block postpones the message for later use, the method returns . A target block that postpones a message can later calls the method to try to reserve the offered message. At this point, the message is either still available and can be used by the target block, or the message has been taken by another target. When the target block later requires the message or no longer needs the message, it calls the or method, respectively. Message reservation is typically used by the dataflow block types that operate in non-greedy mode. Non-greedy mode is explained later in this document. Instead of reserving a postponed message, a target block can also use the method to attempt to directly consume the postponed message. + When a target block postpones the message for later use, the method returns . A target block that postpones a message can later calls the method to try to reserve the offered message. At this point, the message is either still available and can be used by the target block, or the message has been taken by another target. When the target block later requires the message or no longer needs the message, it calls the or method, respectively. Message reservation is typically used by the dataflow block types that operate in non-greedy mode. Non-greedy mode is explained later in this document. Instead of reserving a postponed message, a target block can also use the method to attempt to directly consume the postponed message. ### Dataflow Block Completion - Dataflow blocks also support the concept of *completion*. A dataflow block that is in the completed state does not perform any further work. Each dataflow block has an associated object, known as a *completion task*, that represents the completion status of the block. Because you can wait for a object to finish, by using completion tasks, you can wait for one or more terminal nodes of a dataflow network to finish. The interface defines the method, which informs the dataflow block of a request for it to complete, and the property, which returns the completion task for the dataflow block. Both and inherit the interface. + Dataflow blocks also support the concept of *completion*. A dataflow block that is in the completed state does not perform any further work. Each dataflow block has an associated object, known as a *completion task*, that represents the completion status of the block. Because you can wait for a object to finish, by using completion tasks, you can wait for one or more terminal nodes of a dataflow network to finish. The interface defines the method, which informs the dataflow block of a request for it to complete, and the property, which returns the completion task for the dataflow block. Both and inherit the interface. - There are two ways to determine whether a dataflow block completed without error, encountered one or more errors, or was canceled. The first way is to call the method on the completion task in a `try`-`catch` block (`Try`-`Catch` in Visual Basic). The following example creates an object that throws if its input value is less than zero. is thrown when this example calls on the completion task. The is accessed through the property of the object. + There are two ways to determine whether a dataflow block completed without error, encountered one or more errors, or was canceled. The first way is to call the method on the completion task in a `try`-`catch` block (`Try`-`Catch` in Visual Basic). The following example creates an object that throws if its input value is less than zero. is thrown when this example calls on the completion task. The is accessed through the property of the object. [!code-csharp[TPLDataflow_Overview#10](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#10)] [!code-vb[TPLDataflow_Overview#10](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#10)] @@ -74,7 +74,7 @@ manager: "wpickett" When a dataflow block is canceled explicitly, the object contains in the property. For more information about dataflow cancellation, see Enabling Cancellation later in this document. - The second way to determine the completion status of a dataflow block is to use a continuation off of the completion task, or to use the asynchronous language features of C# and Visual Basic to asynchronously wait for the completion task. The delegate that you provide to the method takes a object that represents the antecedent task. In the case of the property, the delegate for the continuation takes the completion task itself. The following example resembles the previous one, except that it also uses the method to create a completion task that prints the status of the overall dataflow operation. + The second way to determine the completion status of a dataflow block is to use a continuation off of the completion task, or to use the asynchronous language features of C# and Visual Basic to asynchronously wait for the completion task. The delegate that you provide to the method takes a object that represents the antecedent task. In the case of the property, the delegate for the continuation takes the completion task itself. The following example resembles the previous one, except that it also uses the method to create a completion task that prints the status of the overall dataflow operation. [!code-csharp[TPLDataflow_Overview#11](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_overview/cs/program.cs#11)] [!code-vb[TPLDataflow_Overview#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_overview/vb/program.vb#11)] @@ -88,7 +88,7 @@ manager: "wpickett" The TPL Dataflow Library provides several predefined dataflow block types. These types are divided into three categories: *buffering blocks*, *execution blocks*, and *grouping blocks*. The following sections describe the block types that make up these categories. ### Buffering Blocks - Buffering blocks hold data for use by data consumers. The TPL Dataflow Library provides three buffering block types: , , and . + Buffering blocks hold data for use by data consumers. The TPL Dataflow Library provides three buffering block types: , , and . #### BufferBlock(T) The class represents a general-purpose asynchronous messaging structure. This class stores a first in, first out (FIFO) queue of messages that can be written to by multiple sources or read from by multiple targets. When a target receives a message from a object, that message is removed from the message queue. Therefore, although a object can have multiple targets, only one target will receive each message. The class is useful when you want to pass multiple messages to another component, and that component must receive each message. @@ -121,7 +121,7 @@ manager: "wpickett" For a complete example that demonstrates how to use to receive the value of the first operation that finishes, see [How to: Unlink Dataflow Blocks](../../../docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md). ### Execution Blocks - Execution blocks call a user-provided delegate for each piece of received data. The TPL Dataflow Library provides three execution block types: , , and . + Execution blocks call a user-provided delegate for each piece of received data. The TPL Dataflow Library provides three execution block types: , , and . #### ActionBlock(T) The class is a target block that calls a delegate when it receives data. Think of a object as a delegate that runs asynchronously when data becomes available. The delegate that you provide to an object can be of type or type `System.Func\`. When you use an object with , processing of each input element is considered completed when the delegate returns. When you use an object with `System.Func\`, processing of each input element is considered completed only when the returned object is completed. By using these two mechanisms, you can use for both synchronous and asynchronous processing of each input element. @@ -183,7 +183,7 @@ manager: "wpickett" For a complete example that uses to improve the efficiency of database insert operations, see [Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency](../../../docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md). #### JoinBlock(T1, T2, ...) - The and classes collect input elements and propagate out or objects that contain those elements. The and classes do not inherit from . Instead, they provide properties, , , and , that implement . + The and classes collect input elements and propagate out or objects that contain those elements. The and classes do not inherit from . Instead, they provide properties, , , and , that implement . Like , and operate in either greedy or non-greedy mode. In greedy mode, which is the default, a or object accepts every message that it is offered and propagates out a tuple after each of its targets receives at least one message. In non-greedy mode, a or object postpones all incoming messages until all targets have been offered the data that is required to create a tuple. At this point, the block engages in a two-phase commit protocol to atomically retrieve all required items from the sources. This postponement makes it possible for another entity to consume the data in the meantime, to allow the overall system to make forward progress. @@ -208,7 +208,7 @@ manager: "wpickett" ## Configuring Dataflow Block Behavior - You can enable additional options by providing a object to the constructor of dataflow block types. These options control behavior such the scheduler that manages the underlying task and the degree of parallelism. The also has derived types that specify behavior that is specific to certain dataflow block types. The following table summarizes which options type is associated with each dataflow block type. + You can enable additional options by providing a object to the constructor of dataflow block types. These options control behavior such the scheduler that manages the underlying task and the degree of parallelism. The also has derived types that specify behavior that is specific to certain dataflow block types. The following table summarizes which options type is associated with each dataflow block type. |Dataflow Block Type| type| |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -222,7 +222,7 @@ manager: "wpickett" ||| ||| - The following sections provide additional information about the important kinds of dataflow block options that are available through the , , and classes. + The following sections provide additional information about the important kinds of dataflow block options that are available through the , , and classes. ### Specifying the Task Scheduler Every predefined dataflow block uses the TPL task scheduling mechanism to perform activities such as propagating data to a target, receiving data from a source, and running user-defined delegates when data becomes available. is an abstract class that represents a task scheduler that queues tasks onto threads. The default task scheduler, , uses the class to queue and execute work. You can override the default task scheduler by setting the property when you construct a dataflow block object. @@ -230,9 +230,9 @@ manager: "wpickett" When the same task scheduler manages multiple dataflow blocks, it can enforce policies across them. For example, if multiple dataflow blocks are each configured to target the exclusive scheduler of the same object, all work that runs across these blocks is serialized. Similarly, if these blocks are configured to target the concurrent scheduler of the same object, and that scheduler is configured to have a maximum concurrency level, all work from these blocks is limited to that number of concurrent operations. For an example that uses the class to enable read operations to occur in parallel, but write operations to occur exclusively of all other operations, see [How to: Specify a Task Scheduler in a Dataflow Block](../../../docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md). For more information about task schedulers in the TPL, see the class topic. ### Specifying the Degree of Parallelism - By default, the three execution block types that the TPL Dataflow Library provides, , , and , process one message at a time. These dataflow block types also process messages in the order in which they are received. To enable these dataflow blocks to process messages concurrently, set the property when you construct the dataflow block object. + By default, the three execution block types that the TPL Dataflow Library provides, , , and , process one message at a time. These dataflow block types also process messages in the order in which they are received. To enable these dataflow blocks to process messages concurrently, set the property when you construct the dataflow block object. - The default value of is 1, which guarantees that the dataflow block processes one message at a time. Setting this property to a value that is larger than 1 enables the dataflow block to process multiple messages concurrently. Setting this property to enables the underlying task scheduler to manage the maximum degree of concurrency. + The default value of is 1, which guarantees that the dataflow block processes one message at a time. Setting this property to a value that is larger than 1 enables the dataflow block to process multiple messages concurrently. Setting this property to enables the underlying task scheduler to manage the maximum degree of concurrency. > [!IMPORTANT] > When you specify a maximum degree of parallelism that is larger than 1, multiple messages are processed simultaneously, and therefore, messages might not be processed in the order in which they are received. The order in which the messages are output from the block will, however, be correctly ordered. @@ -244,7 +244,7 @@ manager: "wpickett" For an example that sets the maximum degree of parallelism to enable lengthy operations to occur in parallel, see [How to: Specify the Degree of Parallelism in a Dataflow Block](../../../docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md). ### Specifying the Number of Messages per Task - The predefined dataflow block types use tasks to process multiple input elements. This helps minimize the number of task objects that are required to process data, which enables applications to run more efficiently. However, when the tasks from one set of dataflow blocks are processing data, the tasks from other dataflow blocks might need to wait for processing time by queuing messages. To enable better fairness among dataflow tasks, set the property. When is set to , which is the default, the task used by a dataflow block processes as many messages as are available. When is set to a value other than , the dataflow block processes at most this number of messages per object. Although setting the property can increase fairness among tasks, it can cause the system to create more tasks than are necessary, which can decrease performance. + The predefined dataflow block types use tasks to process multiple input elements. This helps minimize the number of task objects that are required to process data, which enables applications to run more efficiently. However, when the tasks from one set of dataflow blocks are processing data, the tasks from other dataflow blocks might need to wait for processing time by queuing messages. To enable better fairness among dataflow tasks, set the property. When is set to , which is the default, the task used by a dataflow block processes as many messages as are available. When is set to a value other than , the dataflow block processes at most this number of messages per object. Although setting the property can increase fairness among tasks, it can cause the system to create more tasks than are necessary, which can decrease performance. ### Enabling Cancellation The TPL provides a mechanism that enables tasks to coordinate cancellation in a cooperative manner. To enable dataflow blocks to participate in this cancellation mechanism, set the property. When this object is set to the canceled state, all dataflow blocks that monitor this token finish execution of their current item but do not start processing subsequent items. These dataflow blocks also clear any buffered messages, release connections to any source and target blocks, and transition to the canceled state. By transitioning to the canceled state, the property has the property set to , unless an exception occurred during processing. In that case, is set to . diff --git a/docs/standard/parallel-programming/exception-handling-task-parallel-library.md b/docs/standard/parallel-programming/exception-handling-task-parallel-library.md index ed7599adf1d4e..72a3765529888 100644 --- a/docs/standard/parallel-programming/exception-handling-task-parallel-library.md +++ b/docs/standard/parallel-programming/exception-handling-task-parallel-library.md @@ -17,9 +17,9 @@ ms.author: "ronpet" manager: "wpickett" --- # Exception Handling (Task Parallel Library) -Unhandled exceptions that are thrown by user code that is running inside a task are propagated back to the calling thread, except in certain scenarios that are described later in this topic. Exceptions are propagated when you use one of the static or instance or `Wait` methods, and you handle them by enclosing the call in a `try`/`catch` statement. If a task is the parent of attached child tasks, or if you are waiting on multiple tasks, multiple exceptions could be thrown. +Unhandled exceptions that are thrown by user code that is running inside a task are propagated back to the calling thread, except in certain scenarios that are described later in this topic. Exceptions are propagated when you use one of the static or instance or `Wait` methods, and you handle them by enclosing the call in a `try`/`catch` statement. If a task is the parent of attached child tasks, or if you are waiting on multiple tasks, multiple exceptions could be thrown. - To propagate all the exceptions back to the calling thread, the Task infrastructure wraps them in an instance. The exception has an property that can be enumerated to examine all the original exceptions that were thrown, and handle (or not handle) each one individually. You can also handle the original exceptions by using the method. + To propagate all the exceptions back to the calling thread, the Task infrastructure wraps them in an instance. The exception has an property that can be enumerated to examine all the original exceptions that were thrown, and handle (or not handle) each one individually. You can also handle the original exceptions by using the method. Even if only one exception is thrown, it is still wrapped in an exception, as the following example shows. @@ -28,7 +28,7 @@ Unhandled exceptions that are thrown by user code that is running inside a task You could avoid an unhandled exception by just catching the and not observing any of the inner exceptions. However, we recommend that you do not do this because it is analogous to catching the base type in non-parallel scenarios. To catch an exception without taking specific actions to recover from it can leave your program in an indeterminate state. - If you do not want to call the or `Wait` method to wait for a task's completion, you can also retrieve the exception from the task's property, as the following example shows. For more information, see the [Observing Exceptions By Using the Task.Exception Property](#ExceptionProp) section in this topic. + If you do not want to call the or `Wait` method to wait for a task's completion, you can also retrieve the exception from the task's property, as the following example shows. For more information, see the [Observing Exceptions By Using the Task.Exception Property](#ExceptionProp) section in this topic. [!code-csharp[TPL_Exceptions#29](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/handling22.cs#29)] [!code-vb[TPL_Exceptions#29](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/handling22.vb#29)] @@ -41,12 +41,12 @@ Unhandled exceptions that are thrown by user code that is running inside a task > When "Just My Code" is enabled, Visual Studio in some cases will break on the line that throws the exception and display an error message that says "exception not handled by user code." This error is benign. You can press F5 to continue and see the exception-handling behavior that is demonstrated in these examples. To prevent Visual Studio from breaking on the first error, just uncheck the **Enable Just My Code** checkbox under **Tools, Options, Debugging, General**. ## Attached Child Tasks and Nested AggregateExceptions - If a task has an attached child task that throws an exception, that exception is wrapped in an before it is propagated to the parent task, which wraps that exception in its own before it propagates it back to the calling thread. In such cases, the property of the exception that is caught at the or `Wait` or or method contains one or more instances, not the original exceptions that caused the fault. To avoid having to iterate over nested exceptions, you can use the method to remove all the nested exceptions, so that the property contains the original exceptions. In the following example, nested instances are flattened and handled in just one loop. + If a task has an attached child task that throws an exception, that exception is wrapped in an before it is propagated to the parent task, which wraps that exception in its own before it propagates it back to the calling thread. In such cases, the property of the exception that is caught at the or `Wait` or or method contains one or more instances, not the original exceptions that caused the fault. To avoid having to iterate over nested exceptions, you can use the method to remove all the nested exceptions, so that the property contains the original exceptions. In the following example, nested instances are flattened and handled in just one loop. [!code-csharp[TPL_Exceptions#22](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/flatten2.cs#22)] [!code-vb[TPL_Exceptions#22](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/flatten2.vb#22)] - You can also use the method to rethrow the inner exceptions from multiple instances thrown by multiple tasks in a single instance, as the following example shows. + You can also use the method to rethrow the inner exceptions from multiple instances thrown by multiple tasks in a single instance, as the following example shows. [!code-csharp[TPL_Exceptions#13](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/taskexceptions2.cs#13)] [!code-vb[TPL_Exceptions#13](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/taskexceptions2.vb#13)] @@ -66,21 +66,21 @@ Unhandled exceptions that are thrown by user code that is running inside a task [!code-vb[TPL_Exceptions#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/tpl_exceptions.vb#4)] ## Using the Handle Method to Filter Inner Exceptions - You can use the method to filter out exceptions that you can treat as "handled" without using any further logic. In the user delegate that is supplied to the method, you can examine the exception type, its property, or any other information about it that will let you determine whether it is benign. Any exceptions for which the delegate returns `false` are rethrown in a new instance immediately after the method returns. + You can use the method to filter out exceptions that you can treat as "handled" without using any further logic. In the user delegate that is supplied to the method, you can examine the exception type, its property, or any other information about it that will let you determine whether it is benign. Any exceptions for which the delegate returns `false` are rethrown in a new instance immediately after the method returns. - The following example is functionally equivalent to the first example in this topic, which examines each exception in the collection. Instead, this exception handler calls the method object for each exception, and only rethrows exceptions that are not `CustomException` instances. + The following example is functionally equivalent to the first example in this topic, which examines each exception in the collection. Instead, this exception handler calls the method object for each exception, and only rethrows exceptions that are not `CustomException` instances. [!code-csharp[TPL_Exceptions#26](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/handlemethod21.cs#26)] [!code-vb[TPL_Exceptions#26](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/handlemethod21.vb#26)] - The following is a more complete example that uses the method to provide special handling for an exception when enumerating files. + The following is a more complete example that uses the method to provide special handling for an exception when enumerating files. [!code-csharp[TPL_Exceptions#12](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/taskexceptions.cs#12)] [!code-vb[TPL_Exceptions#12](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/taskexceptions.vb#12)] ## Observing Exceptions by Using the Task.Exception Property - If a task completes in the state, its property can be examined to discover which specific exception caused the fault. A good way to observe the property is to use a continuation that runs only if the antecedent task faults, as shown in the following example. + If a task completes in the state, its property can be examined to discover which specific exception caused the fault. A good way to observe the property is to use a continuation that runs only if the antecedent task faults, as shown in the following example. [!code-csharp[TPL_Exceptions#27](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/exceptionprop21.cs#27)] [!code-vb[TPL_Exceptions#27](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/exceptionprop21.vb#27)] @@ -88,7 +88,7 @@ Unhandled exceptions that are thrown by user code that is running inside a task In a real application, the continuation delegate could log detailed information about the exception and possibly spawn new tasks to recover from the exception. ## UnobservedTaskException Event - In some scenarios, such as when hosting untrusted plug-ins, benign exceptions might be common, and it might be too difficult to manually observe them all. In these cases, you can handle the event. The instance that is passed to your handler can be used to prevent the unobserved exception from being propagated back to the joining thread. + In some scenarios, such as when hosting untrusted plug-ins, benign exceptions might be common, and it might be too difficult to manually observe them all. In these cases, you can handle the event. The instance that is passed to your handler can be used to prevent the unobserved exception from being propagated back to the joining thread. ## See Also [Task Parallel Library (TPL)](../../../docs/standard/parallel-programming/task-parallel-library-tpl.md) diff --git a/docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md b/docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md index d23de2b75cf10..f94bc1fede7b2 100644 --- a/docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md +++ b/docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md @@ -22,7 +22,7 @@ manager: "wpickett" This document demonstrates how to enable cancellation in your application. This example uses Windows Forms to show where work items are active in a dataflow pipeline and also the effects of cancellation. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ### To Create the Windows Forms Application @@ -63,7 +63,7 @@ This document demonstrates how to enable cancellation in your application. This [!code-csharp[TPLDataflow_CancellationWinForms#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_cancellationwinforms/cs/cancellationwinforms/form1.cs#4)] [!code-vb[TPLDataflow_CancellationWinForms#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_cancellationwinforms/vb/cancellationwinforms/form1.vb#4)] - Because the `incrementProgress` and `decrementProgress` dataflow blocks act on the user interface, it is important that these actions occur on the user-interface thread. To accomplish this, during construction these objects each provide a object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `Form1` constructor is called from the user-interface thread, the actions for the `incrementProgress` and `decrementProgress` dataflow blocks also run on the user-interface thread. + Because the `incrementProgress` and `decrementProgress` dataflow blocks act on the user interface, it is important that these actions occur on the user-interface thread. To accomplish this, during construction these objects each provide a object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `Form1` constructor is called from the user-interface thread, the actions for the `incrementProgress` and `decrementProgress` dataflow blocks also run on the user-interface thread. This example sets the property when it constructs the members of the pipeline. Because the property permanently cancels dataflow block execution, the whole pipeline must be recreated after the user cancels the operation and then wants to add more work items to the pipeline. For an example that demonstrates an alternative way to cancel a dataflow block so that other work can be performed after an operation is canceled, see [Walkthrough: Using Dataflow in a Windows Forms Application](../../../docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md). diff --git a/docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md b/docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md index 8d22f2840561f..56d654a9632af 100644 --- a/docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md +++ b/docs/standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md @@ -18,10 +18,10 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Cancel a Parallel.For or ForEach Loop -The and methods support cancellation through the use of cancellation tokens. For more information about cancellation in general, see [Cancellation](../../../docs/standard/threading/cancellation-in-managed-threads.md). In a parallel loop, you supply the to the method in the parameter and then enclose the parallel call in a try-catch block. +The and methods support cancellation through the use of cancellation tokens. For more information about cancellation in general, see [Cancellation](../../../docs/standard/threading/cancellation-in-managed-threads.md). In a parallel loop, you supply the to the method in the parameter and then enclose the parallel call in a try-catch block. ## Example - The following example shows how to cancel a call to . You can apply the same approach to a call. + The following example shows how to cancel a call to . You can apply the same approach to a call. [!code-csharp[TPL_Parallel#29](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/parallel_cancel.cs#29)] [!code-vb[TPL_Parallel#29](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/cancelloop.vb#29)] diff --git a/docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md b/docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md index a400c8056a0e7..632b00bbd0559 100644 --- a/docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md +++ b/docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md @@ -29,7 +29,7 @@ The following examples show two ways to cancel a PLINQ query. The first example [!code-csharp[PLINQ#16](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#16)] [!code-vb[PLINQ#16](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#16)] - The PLINQ framework does not roll a single into an ; the must be handled in a separate catch block. If one or more user delegates throws an OperationCanceledException(externalCT) (by using an external ) but no other exception, and the query was defined as `AsParallel().WithCancellation(externalCT)`, then PLINQ will issue a single (externalCT) rather than an . However, if one user delegate throws an , and another delegate throws another exception type, then both exceptions will be rolled into an . + The PLINQ framework does not roll a single into an ; the must be handled in a separate catch block. If one or more user delegates throws an OperationCanceledException(externalCT) (by using an external ) but no other exception, and the query was defined as `AsParallel().WithCancellation(externalCT)`, then PLINQ will issue a single (externalCT) rather than an . However, if one user delegate throws an , and another delegate throws another exception type, then both exceptions will be rolled into an . The general guidance on cancellation is as follows: diff --git a/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md b/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md index aba78f64a6c23..975d8738e4600 100644 --- a/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md +++ b/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md @@ -35,13 +35,13 @@ These examples show how to perform the following tasks: [!code-csharp[TPL_Cancellation#04](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_cancellation/cs/cancel1.cs#04)] [!code-vb[TPL_Cancellation#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_cancellation/vb/cancel1.vb#04)] - The class is fully integrated with the cancellation model that is based on the and types. For more information, see [Cancellation in Managed Threads](../../../docs/standard/threading/cancellation-in-managed-threads.md) and [Task Cancellation](../../../docs/standard/parallel-programming/task-cancellation.md). + The class is fully integrated with the cancellation model that is based on the and types. For more information, see [Cancellation in Managed Threads](../../../docs/standard/threading/cancellation-in-managed-threads.md) and [Task Cancellation](../../../docs/standard/parallel-programming/task-cancellation.md). ## See Also - - - - + + + + [Task-based Asynchronous Programming](../../../docs/standard/parallel-programming/task-based-asynchronous-programming.md) [Attached and Detached Child Tasks](../../../docs/standard/parallel-programming/attached-and-detached-child-tasks.md) [Lambda Expressions in PLINQ and TPL](../../../docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md) diff --git a/docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md b/docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md index 2351741411c9b..319fc19f13fcd 100644 --- a/docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md +++ b/docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Create Pre-Computed Tasks -This document describes how to use the method to retrieve the results of asynchronous download operations that are held in a cache. The method returns a finished object that holds the provided value as its property. This method is useful when you perform an asynchronous operation that returns a object, and the result of that object is already computed. +This document describes how to use the method to retrieve the results of asynchronous download operations that are held in a cache. The method returns a finished object that holds the provided value as its property. This method is useful when you perform an asynchronous operation that returns a object, and the result of that object is already computed. ## Example The following example downloads strings from the web. It defines the `DownloadStringAsync` method. This method downloads strings from the web asynchronously. This example also uses a object to cache the results of previous operations. If the input address is held in this cache, `DownloadStringAsync` uses the method to produce a object that holds the content at that address. Otherwise, `DownloadStringAsync` downloads the file from the web and adds the result to the cache. diff --git a/docs/standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query.md b/docs/standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query.md index fa30eb6ff0977..220e4eb90c4a5 100644 --- a/docs/standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query.md +++ b/docs/standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Handle Exceptions in a PLINQ Query -The first example in this topic shows how to handle the that can be thrown from a PLINQ query when it executes. The second example shows how to put try-catch blocks within delegates, as close as possible to where the exception will be thrown. In this way, you can catch them as soon as they occur and possibly continue query execution. When exceptions are allowed to bubble up back to the joining thread, then it is possible that a query may continue to process some items after the exception is raised. +The first example in this topic shows how to handle the that can be thrown from a PLINQ query when it executes. The second example shows how to put try-catch blocks within delegates, as close as possible to where the exception will be thrown. In this way, you can catch them as soon as they occur and possibly continue query execution. When exceptions are allowed to bubble up back to the joining thread, then it is possible that a query may continue to process some items after the exception is raised. In some cases when PLINQ falls back to sequential execution, and an exception occurs, the exception may be propagated directly, and not wrapped in an . Also, s are always propagated directly. @@ -27,7 +27,7 @@ The first example in this topic shows how to handle the This example is intended to demonstrate usage, and might not run faster than the equivalent sequential LINQ to Objects query. For more information about speedup, see [Understanding Speedup in PLINQ](../../../docs/standard/parallel-programming/understanding-speedup-in-plinq.md). ## Example - This example shows how to put the try-catch blocks around the code that executes the query to catch any s that are thrown. + This example shows how to put the try-catch blocks around the code that executes the query to catch any s that are thrown. [!code-csharp[PLINQ#41](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinqsamples.cs#41)] [!code-vb[PLINQ#41](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinqsnippets1.vb#41)] diff --git a/docs/standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md b/docs/standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md index 2d9f7ff43fed4..4a546a47189a2 100644 --- a/docs/standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md +++ b/docs/standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md @@ -17,15 +17,15 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Handle Exceptions in Parallel Loops -The and overloads do not have any special mechanism to handle exceptions that might be thrown. In this respect, they resemble regular `for` and `foreach` loops (`For` and `For Each` in Visual Basic); an unhandled exception causes the loop to terminate immediately. +The and overloads do not have any special mechanism to handle exceptions that might be thrown. In this respect, they resemble regular `for` and `foreach` loops (`For` and `For Each` in Visual Basic); an unhandled exception causes the loop to terminate immediately. - When you add your own exception-handling logic to parallel loops, handle the case in which similar exceptions might be thrown on multiple threads concurrently, and the case in which an exception thrown on one thread causes another exception to be thrown on another thread. You can handle both cases by wrapping all exceptions from the loop in a . The following example shows one possible approach. + When you add your own exception-handling logic to parallel loops, handle the case in which similar exceptions might be thrown on multiple threads concurrently, and the case in which an exception thrown on one thread causes another exception to be thrown on another thread. You can handle both cases by wrapping all exceptions from the loop in a . The following example shows one possible approach. > [!NOTE] > When "Just My Code" is enabled, Visual Studio in some cases will break on the line that throws the exception and display an error message that says "exception not handled by user code." This error is benign. You can press F5 to continue from it, and see the exception-handling behavior that is demonstrated in the example below. To prevent Visual Studio from breaking on the first error, just uncheck the "Just My Code" checkbox under **Tools, Options, Debugging, General**. ## Example - In this example, all exceptions are caught and then wrapped in an which is thrown. The caller can decide which exceptions to handle. + In this example, all exceptions are caught and then wrapped in an which is thrown. The caller can decide which exceptions to handle. [!code-csharp[TPL_Exceptions#08](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/exceptions.cs#08)] [!code-vb[TPL_Exceptions#08](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/exceptionsinloops.vb#08)] diff --git a/docs/standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md b/docs/standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md index 557b4e9fb9155..6220fac67ca79 100644 --- a/docs/standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md +++ b/docs/standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Implement a Partitioner for Static Partitioning -The following example shows one way to implement a simple custom partitioner for PLINQ that performs static partitioning. Because the partitioner does not support dynamic partitions, it is not consumable from . This particular partitioner might provide speedup over the default range partitioner for data sources for which each element requires an increasing amount of processing time. +The following example shows one way to implement a simple custom partitioner for PLINQ that performs static partitioning. Because the partitioner does not support dynamic partitions, it is not consumable from . This particular partitioner might provide speedup over the default range partitioner for data sources for which each element requires an increasing amount of processing time. ## Example [!code-csharp[TPL_Partitioners#05](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_partitioners/cs/partitioners.cs#05)] diff --git a/docs/standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md b/docs/standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md index 85388065606fa..a99d48695a9b1 100644 --- a/docs/standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md +++ b/docs/standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md @@ -22,10 +22,10 @@ manager: "wpickett" This document describes how to use the TPL Dataflow Library to implement a producer-consumer pattern. In this pattern, the *producer* sends messages to a message block, and the *consumer* reads messages from that block. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Example - The following example demonstrates a basic producer- consumer model that uses dataflow. The `Produce` method writes arrays that contain random bytes of data to a object and the `Consume` method reads bytes from a object. By acting on the and interfaces, instead of their derived types, you can write reusable code that can act on a variety of dataflow block types. This example uses the class. Because the class acts as both a source block and as a target block, the producer and the consumer can use a shared object to transfer data. + The following example demonstrates a basic producer- consumer model that uses dataflow. The `Produce` method writes arrays that contain random bytes of data to a object and the `Consume` method reads bytes from a object. By acting on the and interfaces, instead of their derived types, you can write reusable code that can act on a variety of dataflow block types. This example uses the class. Because the class acts as both a source block and as a target block, the producer and the consumer can use a shared object to transfer data. The `Produce` method calls the method in a loop to synchronously write data to the target block. After the `Produce` method writes all data to the target block, it calls the method to indicate that the block will never have additional data available. The `Consume` method uses the [async](~/docs/csharp/language-reference/keywords/async.md) and [await](~/docs/csharp/language-reference/keywords/await.md) operators ([Async](~/docs/visual-basic/language-reference/modifiers/async.md) and [Await](~/docs/visual-basic/language-reference/operators/await-operator.md) in [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]) to asynchronously compute the total number of bytes that are received from the object. To act asynchronously, the `Consume` method calls the method to receive a notification when the source block has data available and when the source block will never have additional data available. diff --git a/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md b/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md index d73680abcfa83..d1f41ca9ae45c 100644 --- a/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md +++ b/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Implement Dynamic Partitions -The following example shows how to implement a custom that implements dynamic partitioning and can be used from certain overloads and from PLINQ. +The following example shows how to implement a custom that implements dynamic partitioning and can be used from certain overloads and from PLINQ. ## Example Each time a partition calls on the enumerator, the enumerator provides the partition with one list element. In the case of PLINQ and , the partition is a instance. Because requests are happening concurrently on multiple threads, access to the current index is synchronized. diff --git a/docs/standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md b/docs/standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md index 6d9fbb41945f0..957fa64df7d86 100644 --- a/docs/standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md +++ b/docs/standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md @@ -27,7 +27,7 @@ In many cases, file iteration is an operation that can be easily parallelized. T In this example, the file I/O is performed synchronously. When dealing with large files or slow network connections, it might be preferable to access the files asynchronously. You can combine asynchronous I/O techniques with parallel iteration. For more information, see [TPL and Traditional .NET Framework Asynchronous Programming](../../../docs/standard/parallel-programming/tpl-and-traditional-async-programming.md). - The example uses the local `fileCount` variable to maintain a count of the total number of files processed. Because the variable might be accessed concurrently by multiple tasks, access to it is synchronized by calling the method. + The example uses the local `fileCount` variable to maintain a count of the total number of files processed. Because the variable might be accessed concurrently by multiple tasks, access to it is synchronized by calling the method. Note that if an exception is thrown on the main thread, the threads that are started by the method might continue to run. To stop these threads, you can set a Boolean variable in your exception handlers, and check its value on each iteration of the parallel loop. If the value indicates that an exception has been thrown, use the variable to stop or break from the loop. For more information, see [How to: Stop or Break from a Parallel.For Loop](http://msdn.microsoft.com/en-us/de52e4f1-9346-4ad5-b582-1a4d54dc7f7e). diff --git a/docs/standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md b/docs/standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md index c42658db174df..8792d572f8f5e 100644 --- a/docs/standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md +++ b/docs/standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md @@ -18,10 +18,10 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Perform Action When a Dataflow Block Receives Data -*Execution dataflow block* types call a user-provided delegate when they receive data. The , , and classes are execution dataflow block types. You can use the `delegate` keyword (`Sub` in [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]), , , or a lambda expression when you provide a work function to an execution dataflow block. This document describes how to use and lambda expressions to perform action in execution blocks. +*Execution dataflow block* types call a user-provided delegate when they receive data. The , , and classes are execution dataflow block types. You can use the `delegate` keyword (`Sub` in [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]), , , or a lambda expression when you provide a work function to an execution dataflow block. This document describes how to use and lambda expressions to perform action in execution blocks. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Example The following example uses dataflow to read a file from disk and computes the number of bytes in that file that are equal to zero. It uses to read the file and compute the number of zero bytes, and to print the number of zero bytes to the console. The object specifies a object to perform work when the blocks receive data. The object uses a lambda expression to print to the console the number of zero bytes that are read. diff --git a/docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md b/docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md index d60aefb1f6a35..479be43461448 100644 --- a/docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md +++ b/docs/standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md @@ -17,15 +17,15 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Prevent a Child Task from Attaching to its Parent -This document demonstrates how to prevent a child task from attaching to the parent task. Preventing a child task from attaching to its parent is useful when you call a component that is written by a third party and that also uses tasks. For example, a third-party component that uses the option to create a or object can cause problems in your code if it is long-running or throws an unhandled exception. +This document demonstrates how to prevent a child task from attaching to the parent task. Preventing a child task from attaching to its parent is useful when you call a component that is written by a third party and that also uses tasks. For example, a third-party component that uses the option to create a or object can cause problems in your code if it is long-running or throws an unhandled exception. ## Example - The following example compares the effects of using the default options to the effects of preventing a child task from attaching to the parent. The example creates a object that calls into a third-party library that also uses a object. The third-party library uses the option to create the object. The application uses the option to create the parent task. This option instructs the runtime to remove the specification in child tasks. + The following example compares the effects of using the default options to the effects of preventing a child task from attaching to the parent. The example creates a object that calls into a third-party library that also uses a object. The third-party library uses the option to create the object. The application uses the option to create the parent task. This option instructs the runtime to remove the specification in child tasks. [!code-csharp[TPL_DenyChildAttach#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_denychildattach/cs/denychildattach.cs#1)] [!code-vb[TPL_DenyChildAttach#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_denychildattach/vb/denychildattach.vb#1)] - Because a parent task does not finish until all child tasks finish, a long-running child task can cause the overall application to perform poorly. In this example, when the application uses the default options to create the parent task, the child task must finish before the parent task finishes. When the application uses the option, the child is not attached to the parent. Therefore, the application can perform additional work after the parent task finishes and before it must wait for the child task to finish. + Because a parent task does not finish until all child tasks finish, a long-running child task can cause the overall application to perform poorly. In this example, when the application uses the default options to create the parent task, the child task must finish before the parent task finishes. When the application uses the option, the child is not attached to the parent. Therefore, the application can perform additional work after the parent task finishes and before it must wait for the child task to finish. ## Compiling the Code Copy the example code and paste it in a Visual Studio project, or paste it in a file that is named `DenyChildAttach.cs` (`DenyChildAttach.vb` for [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]), and then run the following command in a Visual Studio Command Prompt window. diff --git a/docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md b/docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md index a0db3720ca726..544ee4e007ac6 100644 --- a/docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md +++ b/docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Return a Value from a Task -This example shows how to use the type to return a value from the property. It requires that the C:\Users\Public\Pictures\Sample Pictures\ directory exists, and that it contains files. +This example shows how to use the type to return a value from the property. It requires that the C:\Users\Public\Pictures\Sample Pictures\ directory exists, and that it contains files. ## Example [!code-csharp[TPL#10](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl/cs/returnavalue10.cs#10)] @@ -25,7 +25,7 @@ This example shows how to use the property blocks the calling thread until the task finishes. - To see how to pass the result of one to a continuation task, see [Chaining Tasks by Using Continuation Tasks](../../../docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md). + To see how to pass the result of one to a continuation task, see [Chaining Tasks by Using Continuation Tasks](../../../docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md). ## See Also [Task-based Asynchronous Programming](../../../docs/standard/parallel-programming/task-based-asynchronous-programming.md) diff --git a/docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md b/docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md index f1888afa7214a..e9533d2c89010 100644 --- a/docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md +++ b/docs/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md @@ -19,10 +19,10 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Specify a Task Scheduler in a Dataflow Block -This document demonstrates how to associate a specific task scheduler when you use dataflow in your application. The example uses the class in a Windows Forms application to show when reader tasks are active and when a writer task is active. It also uses the method to enable a dataflow block to run on the user-interface thread. +This document demonstrates how to associate a specific task scheduler when you use dataflow in your application. The example uses the class in a Windows Forms application to show when reader tasks are active and when a writer task is active. It also uses the method to enable a dataflow block to run on the user-interface thread. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ### To Create the Windows Forms Application @@ -71,7 +71,7 @@ This document demonstrates how to associate a specific task scheduler when you u [!code-csharp[TPLDataflow_WriterReadersWinForms#6](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/cs/writerreaderswinforms/form1.cs#6)] [!code-vb[TPLDataflow_WriterReadersWinForms#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb#6)] - Because the `toggleCheckBox` dataflow block acts on the user interface, it is important that this action occur on the user-interface thread. To accomplish this, during construction this object provides a object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `Form1` constructor is called from the user-interface thread, the action for the `toggleCheckBox` dataflow block also runs on the user-interface thread. + Because the `toggleCheckBox` dataflow block acts on the user interface, it is important that this action occur on the user-interface thread. To accomplish this, during construction this object provides a object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `Form1` constructor is called from the user-interface thread, the action for the `toggleCheckBox` dataflow block also runs on the user-interface thread. This example also uses the class to enable some dataflow blocks to act concurrently, and another dataflow block to act exclusive with respect to all other dataflow blocks that run on the same object. This technique is useful when multiple dataflow blocks share a resource and some require exclusive access to that resource, because it eliminates the requirement to manually synchronize access to that resource. The elimination of manual synchronization can make code more efficient. diff --git a/docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md b/docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md index fad571b40e4ac..2819c242f5027 100644 --- a/docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md +++ b/docs/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md @@ -19,10 +19,10 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Specify the Degree of Parallelism in a Dataflow Block -This document describes how to set the property to enable an execution dataflow block to process more than one message at a time. Doing this is useful when you have a dataflow block that performs a long-running computation and can benefit from processing messages in parallel. This example uses the class to perform multiple dataflow operations concurrently; however, you can specify the maximum degree of parallelism in any of the predefined execution block types that the TPL Dataflow Library provides, , , and . +This document describes how to set the property to enable an execution dataflow block to process more than one message at a time. Doing this is useful when you have a dataflow block that performs a long-running computation and can benefit from processing messages in parallel. This example uses the class to perform multiple dataflow operations concurrently; however, you can specify the maximum degree of parallelism in any of the predefined execution block types that the TPL Dataflow Library provides, , , and . > [!TIP] -> The TPL Dataflow Library (the namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library (the namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Example The following example performs two dataflow computations and prints the elapsed time that is required for each computation. The first computation specifies a maximum degree of parallelism of 1, which is the default. A maximum degree of parallelism of 1 causes the dataflow block to process messages serially. The second computation resembles the first, except that it specifies a maximum degree of parallelism that is equal to the number of available processors. This enables the dataflow block to perform multiple operations in parallel. diff --git a/docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md b/docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md index fdf1e9f0b1a71..8354639478982 100644 --- a/docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md +++ b/docs/standard/parallel-programming/how-to-speed-up-small-loop-bodies.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Speed Up Small Loop Bodies -When a loop has a small body, it might perform more slowly than the equivalent sequential loop, such as the [for](~/docs/csharp/language-reference/keywords/for.md) loop in C# and the [For](http://msdn.microsoft.com/en-us/c470a263-9b49-4308-8fd6-8592b84a7980) loop in Visual Basic. Slower performance is caused by the overhead involved in partitioning the data and the cost of invoking a delegate on each loop iteration. To address such scenarios, the class provides the method, which enables you to provide a sequential loop for the delegate body, so that the delegate is invoked only once per partition, instead of once per iteration. For more information, see [Custom Partitioners for PLINQ and TPL](../../../docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md). +When a loop has a small body, it might perform more slowly than the equivalent sequential loop, such as the [for](~/docs/csharp/language-reference/keywords/for.md) loop in C# and the [For](http://msdn.microsoft.com/en-us/c470a263-9b49-4308-8fd6-8592b84a7980) loop in Visual Basic. Slower performance is caused by the overhead involved in partitioning the data and the cost of invoking a delegate on each loop iteration. To address such scenarios, the class provides the method, which enables you to provide a sequential loop for the delegate body, so that the delegate is invoked only once per partition, instead of once per iteration. For more information, see [Custom Partitioners for PLINQ and TPL](../../../docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md). ## Example [!code-csharp[TPL_Partitioners#01](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_partitioners/cs/partitioner01.cs#01)] diff --git a/docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md b/docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md index 92539e522ee4c..b270629e5ccb8 100644 --- a/docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md +++ b/docs/standard/parallel-programming/how-to-unlink-dataflow-blocks.md @@ -22,7 +22,7 @@ manager: "wpickett" This document describes how to unlink a target dataflow block from its source. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Example The following example creates three objects, each of which calls the `TrySolution` method to compute a value. This example requires only the result from the first call to `TrySolution` to finish. diff --git a/docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md b/docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md index f2d8c922cc9eb..3cb4eff9b7146 100644 --- a/docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md +++ b/docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md @@ -43,5 +43,5 @@ You can return a task from a method, and then wait on or continue from that task [!code-vb[TPL_UnWrap#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_unwrap/vb/snippet04.vb#04)] ## See Also - + [Task-based Asynchronous Programming](../../../docs/standard/parallel-programming/task-based-asynchronous-programming.md) diff --git a/docs/standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md b/docs/standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md index 01043302d90e1..f5031b98f6d46 100644 --- a/docs/standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md +++ b/docs/standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md @@ -22,7 +22,7 @@ manager: "wpickett" This document explains how to use the class to perform an operation when data is available from multiple sources. It also demonstrates how to use non-greedy mode to enable multiple join blocks to share a data source more efficiently. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Example The following example defines three resource types, `NetworkResource`, `FileResource`, and `MemoryResource`, and performs operations when resources become available. This example requires a `NetworkResource` and `MemoryResource` pair in order to perform the first operation and a `FileResource` and `MemoryResource` pair in order to perform the second operation. To enable these operations to occur when all required resources are available, this example uses the class. When a object receives data from all sources, it propagates that data to its target, which in this example is an object. Both objects read from a shared pool of `MemoryResource` objects. diff --git a/docs/standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md b/docs/standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md index 8179de815234f..029253ee962d2 100644 --- a/docs/standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md +++ b/docs/standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md @@ -28,9 +28,9 @@ This example shows how to use the as the third input parameter. This delegate combines the results from all threads before it performs the final calculation on the aggregated results. In this example we add together the sums from all the threads. + This example uses an overload of the Aggregate standard query operator that is unique to PLINQ. This overload takes an extra as the third input parameter. This delegate combines the results from all threads before it performs the final calculation on the aggregated results. In this example we add together the sums from all the threads. - Note that when a lambda expression body consists of a single expression, the return value of the delegate is the value of the expression. + Note that when a lambda expression body consists of a single expression, the return value of the delegate is the value of the expression. ## See Also diff --git a/docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md b/docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md index cf7898d6e91b9..cf5ce63e11a15 100644 --- a/docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md +++ b/docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md @@ -39,7 +39,7 @@ Function() new MyClass() The fourth parameter defines the loop logic. It must be a delegate or lambda expression whose signature is `Func` in C# or `Func(Of Integer, ParallelLoopState, Long, Long)` in Visual Basic. The first parameter is the value of the loop counter for that iteration of the loop. The second is a object that can be used to break out of the loop; this object is provided by the class to each occurrence of the loop. The third parameter is the thread-local variable. The last parameter is the return type. In this case, the type is because that is the type we specified in the type argument. That variable is named `subtotal` and is returned by the lambda expression. The return value is used to initialize `subtotal` on each subsequent iteration of the loop. You can also think of this last parameter as a value that is passed to each iteration, and then passed to the `localFinally` delegate when the last iteration is complete. - The fifth parameter defines the method that is called once, after all the iterations on a particular thread have completed. The type of the input argument again corresponds to the type argument of the method and the type returned by the body lambda expression. In this example, the value is added to a variable at class scope in a thread safe way by calling the method. By using a thread-local variable, we have avoided writing to this class variable on every iteration of the loop. + The fifth parameter defines the method that is called once, after all the iterations on a particular thread have completed. The type of the input argument again corresponds to the type argument of the method and the type returned by the body lambda expression. In this example, the value is added to a variable at class scope in a thread safe way by calling the method. By using a thread-local variable, we have avoided writing to this class variable on every iteration of the loop. For more information about how to use lambda expressions, see [Lambda Expressions in PLINQ and TPL](../../../docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md). diff --git a/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md b/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md index a29f25438218c..68c824535b87f 100644 --- a/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md +++ b/docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md @@ -24,11 +24,11 @@ The following example shows how to write a loop, you must call one of the method overloads that takes two type parameters. The first type parameter, `TSource`, specifies the type of the source element, and the second type parameter, `TLocal`, specifies the type of the thread-local variable. ## Example - The following example calls overload to compute the sum of an array of one million elements. This overload has four parameters: + The following example calls overload to compute the sum of an array of one million elements. This overload has four parameters: -- `source`, which is the data source. It must implement . The data source in our example is the one million member `IEnumerable` object returned by the method. +- `source`, which is the data source. It must implement . The data source in our example is the one million member `IEnumerable` object returned by the method. -- `localInit`, or the function that initializes the thread-local variable. This function is called once for each partition in which the operation executes. Our example initializes the thread-local variable to zero. +- `localInit`, or the function that initializes the thread-local variable. This function is called once for each partition in which the operation executes. Our example initializes the thread-local variable to zero. - `body`, a that is invoked by the parallel loop on each iteration of the loop. Its signature is `Func\`. You supply the code for the delegate, and the loop passes in the input parameters, which are: @@ -42,7 +42,7 @@ The following example shows how to write a ` delegate that the invokes when the looping operations in each partition have completed. The method passes your `Action` delegate the final value of the thread-local variable for this thread (or loop partition), and you provide the code that performs the required action for combining the result from this partition with the results from the other partitions. This delegate can be invoked concurrently by multiple tasks. Because of this, the example uses the method to synchronize access to the `total` variable. Because the delegate type is an , there is no return value. +- `localFinally`, an `Action` delegate that the invokes when the looping operations in each partition have completed. The method passes your `Action` delegate the final value of the thread-local variable for this thread (or loop partition), and you provide the code that performs the required action for combining the result from this partition with the results from the other partitions. This delegate can be invoked concurrently by multiple tasks. Because of this, the example uses the method to synchronize access to the `total` variable. Because the delegate type is an , there is no return value. [!code-csharp[TPL_Parallel#04](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/foreachthreadlocal.cs#04)] [!code-vb[TPL_Parallel#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/foreachthreadlocal.vb#04)] diff --git a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md index 1cf15bcb08e0d..ff2905d8ee6b0 100644 --- a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md +++ b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md @@ -19,7 +19,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Write a Simple Parallel.For Loop -This topic contains two examples that illustrate the method. The first uses the method overload, and the second uses the overload, the two simplest overloads of the method. You can use these two overloads of the method when you do not need to cancel the loop, break out of the loop iterations, or maintain any thread-local state. +This topic contains two examples that illustrate the method. The first uses the method overload, and the second uses the overload, the two simplest overloads of the method. You can use these two overloads of the method when you do not need to cancel the loop, break out of the loop iterations, or maintain any thread-local state. > [!NOTE] > This documentation uses lambda expressions to define delegates in TPL. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](../../../docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md). @@ -27,13 +27,13 @@ This topic contains two examples that illustrate the method to enumerate the files in the directory and determine their file sizes. Each file size is then added to the `totalSize` variable. Note that the addition is performed by calling the so that the addition is performed as an atomic operation. Otherwise, multiple tasks could try to update the `totalSize` variable simultaneously. + This example is a simple command-line utility that calculates the total size of files in a directory. It expects a single directory path as an argument, and reports the number and total size of the files in that directory. After verifying that the directory exists, it uses the method to enumerate the files in the directory and determine their file sizes. Each file size is then added to the `totalSize` variable. Note that the addition is performed by calling the so that the addition is performed as an atomic operation. Otherwise, multiple tasks could try to update the `totalSize` variable simultaneously. [!code-csharp[Conceptual.Parallel.For#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.parallel.for/cs/for1.cs#1)] [!code-vb[Conceptual.Parallel.For#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.parallel.for/vb/for1.vb#1)] ## Example - This example uses the method to compute the product of two matrices. It also shows how to use the class to compare the performance of a parallel loop with a non-parallel loop. Note that, because it can generate a large volume of output, the example allows output to be redirected to a file. + This example uses the method to compute the product of two matrices. It also shows how to use the class to compare the performance of a parallel loop with a non-parallel loop. Note that, because it can generate a large volume of output, the example allows output to be redirected to a file. [!code-csharp[TPL_Parallel#01](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_parallel/cs/simpleparallelfor.cs#01)] [!code-vb[TPL_Parallel#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_parallel/vb/simpleparallelfor.vb#01)] @@ -46,17 +46,17 @@ This topic contains two examples that illustrate the input parameter, such as: . + If you require more control over the concurrency level, use one of the overloads that takes a input parameter, such as: . ## Return Value and Exception Handling - returns a object when all threads have completed. This return value is useful when you are stopping or breaking loop iteration manually, because the stores information such as the last iteration that ran to completion. If one or more exceptions occur on one of the threads, a will be thrown. + returns a object when all threads have completed. This return value is useful when you are stopping or breaking loop iteration manually, because the stores information such as the last iteration that ran to completion. If one or more exceptions occur on one of the threads, a will be thrown. In the code in this example, the return value of is not used. ## Analysis and Performance You can use the Performance Wizard to view CPU usage on your computer. As an experiment, increase the number of columns and rows in the matrices. The larger the matrices, the greater the performance difference between the parallel and sequential versions of the computation. When the matrix is small, the sequential version will run faster because of the overhead in setting up the parallel loop. - Synchronous calls to shared resources, like the Console or the File System, will significantly degrade the performance of a parallel loop. When measuring performance, try to avoid calls such as within the loop. + Synchronous calls to shared resources, like the Console or the File System, will significantly degrade the performance of a parallel loop. When measuring performance, try to avoid calls such as within the loop. ## Compiling the Code diff --git a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md index 6f327e6d9e66d..b0bd7e334c9ad 100644 --- a/docs/standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md +++ b/docs/standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md @@ -18,7 +18,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Write a Simple Parallel.ForEach Loop -This example shows how to use a loop to enable data parallelism over any or data source. +This example shows how to use a loop to enable data parallelism over any or data source. > [!NOTE] > This documentation uses lambda expressions to define delegates in PLINQ. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](../../../docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md). diff --git a/docs/standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md b/docs/standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md index c2fb755f78559..de3e0752efb46 100644 --- a/docs/standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md +++ b/docs/standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md @@ -18,10 +18,10 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Write Messages to and Read Messages from a Dataflow Block -This document describes how to use the TPL Dataflow Library to write messages to and read messages from a dataflow block. The TPL Dataflow Library provides both synchronous and asynchronous methods for writing messages to and reading messages from a dataflow block. This document uses the class. The class buffers messages and behaves as both a message source and as a message target. +This document describes how to use the TPL Dataflow Library to write messages to and read messages from a dataflow block. The TPL Dataflow Library provides both synchronous and asynchronous methods for writing messages to and reading messages from a dataflow block. This document uses the class. The class buffers messages and behaves as both a message source and as a message target. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Writing to and Reading from a Dataflow Block Synchronously The following example uses the method to write to a dataflow block and the method to read from the same object. diff --git a/docs/standard/parallel-programming/index.md b/docs/standard/parallel-programming/index.md index 0867dbe838d0a..444cb1cce087a 100644 --- a/docs/standard/parallel-programming/index.md +++ b/docs/standard/parallel-programming/index.md @@ -25,7 +25,7 @@ Many personal computers and workstations have two or four cores (that is, CPUs) |Technology|Description| |----------------|-----------------| -|[Task Parallel Library (TPL)](../../../docs/standard/parallel-programming/task-parallel-library-tpl.md)|Provides documentation for the class, which includes parallel versions of `For` and `ForEach` loops, and also for the class, which represents the preferred way to express asynchronous operations.| +|[Task Parallel Library (TPL)](../../../docs/standard/parallel-programming/task-parallel-library-tpl.md)|Provides documentation for the class, which includes parallel versions of `For` and `ForEach` loops, and also for the class, which represents the preferred way to express asynchronous operations.| |[Parallel LINQ (PLINQ)](../../../docs/standard/parallel-programming/parallel-linq-plinq.md)|A parallel implementation of LINQ to Objects that significantly improves performance in many scenarios.| |[Data Structures for Parallel Programming](../../../docs/standard/parallel-programming/data-structures-for-parallel-programming.md)|Provides links to documentation for thread-safe collection classes, lightweight synchronization types, and types for lazy initialization.| |[Parallel Diagnostic Tools](../../../docs/standard/parallel-programming/parallel-diagnostic-tools.md)|Provides links to documentation for Visual Studio debugger windows for tasks and parallel stacks, and the [Concurrency Visualizer](/visualstudio/profiling/concurrency-visualizer), which consists of a set of views in the [!INCLUDE[vsprvsts](../../../includes/vsprvsts-md.md)] Profiler that you can use to debug and to tune the performance of parallel code.| diff --git a/docs/standard/parallel-programming/introduction-to-plinq.md b/docs/standard/parallel-programming/introduction-to-plinq.md index cfbcbd84d4bca..d8773e85549ec 100644 --- a/docs/standard/parallel-programming/introduction-to-plinq.md +++ b/docs/standard/parallel-programming/introduction-to-plinq.md @@ -18,7 +18,7 @@ manager: "wpickett" --- # Introduction to PLINQ ## What is a Parallel Query? - Language-Integrated Query (LINQ) was introduced in the [!INCLUDE[net_v35_long](../../../includes/net-v35-long-md.md)]. It features a unified model for querying any or data source in a type-safe manner. LINQ to Objects is the name for LINQ queries that are run against in-memory collections such as and arrays. This article assumes that you have a basic understand of LINQ. For more information, see [LINQ (Language-Integrated Query)](http://msdn.microsoft.com/library/a73c4aec-5d15-4e98-b962-1274021ea93d). + Language-Integrated Query (LINQ) was introduced in the [!INCLUDE[net_v35_long](../../../includes/net-v35-long-md.md)]. It features a unified model for querying any or data source in a type-safe manner. LINQ to Objects is the name for LINQ queries that are run against in-memory collections such as and arrays. This article assumes that you have a basic understand of LINQ. For more information, see [LINQ (Language-Integrated Query)](http://msdn.microsoft.com/library/a73c4aec-5d15-4e98-b962-1274021ea93d). Parallel LINQ (PLINQ) is a parallel implementation of the LINQ pattern. A PLINQ query in many ways resembles a non-parallel LINQ to Objects query. PLINQ queries, just like sequential [!INCLUDE[vbteclinq](../../../includes/vbteclinq-md.md)] queries, operate on any in-memory or data source, and have deferred execution, which means they do not begin executing until the query is enumerated. The primary difference is that PLINQ attempts to make full use of all the processors on the system. It does this by partitioning the data source into segments, and then executing the query on each segment on separate worker threads in parallel on multiple processors. In many cases, parallel execution means that the query runs significantly faster. @@ -30,7 +30,7 @@ manager: "wpickett" The remainder of this article gives an overview of the main PLINQ classes, and discusses how to create PLINQ queries. Each section contains links to more detailed information and code examples. ## The ParallelEnumerable Class - The class exposes almost all of PLINQ's functionality. It and the rest of the namespace types are compiled into the System.Core.dll assembly. The default C# and Visual Basic projects in Visual Studio both reference the assembly and import the namespace. + The class exposes almost all of PLINQ's functionality. It and the rest of the namespace types are compiled into the System.Core.dll assembly. The default C# and Visual Basic projects in Visual Studio both reference the assembly and import the namespace. includes implementations of all the standard query operators that LINQ to Objects supports, although it does not attempt to parallelize each one. If you are not familiar with [!INCLUDE[vbteclinq](../../../includes/vbteclinq-md.md)], see [Introduction to LINQ](http://msdn.microsoft.com/library/24dddf19-12a0-4707-a4bc-eba4fa7f219e). @@ -50,15 +50,15 @@ manager: "wpickett" | overload|An overload that is unique to PLINQ and enables intermediate aggregation over thread-local partitions, plus a final aggregation function to combine the results of all partitions.| ## The Opt-in Model - When you write a query, opt in to PLINQ by invoking the extension method on the data source, as shown in the following example. + When you write a query, opt in to PLINQ by invoking the extension method on the data source, as shown in the following example. [!code-csharp[PLINQ#1](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinq2_cs.cs#1)] [!code-vb[PLINQ#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#1)] - The extension method binds the subsequent query operators, in this case, `where` and `select`, to the implementations. + The extension method binds the subsequent query operators, in this case, `where` and `select`, to the implementations. ## Execution Modes - By default, PLINQ is conservative. At run time, the PLINQ infrastructure analyzes the overall structure of the query. If the query is likely to yield speedups by parallelization, PLINQ partitions the source sequence into tasks that can be run concurrently. If it is not safe to parallelize a query, PLINQ just runs the query sequentially. If PLINQ has a choice between a potentially expensive parallel algorithm or an inexpensive sequential algorithm, it chooses the sequential algorithm by default. You can use the method and the enumeration to instruct PLINQ to select the parallel algorithm. This is useful when you know by testing and measurement that a particular query executes faster in parallel. For more information, see [How to: Specify the Execution Mode in PLINQ](../../../docs/standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md). + By default, PLINQ is conservative. At run time, the PLINQ infrastructure analyzes the overall structure of the query. If the query is likely to yield speedups by parallelization, PLINQ partitions the source sequence into tasks that can be run concurrently. If it is not safe to parallelize a query, PLINQ just runs the query sequentially. If PLINQ has a choice between a potentially expensive parallel algorithm or an inexpensive sequential algorithm, it chooses the sequential algorithm by default. You can use the method and the enumeration to instruct PLINQ to select the parallel algorithm. This is useful when you know by testing and measurement that a particular query executes faster in parallel. For more information, see [How to: Specify the Execution Mode in PLINQ](../../../docs/standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md). ## Degree of Parallelism By default, PLINQ uses all of the processors on the host computer up to a maximum of 64. You can instruct PLINQ to use no more than a specified number of processors by using the method. This is useful when you want to make sure that other processes running on the computer receive a certain amount of CPU time. The following snippet limits the query to utilizing a maximum of two processors. @@ -85,7 +85,7 @@ manager: "wpickett" When a PLINQ query executes in parallel, its results from each worker thread must be merged back onto the main thread for consumption by a `foreach` loop (`For Each` in [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]), or insertion into a list or array. In some cases, it might be beneficial to specify a particular kind of merge operation, for example, to begin producing results more quickly. For this purpose, PLINQ supports the method, and the enumeration. For more information, see [Merge Options in PLINQ](../../../docs/standard/parallel-programming/merge-options-in-plinq.md). ## The ForAll Operator - In sequential [!INCLUDE[vbteclinq](../../../includes/vbteclinq-md.md)] queries, execution is deferred until the query is enumerated either in a `foreach` (`For Each` in [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]) loop or by invoking a method such as , , or . In PLINQ, you can also use `foreach` to execute the query and iterate through the results. However, `foreach` itself does not run in parallel, and therefore, it requires that the output from all parallel tasks be merged back into the thread on which the loop is running. In PLINQ, you can use `foreach` when you must preserve the final ordering of the query results, and also whenever you are processing the results in a serial manner, for example when you are calling `Console.WriteLine` for each element. For faster query execution when order preservation is not required and when the processing of the results can itself be parallelized, use the method to execute a PLINQ query. does not perform this final merge step. The following code example shows how to use the method. is used here because it is optimized for multiple threads adding concurrently without attempting to remove any items. + In sequential [!INCLUDE[vbteclinq](../../../includes/vbteclinq-md.md)] queries, execution is deferred until the query is enumerated either in a `foreach` (`For Each` in [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]) loop or by invoking a method such as , , or . In PLINQ, you can also use `foreach` to execute the query and iterate through the results. However, `foreach` itself does not run in parallel, and therefore, it requires that the output from all parallel tasks be merged back into the thread on which the loop is running. In PLINQ, you can use `foreach` when you must preserve the final ordering of the query results, and also whenever you are processing the results in a serial manner, for example when you are calling `Console.WriteLine` for each element. For faster query execution when order preservation is not required and when the processing of the results can itself be parallelized, use the method to execute a PLINQ query. does not perform this final merge step. The following code example shows how to use the method. is used here because it is optimized for multiple threads adding concurrently without attempting to remove any items. [!code-csharp[PLINQ#4](../../../samples/snippets/csharp/VS_Snippets_Misc/plinq/cs/plinq2_cs.cs#4)] [!code-vb[PLINQ#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/plinq/vb/plinq2_vb.vb#4)] diff --git a/docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md b/docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md index 97fb4223025b0..02ac398f05b7f 100644 --- a/docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md +++ b/docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md @@ -19,18 +19,18 @@ ms.author: "ronpet" manager: "wpickett" --- # Lambda Expressions in PLINQ and TPL -The Task Parallel Library (TPL) contains many methods that take one of the or family of delegates as input parameters. You use these delegates to pass in your custom program logic to the parallel loop, task or query. The code examples for TPL as well as PLINQ use lambda expressions to create instances of those delegates as inline code blocks. This topic provides a brief introduction to Func and Action and shows you how to use lambda expressions in the Task Parallel Library and PLINQ. +The Task Parallel Library (TPL) contains many methods that take one of the or family of delegates as input parameters. You use these delegates to pass in your custom program logic to the parallel loop, task or query. The code examples for TPL as well as PLINQ use lambda expressions to create instances of those delegates as inline code blocks. This topic provides a brief introduction to Func and Action and shows you how to use lambda expressions in the Task Parallel Library and PLINQ. **Note** For more information about delegates in general, see [Delegates](../../csharp/programming-guide/delegates/index.md) and [Delegates](../../visual-basic/programming-guide/language-features/delegates/index.md). For more information about lambda expressions in C# and [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)], see [Lambda Expressions](~/docs/csharp/programming-guide/statements-expressions-operators/lambda-expressions.md) and [Lambda Expressions](~/docs/visual-basic/programming-guide/language-features/procedures/lambda-expressions.md). ## Func Delegate - A `Func` delegate encapsulates a method that returns a value. In a Func signature, the last or rightmost type parameter always specifies the return type. One common cause of compiler errors is to attempt to pass in two input parameters to a ; in fact this type takes only one input parameter. The Framework Class Library defines 17 versions of `Func`: , , , and so on up through . + A `Func` delegate encapsulates a method that returns a value. In a Func signature, the last or rightmost type parameter always specifies the return type. One common cause of compiler errors is to attempt to pass in two input parameters to a ; in fact this type takes only one input parameter. The Framework Class Library defines 17 versions of `Func`: , , , and so on up through . ## Action Delegate - A delegate encapsulates a method (Sub in [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]) that does not return a value, or returns [void](~/docs/csharp/language-reference/keywords/void.md). In an Action type signature, the type parameters represent only input parameters. Like Func, the Framework Class Library defines 17 versions of Action, from a version that has no type parameters up through a version that has 16 type parameters. + A delegate encapsulates a method (Sub in [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)]) that does not return a value, or returns [void](~/docs/csharp/language-reference/keywords/void.md). In an Action type signature, the type parameters represent only input parameters. Like Func, the Framework Class Library defines 17 versions of Action, from a version that has no type parameters up through a version that has 16 type parameters. ## Example - The following example for the method shows how to express both Func and Action delegates by using lambda expressions. + The following example for the method shows how to express both Func and Action delegates by using lambda expressions. [!code-csharp[System.Threading.Tasks.Parallel#02](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.parallel/cs/parallelforeach.cs#02)] [!code-vb[System.Threading.Tasks.Parallel#02](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.parallel/vb/parallelforeach.vb#02)] diff --git a/docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md b/docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md index 078768317e071..f2675776d072f 100644 --- a/docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md +++ b/docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md @@ -17,13 +17,13 @@ ms.author: "ronpet" manager: "wpickett" --- # Potential Pitfalls in Data and Task Parallelism -In many cases, and can provide significant performance improvements over ordinary sequential loops. However, the work of parallelizing the loop introduces complexity that can lead to problems that, in sequential code, are not as common or are not encountered at all. This topic lists some practices to avoid when you write parallel loops. +In many cases, and can provide significant performance improvements over ordinary sequential loops. However, the work of parallelizing the loop introduces complexity that can lead to problems that, in sequential code, are not as common or are not encountered at all. This topic lists some practices to avoid when you write parallel loops. ## Do Not Assume That Parallel Is Always Faster In certain cases a parallel loop might run slower than its sequential equivalent. The basic rule of thumb is that parallel loops that have few iterations and fast user delegates are unlikely to speedup much. However, because many factors are involved in performance, we recommend that you always measure actual results. ## Avoid Writing to Shared Memory Locations - In sequential code, it is not uncommon to read from or write to static variables or class fields. However, whenever multiple threads are accessing such variables concurrently, there is a big potential for race conditions. Even though you can use locks to synchronize access to the variable, the cost of synchronization can hurt performance. Therefore, we recommend that you avoid, or at least limit, access to shared state in a parallel loop as much as possible. The best way to do this is to use the overloads of and that use a variable to store thread-local state during loop execution. For more information, see [How to: Write a Parallel.For Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md) and [How to: Write a Parallel.ForEach Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md). + In sequential code, it is not uncommon to read from or write to static variables or class fields. However, whenever multiple threads are accessing such variables concurrently, there is a big potential for race conditions. Even though you can use locks to synchronize access to the variable, the cost of synchronization can hurt performance. Therefore, we recommend that you avoid, or at least limit, access to shared state in a parallel loop as much as possible. The best way to do this is to use the overloads of and that use a variable to store thread-local state during loop execution. For more information, see [How to: Write a Parallel.For Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md) and [How to: Write a Parallel.ForEach Loop with Thread-Local Variables](../../../docs/standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-thread-local-variables.md). ## Avoid Over-Parallelization By using parallel loops, you incur the overhead costs of partitioning the source collection and synchronizing the worker threads. The benefits of parallelization are further limited by the number of processors on the computer. There is no speedup to be gained by running multiple compute-bound threads on just one processor. Therefore, you must be careful not to over-parallelize a loop. @@ -39,7 +39,7 @@ In many cases, method simultaneously, which is not supported by the class. + Writing to non-thread-safe instance methods from a parallel loop can lead to data corruption which may or may not go undetected in your program. It can also lead to exceptions. In the following example, multiple threads would be attempting to call the method simultaneously, which is not supported by the class. [!code-csharp[TPL_Pitfalls#04](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_pitfalls/cs/pitfalls.cs#04)] [!code-vb[TPL_Pitfalls#04](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_pitfalls/vb/pitfalls_vb.vb#04)] diff --git a/docs/standard/parallel-programming/potential-pitfalls-with-plinq.md b/docs/standard/parallel-programming/potential-pitfalls-with-plinq.md index 0a0feec658222..93c05e5c79937 100644 --- a/docs/standard/parallel-programming/potential-pitfalls-with-plinq.md +++ b/docs/standard/parallel-programming/potential-pitfalls-with-plinq.md @@ -66,9 +66,9 @@ a.Where(...).OrderBy(...).Select(...).ForAll(x => fs.Write(x)); When PLINQ executes a query in parallel, it divides the source sequence into partitions that can be operated on concurrently on multiple threads. By default, the order in which the partitions are processed and the results are delivered is not predictable (except for operators such as `OrderBy`). You can instruct PLINQ to preserve the ordering of any source sequence, but this has a negative impact on performance. The best practice, whenever possible, is to structure queries so that they do not rely on order preservation. For more information, see [Order Preservation in PLINQ](../../../docs/standard/parallel-programming/order-preservation-in-plinq.md). ## Prefer ForAll to ForEach When It Is Possible - Although PLINQ executes a query on multiple threads, if you consume the results in a `foreach` loop (`For Each` in Visual Basic), then the query results must be merged back into one thread and accessed serially by the enumerator. In some cases, this is unavoidable; however, whenever possible, use the `ForAll` method to enable each thread to output its own results, for example, by writing to a thread-safe collection such as . + Although PLINQ executes a query on multiple threads, if you consume the results in a `foreach` loop (`For Each` in Visual Basic), then the query results must be merged back into one thread and accessed serially by the enumerator. In some cases, this is unavoidable; however, whenever possible, use the `ForAll` method to enable each thread to output its own results, for example, by writing to a thread-safe collection such as . - The same issue applies to In other words, `source.AsParallel().Where().ForAll(...)` should be strongly preferred to + The same issue applies to In other words, `source.AsParallel().Where().ForAll(...)` should be strongly preferred to `Parallel.ForEach(source.AsParallel().Where(), ...)`. @@ -76,7 +76,7 @@ a.Where(...).OrderBy(...).Select(...).ForAll(x => fs.Write(x)); Some technologies, for example, COM interoperability for Single-Threaded Apartment (STA) components, Windows Forms, and Windows Presentation Foundation (WPF), impose thread affinity restrictions that require code to run on a specific thread. For example, in both Windows Forms and WPF, a control can only be accessed on the thread on which it was created. If you try to access the shared state of a Windows Forms control in a PLINQ query, an exception is raised if you are running in the debugger. (This setting can be turned off.) However, if your query is consumed on the UI thread, then you can access the control from the `foreach` loop that enumerates the query results because that code executes on just one thread. ## Do Not Assume that Iterations of ForEach, For and ForAll Always Execute in Parallel - It is important to keep in mind that individual iterations in a , or loop may but do not have to execute in parallel. Therefore, you should avoid writing any code that depends for correctness on parallel execution of iterations or on the execution of iterations in any particular order. + It is important to keep in mind that individual iterations in a , or loop may but do not have to execute in parallel. Therefore, you should avoid writing any code that depends for correctness on parallel execution of iterations or on the execution of iterations in any particular order. For example, this code is likely to deadlock: diff --git a/docs/standard/parallel-programming/task-based-asynchronous-programming.md b/docs/standard/parallel-programming/task-based-asynchronous-programming.md index de48267c6e001..c9cc5e044cf2e 100644 --- a/docs/standard/parallel-programming/task-based-asynchronous-programming.md +++ b/docs/standard/parallel-programming/task-based-asynchronous-programming.md @@ -30,7 +30,7 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre For both of these reasons, in the .NET Framework, TPL is the preferred API for writing multi-threaded, asynchronous, and parallel code. ## Creating and running tasks implicitly - The method provides a convenient way to run any number of arbitrary statements concurrently. Just pass in an delegate for each item of work. The easiest way to create these delegates is to use lambda expressions. The lambda expression can either call a named method or provide the code inline. The following example shows a basic call that creates and starts two tasks that run concurrently. The first task is represented by a lambda expression that calls a method named `DoSomeWork`, and the second task is represented by a lambda expression that calls a method named `DoSomeOtherWork`. + The method provides a convenient way to run any number of arbitrary statements concurrently. Just pass in an delegate for each item of work. The easiest way to create these delegates is to use lambda expressions. The lambda expression can either call a named method or provide the code inline. The following example shows a basic call that creates and starts two tasks that run concurrently. The first task is represented by a lambda expression that calls a method named `DoSomeWork`, and the second task is represented by a lambda expression that calls a method named `DoSomeOtherWork`. > [!NOTE] > This documentation uses lambda expressions to define delegates in TPL. If you are not familiar with lambda expressions in C# or Visual Basic, see [Lambda Expressions in PLINQ and TPL](../../../docs/standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md). @@ -46,24 +46,24 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre For greater control over task execution or to return a value from the task, you have to work with objects more explicitly. ## Creating and running tasks explicitly - A task that does not return a value is represented by the class. A task that returns a value is represented by the class, which inherits from . The task object handles the infrastructure details and provides methods and properties that are accessible from the calling thread throughout the lifetime of the task. For example, you can access the property of a task at any time to determine whether it has started running, ran to completion, was canceled, or has thrown an exception. The status is represented by a enumeration. + A task that does not return a value is represented by the class. A task that returns a value is represented by the class, which inherits from . The task object handles the infrastructure details and provides methods and properties that are accessible from the calling thread throughout the lifetime of the task. For example, you can access the property of a task at any time to determine whether it has started running, ran to completion, was canceled, or has thrown an exception. The status is represented by a enumeration. - When you create a task, you give it a user delegate that encapsulates the code that the task will execute. The delegate can be expressed as a named delegate, an anonymous method, or a lambda expression. Lambda expressions can contain a call to a named method, as shown in the following example. Note that the example includes a call to the method to ensure that the task completes execution before the console mode application ends. + When you create a task, you give it a user delegate that encapsulates the code that the task will execute. The delegate can be expressed as a named delegate, an anonymous method, or a lambda expression. Lambda expressions can contain a call to a named method, as shown in the following example. Note that the example includes a call to the method to ensure that the task completes execution before the console mode application ends. [!code-csharp[TPL_TaskIntro#1](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/lambda1.cs#1)] [!code-vb[TPL_TaskIntro#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/lambda1.vb#1)] - You can also use the methods to create and start a task in one operation. To manage the task, the methods use the default task scheduler, regardless of which task scheduler is associated with the current thread. The methods are the preferred way to create and start tasks when more control over the creation and scheduling of the task is not needed. + You can also use the methods to create and start a task in one operation. To manage the task, the methods use the default task scheduler, regardless of which task scheduler is associated with the current thread. The methods are the preferred way to create and start tasks when more control over the creation and scheduling of the task is not needed. [!code-csharp[TPL_TaskIntro#2](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/run1.cs#2)] [!code-vb[TPL_TaskIntro#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/run1.vb#2)] - You can also use the method to create and start a task in one operation. Use this method when creation and scheduling do not have to be separated and you require additional task creation options or the use of a specific scheduler, or when you need to pass additional state into the task through its property, as shown in the following example. + You can also use the method to create and start a task in one operation. Use this method when creation and scheduling do not have to be separated and you require additional task creation options or the use of a specific scheduler, or when you need to pass additional state into the task through its property, as shown in the following example. [!code-csharp[TPL_TaskIntro#3](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/startnew1.cs#3)] [!code-vb[TPL_TaskIntro#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/startnew1.vb#3)] - and each expose a static property that returns a default instance of , so that you can call the method as `Task.Factory.StartNew()`. Also, in the following example, because the tasks are of type , they each have a public property that contains the result of the computation. The tasks run asynchronously and may complete in any order. If the property is accessed before the computation finishes, the property blocks the calling thread until the value is available. + and each expose a static property that returns a default instance of , so that you can call the method as `Task.Factory.StartNew()`. Also, in the following example, because the tasks are of type , they each have a public property that contains the result of the computation. The tasks run asynchronously and may complete in any order. If the property is accessed before the computation finishes, the property blocks the calling thread until the value is available. [!code-csharp[TPL_TaskIntro#4](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/result1.cs#4)] [!code-vb[TPL_TaskIntro#4](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/result1.vb#4)] @@ -80,13 +80,13 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre [!code-csharp[TPL_TaskIntro#21](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/iteration1a.cs#21)] [!code-vb[TPL_TaskIntro#21](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/iteration1a.vb#21)] - This state is passed as an argument to the task delegate, and it can be accessed from the task object by using the property. The following example is a variation on the previous example. It uses the property to display information about the `CustomData` objects passed to the lambda expression. + This state is passed as an argument to the task delegate, and it can be accessed from the task object by using the property. The following example is a variation on the previous example. It uses the property to display information about the `CustomData` objects passed to the lambda expression. [!code-csharp[TPL_TaskIntro#23](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/asyncstate.cs#23)] [!code-vb[TPL_TaskIntro#23](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/asyncstate.vb#23)] ## Task ID - Every task receives an integer ID that uniquely identifies it in an application domain and can be accessed by using the property. The ID is useful for viewing task information in the Visual Studio debugger **Parallel Stacks** and **Tasks** windows. The ID is lazily created, which means that it isn't created until it is requested; therefore, a task may have a different ID every time the program is run. For more information about how to view task IDs in the debugger, see [Using the Tasks Window](/visualstudio/debugger/using-the-tasks-window) and [Using the Parallel Stacks Window](/visualstudio/debugger/using-the-parallel-stacks-window). + Every task receives an integer ID that uniquely identifies it in an application domain and can be accessed by using the property. The ID is useful for viewing task information in the Visual Studio debugger **Parallel Stacks** and **Tasks** windows. The ID is lazily created, which means that it isn't created until it is requested; therefore, a task may have a different ID every time the program is run. For more information about how to view task IDs in the debugger, see [Using the Tasks Window](/visualstudio/debugger/using-the-tasks-window) and [Using the Parallel Stacks Window](/visualstudio/debugger/using-the-parallel-stacks-window). ## Task Creation Options Most APIs that create tasks provide overloads that accept a parameter. By specifying one of these options, you tell the task scheduler how to schedule the task on the thread pool. The following table lists the various task creation options. @@ -98,7 +98,7 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre ||Specifies that the task represents a long-running operation.| ||Specifies that a task should be created as an attached child of the current task, if one exists. For more information, see [Attached and Detached Child Tasks](../../../docs/standard/parallel-programming/attached-and-detached-child-tasks.md).| ||Specifies that if an inner task specifies the `AttachedToParent` option, that task will not become an attached child task.| -||Specifies that the task scheduler for tasks created by calling methods like or from within a particular task is the default scheduler instead of the scheduler on which this task is running.| +||Specifies that the task scheduler for tasks created by calling methods like or from within a particular task is the default scheduler instead of the scheduler on which this task is running.| The options may be combined by using a bitwise **OR** operation. The following example shows a task that has the and option. @@ -106,7 +106,7 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre [!code-vb[TPL_TaskIntro#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/tpl_intro.vb#03)] ## Tasks, threads, and culture - Each thread has an associated culture and UI culture, which is defined by the and properties, respectively. A thread's culture is used in such operations as formatting, parsing, sorting, and string comparison. A thread's UI culture is used in resource lookup. Ordinarily, unless you specify a default culture for all the threads in an application domain by using the and properties, the default culture and UI culture of a thread is defined by the system culture. If you explicitly set a thread's culture and launch a new thread, the new thread does not inherit the culture of the calling thread; instead, its culture is the default system culture. The task-based programming model for apps that target versions of the .NET Framework prior to [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] adhere to this practice. + Each thread has an associated culture and UI culture, which is defined by the and properties, respectively. A thread's culture is used in such operations as formatting, parsing, sorting, and string comparison. A thread's UI culture is used in resource lookup. Ordinarily, unless you specify a default culture for all the threads in an application domain by using the and properties, the default culture and UI culture of a thread is defined by the system culture. If you explicitly set a thread's culture and launch a new thread, the new thread does not inherit the culture of the calling thread; instead, its culture is the default system culture. The task-based programming model for apps that target versions of the .NET Framework prior to [!INCLUDE[net_v46](../../../includes/net-v46-md.md)] adhere to this practice. > [!IMPORTANT] > Note that the calling thread's culture as part of a task's context applies to apps that *target* the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)], not apps that *run under* the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)]. You can target a particular version of the .NET Framework when you create your project in Visual Studio by selecting that version from the dropdown list at the top of the **New Project** dialog box, or outside of Visual Studio you can use the attribute. For apps that target versions of the .NET Framework prior to the [!INCLUDE[net_v46](../../../includes/net-v46-md.md)], or that do not target a specific version of the .NET Framework, a task's culture continues to be determined by the culture of the thread on which it runs. @@ -125,14 +125,14 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre For more information on asynchronous tasks and culture, see the "Culture and asynchronous task-based operations" section in the topic. ## Creating task continuations - The and methods let you specify a task to start when the *antecedent task* finishes. The delegate of the continuation task is passed a reference to the antecedent task so that it can examine the antecedent task's status and, by retrieving the value of the property, can use the output of the antecedent as input for the continuation. + The and methods let you specify a task to start when the *antecedent task* finishes. The delegate of the continuation task is passed a reference to the antecedent task so that it can examine the antecedent task's status and, by retrieving the value of the property, can use the output of the antecedent as input for the continuation. - In the following example, the `getData` task is started by a call to the method. The `processData` task is started automatically when `getData` finishes, and `displayData` is started when `processData` finishes. `getData` produces an integer array, which is accessible to the `processData` task through the `getData` task's property. The `processData` task processes that array and returns a result whose type is inferred from the return type of the lambda expression passed to the method. The `displayData` task executes automatically when `processData` finishes, and the object returned by the `processData` lambda expression is accessible to the `displayData` task through the `processData` task's property. The `displayData` task takes the result of the `processData` task and produces a result whose type is inferred in a similar manner and which is made available to the program in the property. + In the following example, the `getData` task is started by a call to the method. The `processData` task is started automatically when `getData` finishes, and `displayData` is started when `processData` finishes. `getData` produces an integer array, which is accessible to the `processData` task through the `getData` task's property. The `processData` task processes that array and returns a result whose type is inferred from the return type of the lambda expression passed to the method. The `displayData` task executes automatically when `processData` finishes, and the object returned by the `processData` lambda expression is accessible to the `displayData` task through the `processData` task's property. The `displayData` task takes the result of the `processData` task and produces a result whose type is inferred in a similar manner and which is made available to the program in the property. [!code-csharp[TPL_TaskIntro#5](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/continuations1.cs#5)] [!code-vb[TPL_TaskIntro#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/continuations1.vb#5)] - Because is an instance method, you can chain method calls together instead of instantiating a object for each antecedent task. The following example is functionally identical to the previous example, except that it chains together calls to the method. Note that the object returned by the chain of method calls is the final continuation task. + Because is an instance method, you can chain method calls together instead of instantiating a object for each antecedent task. The following example is functionally identical to the previous example, except that it chains together calls to the method. Note that the object returned by the chain of method calls is the final continuation task. [!code-csharp[TPL_TaskIntro#24](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/continuations2.cs#24)] [!code-vb[TPL_TaskIntro#24](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/continuations2.vb#24)] @@ -150,15 +150,15 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre Note that the parent task does not wait for the detached child task to finish. ## Creating child tasks - When user code that is running in a task creates a task with the option, the new task is known as a *attached child task* of the parent task. You can use the option to express structured task parallelism, because the parent task implicitly waits for all attached child tasks to finish. The following example shows a parent task that creates ten attached child tasks. Note that although the example calls the method to wait for the parent task to finish, it does not have to explicitly wait for the attached child tasks to complete. + When user code that is running in a task creates a task with the option, the new task is known as a *attached child task* of the parent task. You can use the option to express structured task parallelism, because the parent task implicitly waits for all attached child tasks to finish. The following example shows a parent task that creates ten attached child tasks. Note that although the example calls the method to wait for the parent task to finish, it does not have to explicitly wait for the attached child tasks to complete. [!code-csharp[TPL_TaskIntro#8](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_taskintro/cs/child1.cs#8)] [!code-vb[TPL_TaskIntro#8](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_taskintro/vb/child1.vb#8)] - A parent task can use the option to prevent other tasks from attaching to the parent task. For more information, see [Attached and Detached Child Tasks](../../../docs/standard/parallel-programming/attached-and-detached-child-tasks.md). + A parent task can use the option to prevent other tasks from attaching to the parent task. For more information, see [Attached and Detached Child Tasks](../../../docs/standard/parallel-programming/attached-and-detached-child-tasks.md). ## Waiting for tasks to finish - The and types provide several overloads of the and `System.Threading.Tasks.Task.Wait` methods that enable you to wait for a task to finish. In addition, overloads of the static and methods let you wait for any or all of an array of tasks to finish. + The and types provide several overloads of the and `System.Threading.Tasks.Task.Wait` methods that enable you to wait for a task to finish. In addition, overloads of the static and methods let you wait for any or all of an array of tasks to finish. Typically, you would wait for a task for one of these reasons: @@ -177,16 +177,16 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre Some overloads let you specify a time-out, and others take an additional as an input parameter, so that the wait itself can be canceled either programmatically or in response to user input. - When you wait for a task, you implicitly wait for all children of that task that were created by using the option. returns immediately if the task has already completed. Any exceptions raised by a task will be thrown by a method, even if the method was called after the task completed. + When you wait for a task, you implicitly wait for all children of that task that were created by using the option. returns immediately if the task has already completed. Any exceptions raised by a task will be thrown by a method, even if the method was called after the task completed. ## Composing tasks The and classes provide several methods that can help you compose multiple tasks to implement common patterns and to better use the asynchronous language features that are provided by C#, [!INCLUDE[vbprvb](../../../includes/vbprvb-md.md)], and F#. This section describes the , , , and methods. ### Task.WhenAll - The method asynchronously waits for multiple or objects to finish. It provides overloaded versions that enable you to wait for non-uniform sets of tasks. For example, you can wait for multiple and objects to complete from one method call. + The method asynchronously waits for multiple or objects to finish. It provides overloaded versions that enable you to wait for non-uniform sets of tasks. For example, you can wait for multiple and objects to complete from one method call. ### Task.WhenAny - The method asynchronously waits for one of multiple or objects to finish. As in the method, this method provides overloaded versions that enable you to wait for non-uniform sets of tasks. The method is especially useful in the following scenarios. + The method asynchronously waits for one of multiple or objects to finish. As in the method, this method provides overloaded versions that enable you to wait for non-uniform sets of tasks. The method is especially useful in the following scenarios. - Redundant operations. Consider an algorithm or operation that can be performed in many ways. You can use the method to select the operation that finishes first and then cancel the remaining operations. @@ -197,10 +197,10 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre - Expired operations. You can use the method to select between one or more tasks and a task that finishes after a specific time, such as a task that is returned by the method. The method is described in the following section. ### Task.Delay - The method produces a object that finishes after the specified time. You can use this method to build loops that occasionally poll for data, introduce time-outs, delay the handling of user input for a predetermined time, and so on. + The method produces a object that finishes after the specified time. You can use this method to build loops that occasionally poll for data, introduce time-outs, delay the handling of user input for a predetermined time, and so on. ### Task(T).FromResult - By using the method, you can create a object that holds a pre-computed result. This method is useful when you perform an asynchronous operation that returns a object, and the result of that object is already computed. For an example that uses to retrieve the results of asynchronous download operations that are held in a cache, see [How to: Create Pre-Computed Tasks](../../../docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md). + By using the method, you can create a object that holds a pre-computed result. This method is useful when you perform an asynchronous operation that returns a object, and the result of that object is already computed. For an example that uses to retrieve the results of asynchronous download operations that are held in a cache, see [How to: Create Pre-Computed Tasks](../../../docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md). ## Handling exceptions in tasks When a task throws one or more exceptions, the exceptions are wrapped in an exception. That exception is propagated back to the thread that joins with the task, which is typically the thread that is waiting for the task to finish or the thread that accesses the property. This behavior serves to enforce the .NET Framework policy that all unhandled exceptions by default should terminate the process. The calling code can handle the exceptions by using any of the following in a `try`/`catch` block: @@ -218,7 +218,7 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre For more information about exceptions and tasks, see [Exception Handling](../../../docs/standard/parallel-programming/exception-handling-task-parallel-library.md). ## Canceling tasks - The `Task` class supports cooperative cancellation and is fully integrated with the and classes, which were introduced in the .NET Framework 4. Many of the constructors in the class take a object as an input parameter. Many of the and overloads also include a parameter. + The `Task` class supports cooperative cancellation and is fully integrated with the and classes, which were introduced in the .NET Framework 4. Many of the constructors in the class take a object as an input parameter. Many of the and overloads also include a parameter. You can create the token, and issue the cancellation request at some later time, by using the class. Pass the token to the as an argument, and also reference the same token in your user delegate, which does the work of responding to a cancellation request. @@ -239,15 +239,15 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre In some cases, you may want to use a to encapsulate some asynchronous operation that is performed by an external component instead of your own user delegate. If the operation is based on the Asynchronous Programming Model Begin/End pattern, you can use the methods. If that is not the case, you can use the object to wrap the operation in a task and thereby gain some of the benefits of programmability, for example, support for exception propagation and continuations. For more information, see . ## Custom schedulers - Most application or library developers do not care which processor the task runs on, how it synchronizes its work with other tasks, or how it is scheduled on the . They only require that it execute as efficiently as possible on the host computer. If you require more fine-grained control over the scheduling details, the Task Parallel Library lets you configure some settings on the default task scheduler, and even lets you supply a custom scheduler. For more information, see . + Most application or library developers do not care which processor the task runs on, how it synchronizes its work with other tasks, or how it is scheduled on the . They only require that it execute as efficiently as possible on the host computer. If you require more fine-grained control over the scheduling details, the Task Parallel Library lets you configure some settings on the default task scheduler, and even lets you supply a custom scheduler. For more information, see . ## Related data structures - The TPL has several new public types that are useful in both parallel and sequential scenarios. These include several thread-safe, fast and scalable collection classes in the namespace, and several new synchronization types, for example, and , which are more efficient than their predecessors for specific kinds of workloads. Other new types in the .NET Framework 4, for example, and , provide functionality that was not available in earlier releases. For more information, see [Data Structures for Parallel Programming](../../../docs/standard/parallel-programming/data-structures-for-parallel-programming.md). + The TPL has several new public types that are useful in both parallel and sequential scenarios. These include several thread-safe, fast and scalable collection classes in the namespace, and several new synchronization types, for example, and , which are more efficient than their predecessors for specific kinds of workloads. Other new types in the .NET Framework 4, for example, and , provide functionality that was not available in earlier releases. For more information, see [Data Structures for Parallel Programming](../../../docs/standard/parallel-programming/data-structures-for-parallel-programming.md). ## Custom task types - We recommend that you do not inherit from or . Instead, we recommend that you use the property to associate additional data or state with a or object. You can also use extension methods to extend the functionality of the and classes. For more information about extension methods, see [Extension Methods](~/docs/csharp/programming-guide/classes-and-structs/extension-methods.md) and [Extension Methods](~/docs/visual-basic/programming-guide/language-features/procedures/extension-methods.md). + We recommend that you do not inherit from or . Instead, we recommend that you use the property to associate additional data or state with a or object. You can also use extension methods to extend the functionality of the and classes. For more information about extension methods, see [Extension Methods](~/docs/csharp/programming-guide/classes-and-structs/extension-methods.md) and [Extension Methods](~/docs/visual-basic/programming-guide/language-features/procedures/extension-methods.md). - If you must inherit from or , you cannot use , , or the , , or classes to create instances of your custom task type because these mechanisms create only and objects. In addition, you cannot use the task continuation mechanisms that are provided by , , , and to create instances of your custom task type because these mechanisms also create only and objects. + If you must inherit from or , you cannot use , , or the , , or classes to create instances of your custom task type because these mechanisms create only and objects. In addition, you cannot use the task continuation mechanisms that are provided by , , , and to create instances of your custom task type because these mechanisms also create only and objects. ## Related topics @@ -260,7 +260,7 @@ The Task Parallel Library (TPL) is based on the concept of a *task*, which repre |[How to: Use Parallel.Invoke to Execute Parallel Operations](../../../docs/standard/parallel-programming/how-to-use-parallel-invoke-to-execute-parallel-operations.md)|Describes how to use .| |[How to: Return a Value from a Task](../../../docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md)|Describes how to return values from tasks.| |[How to: Cancel a Task and Its Children](../../../docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md)|Describes how to cancel tasks.| -|[How to: Create Pre-Computed Tasks](../../../docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md)|Describes how to use the method to retrieve the results of asynchronous download operations that are held in a cache.| +|[How to: Create Pre-Computed Tasks](../../../docs/standard/parallel-programming/how-to-create-pre-computed-tasks.md)|Describes how to use the method to retrieve the results of asynchronous download operations that are held in a cache.| |[How to: Traverse a Binary Tree with Parallel Tasks](../../../docs/standard/parallel-programming/how-to-traverse-a-binary-tree-with-parallel-tasks.md)|Describes how to use tasks to traverse a binary tree.| |[How to: Unwrap a Nested Task](../../../docs/standard/parallel-programming/how-to-unwrap-a-nested-task.md)|Demonstrates how to use the extension method.| |[Data Parallelism](../../../docs/standard/parallel-programming/data-parallelism-task-parallel-library.md)|Describes how to use and to create parallel loops over data.| diff --git a/docs/standard/parallel-programming/task-cancellation.md b/docs/standard/parallel-programming/task-cancellation.md index 44016358c0959..e58358d005764 100644 --- a/docs/standard/parallel-programming/task-cancellation.md +++ b/docs/standard/parallel-programming/task-cancellation.md @@ -18,9 +18,9 @@ ms.author: "ronpet" manager: "wpickett" --- # Task Cancellation -The and classes support cancellation through the use of cancellation tokens in the .NET Framework. For more information, see [Cancellation in Managed Threads](../../../docs/standard/threading/cancellation-in-managed-threads.md). In the Task classes, cancellation involves cooperation between the user delegate, which represents a cancelable operation and the code that requested the cancellation. A successful cancellation involves the requesting code calling the method, and the user delegate terminating the operation in a timely manner. You can terminate the operation by using one of these options: +The and classes support cancellation through the use of cancellation tokens in the .NET Framework. For more information, see [Cancellation in Managed Threads](../../../docs/standard/threading/cancellation-in-managed-threads.md). In the Task classes, cancellation involves cooperation between the user delegate, which represents a cancelable operation and the code that requested the cancellation. A successful cancellation involves the requesting code calling the method, and the user delegate terminating the operation in a timely manner. You can terminate the operation by using one of these options: -- By simply returning from the delegate. In many scenarios this is sufficient; however, a task instance that is canceled in this way transitions to the state, not to the state. +- By simply returning from the delegate. In many scenarios this is sufficient; however, a task instance that is canceled in this way transitions to the state, not to the state. - By throwing a and passing it the token on which cancellation was requested. The preferred way to do this is to use the method. A task that is canceled in this way transitions to the Canceled state, which the calling code can use to verify that the task responded to its cancellation request. @@ -33,7 +33,7 @@ The and thrown by user code, it compares the exception's token to its associated token (the one that was passed to the API that created the Task). If they are the same and the token's property returns true, the task interprets this as acknowledging cancellation and transitions to the Canceled state. If you do not use a or method to wait for the task, then the task just sets its status to . - If you are waiting on a Task that transitions to the Canceled state, a exception (wrapped in an exception) is thrown. Note that this exception indicates successful cancellation instead of a faulty situation. Therefore, the task's property returns `null`. + If you are waiting on a Task that transitions to the Canceled state, a exception (wrapped in an exception) is thrown. Note that this exception indicates successful cancellation instead of a faulty situation. Therefore, the task's property returns `null`. If the token's property returns false or if the exception's token does not match the Task's token, the is treated like a normal exception, causing the Task to transition to the Faulted state. Also note that the presence of other exceptions will also cause the Task to transition to the Faulted state. You can get the status of the completed task in the property. diff --git a/docs/standard/parallel-programming/task-parallel-library-tpl.md b/docs/standard/parallel-programming/task-parallel-library-tpl.md index 776963b00b583..fe13e733d361e 100644 --- a/docs/standard/parallel-programming/task-parallel-library-tpl.md +++ b/docs/standard/parallel-programming/task-parallel-library-tpl.md @@ -19,7 +19,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Task Parallel Library (TPL) -The Task Parallel Library (TPL) is a set of public types and APIs in the and namespaces. The purpose of the TPL is to make developers more productive by simplifying the process of adding parallelism and concurrency to applications. The TPL scales the degree of concurrency dynamically to most efficiently use all the processors that are available. In addition, the TPL handles the partitioning of the work, the scheduling of threads on the , cancellation support, state management, and other low-level details. By using TPL, you can maximize the performance of your code while focusing on the work that your program is designed to accomplish. +The Task Parallel Library (TPL) is a set of public types and APIs in the and namespaces. The purpose of the TPL is to make developers more productive by simplifying the process of adding parallelism and concurrency to applications. The TPL scales the degree of concurrency dynamically to most efficiently use all the processors that are available. In addition, the TPL handles the partitioning of the work, the scheduling of threads on the , cancellation support, state management, and other low-level details. By using TPL, you can maximize the performance of your code while focusing on the work that your program is designed to accomplish. Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], the TPL is the preferred way to write multithreaded and parallel code. However, not all code is suitable for parallelization; for example, if a loop performs only a small amount of work on each iteration, or it doesn't run for many iterations, then the overhead of parallelization can cause the code to run more slowly. Furthermore, parallelization like any multithreaded code adds complexity to your program execution. Although the TPL simplifies multithreaded scenarios, we recommend that you have a basic understanding of threading concepts, for example, locks, deadlocks, and race conditions, so that you can use the TPL effectively. @@ -28,7 +28,7 @@ The Task Parallel Library (TPL) is a set of public types and APIs in the or explicitly by using objects directly.| +|[Task-based Asynchronous Programming](../../../docs/standard/parallel-programming/task-based-asynchronous-programming.md)|Describes how to create and run tasks implicitly by using or explicitly by using objects directly.| |[Dataflow](../../../docs/standard/parallel-programming/dataflow-task-parallel-library.md)|Describes how to use the dataflow components in the TPL Dataflow Library to handle multiple operations that must communicate with one another or to process data as it becomes available.| |[Using TPL with Other Asynchronous Patterns](../../../docs/standard/parallel-programming/using-tpl-with-other-asynchronous-patterns.md)|Describes how to use TPL with other asynchronous patterns in .NET| |[Potential Pitfalls in Data and Task Parallelism](../../../docs/standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md)|Describes some common pitfalls and how to avoid them.| diff --git a/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md b/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md index 620f31abeb1de..1825db4924439 100644 --- a/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md +++ b/docs/standard/parallel-programming/tpl-and-traditional-async-programming.md @@ -19,9 +19,9 @@ manager: "wpickett" # TPL and Traditional .NET Framework Asynchronous Programming The .NET Framework provides the following two standard patterns for performing I/O-bound and compute-bound asynchronous operations: -- Asynchronous Programming Model (APM), in which asynchronous operations are represented by a pair of Begin/End methods such as and . +- Asynchronous Programming Model (APM), in which asynchronous operations are represented by a pair of Begin/End methods such as and . -- Event-based asynchronous pattern (EAP), in which asynchronous operations are represented by a method/event pair that are named *OperationName*Async and *OperationName*Completed, for example, and . (EAP was introduced in the .NET Framework version 2.0.) +- Event-based asynchronous pattern (EAP), in which asynchronous operations are represented by a method/event pair that are named *OperationName*Async and *OperationName*Completed, for example, and . (EAP was introduced in the .NET Framework version 2.0.) The Task Parallel Library (TPL) can be used in various ways in conjunction with either of the asynchronous patterns. You can expose both APM and EAP operations as Tasks to library consumers, or you can expose the APM patterns but use Task objects to implement them internally. In both scenarios, by using Task objects, you can simplify the code and take advantage of the following useful functionality: @@ -36,18 +36,18 @@ The .NET Framework provides the following two standard patterns for performing I - Marshal the status of an operation to a Task object by using . ## Wrapping APM Operations in a Task - Both the and classes provide several overloads of the and methods that let you encapsulate an APM Begin/End method pair in one or instance. The various overloads accommodate any Begin/End method pair that have from zero to three input parameters. + Both the and classes provide several overloads of the and methods that let you encapsulate an APM Begin/End method pair in one or instance. The various overloads accommodate any Begin/End method pair that have from zero to three input parameters. For pairs that have `End` methods that return a value (`Function` in Visual Basic), use the methods in that create a . For `End` methods that return void (`Sub` in Visual Basic), use the methods in that create a . For those few cases in which the `Begin` method has more than three parameters or contains `ref` or `out` parameters, additional `FromAsync` overloads that encapsulate only the `End` method are provided. - The following example shows the signature for the `FromAsync` overload that matches the and methods. This overload takes three input parameters, as follows. + The following example shows the signature for the `FromAsync` overload that matches the and methods. This overload takes three input parameters, as follows. [!code-csharp[FromAsync#01](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#01)] [!code-vb[FromAsync#01](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#01)] - The first parameter is a delegate that matches the signature of the method. The second parameter is a delegate that takes an and returns a `TResult`. Because returns an integer, the compiler infers the type of `TResult` as and the type of the task as . The last four parameters are identical to those in the method: + The first parameter is a delegate that matches the signature of the method. The second parameter is a delegate that takes an and returns a `TResult`. Because returns an integer, the compiler infers the type of `TResult` as and the type of the task as . The last four parameters are identical to those in the method: - The buffer in which to store the file data. @@ -83,7 +83,7 @@ The .NET Framework provides the following two standard patterns for performing I [!code-vb[FromAsync#06](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#06)] ### FromAsync Tasks For Only the End Method - For those few cases in which the `Begin` method requires more than three input parameters, or has `ref` or `out` parameters, you can use the `FromAsync` overloads, for example, , that represent only the `End` method. These methods can also be used in any scenario in which you are passed an and want to encapsulate it in a Task. + For those few cases in which the `Begin` method requires more than three input parameters, or has `ref` or `out` parameters, you can use the `FromAsync` overloads, for example, , that represent only the `End` method. These methods can also be used in any scenario in which you are passed an and want to encapsulate it in a Task. [!code-csharp[FromAsync#07](../../../samples/snippets/csharp/VS_Snippets_Misc/fromasync/cs/fromasync.cs#07)] [!code-vb[FromAsync#07](../../../samples/snippets/visualbasic/VS_Snippets_Misc/fromasync/vb/module1.vb#07)] @@ -96,7 +96,7 @@ The .NET Framework provides the following two standard patterns for performing I Some classes that support EAP, for example, , do support cancellation, and you can integrate that native cancellation functionality by using cancellation tokens. ## Exposing Complex EAP Operations As Tasks - The TPL does not provide any methods that are specifically designed to encapsulate an event-based asynchronous operation in the same way that the `FromAsync` family of methods wrap the pattern. However, the TPL does provide the class, which can be used to represent any arbitrary set of operations as a . The operations may be synchronous or asynchronous, and may be I/O bound or compute-bound, or both. + The TPL does not provide any methods that are specifically designed to encapsulate an event-based asynchronous operation in the same way that the `FromAsync` family of methods wrap the pattern. However, the TPL does provide the class, which can be used to represent any arbitrary set of operations as a . The operations may be synchronous or asynchronous, and may be I/O bound or compute-bound, or both. The following example shows how to use a to expose a set of asynchronous operations to client code as a basic . The method lets you enter an array of Web URLs, and a term or name to search for, and then returns the number of times the search term occurs on each site. diff --git a/docs/standard/parallel-programming/understanding-speedup-in-plinq.md b/docs/standard/parallel-programming/understanding-speedup-in-plinq.md index 7fd7d8aeccce8..f9fcadf8db815 100644 --- a/docs/standard/parallel-programming/understanding-speedup-in-plinq.md +++ b/docs/standard/parallel-programming/understanding-speedup-in-plinq.md @@ -69,7 +69,7 @@ The primary purpose of PLINQ is to speed up the execution of LINQ to Objects que ## When PLINQ Chooses Sequential Mode PLINQ will always attempt to execute a query at least as fast as the query would run sequentially. Although PLINQ does not look at how computationally expensive the user delegates are, or how big the input source is, it does look for certain query "shapes." Specifically, it looks for query operators or combinations of operators that typically cause a query to execute more slowly in parallel mode. When it finds such shapes, PLINQ by default falls back to sequential mode. - However, after measuring a specific query's performance, you may determine that it actually runs faster in parallel mode. In such cases you can use the flag via the method to instruct PLINQ to parallelize the query. For more information, see [How to: Specify the Execution Mode in PLINQ](../../../docs/standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md). + However, after measuring a specific query's performance, you may determine that it actually runs faster in parallel mode. In such cases you can use the flag via the method to instruct PLINQ to parallelize the query. For more information, see [How to: Specify the Execution Mode in PLINQ](../../../docs/standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md). The following list describes the query shapes that PLINQ by default will execute in sequential mode: diff --git a/docs/standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md b/docs/standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md index 054b8cbb9eea7..a8f2c307ce010 100644 --- a/docs/standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md +++ b/docs/standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md @@ -25,7 +25,7 @@ Although the TPL Dataflow Library provides several dataflow block types that ena Read [Dataflow](../../../docs/standard/parallel-programming/dataflow-task-parallel-library.md) before you read this document. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Defining the Sliding Window Dataflow Block Consider a dataflow application that requires that input values be buffered and then output in a sliding window manner. For example, for the input values {0, 1, 2, 3, 4, 5} and a window size of three, a sliding window dataflow block produces the output arrays {0, 1, 2}, {1, 2, 3}, {2, 3, 4}, and {3, 4, 5}. The following sections describe two ways to create a dataflow block type that implements this custom behavior. The first technique uses the method to combine the functionality of an object and an object into one propagator block. The second technique defines a class that derives from and combines existing functionality to perform custom behavior. diff --git a/docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md b/docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md index 21633735ba085..4752bda17f42c 100644 --- a/docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md +++ b/docs/standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md @@ -19,10 +19,10 @@ ms.author: "ronpet" manager: "wpickett" --- # Walkthrough: Creating a Dataflow Pipeline -Although you can use the , , and methods to receive messages from source blocks, you can also connect message blocks to form a *dataflow pipeline*. A dataflow pipeline is a series of components, or *dataflow blocks*, each of which performs a specific task that contributes to a larger goal. Every dataflow block in a dataflow pipeline performs work when it receives a message from another dataflow block. An analogy to this is an assembly line for automobile manufacturing. As each vehicle passes through the assembly line, one station assembles the frame, the next one installs the engine, and so on. Because an assembly line enables multiple vehicles to be assembled at the same time, it provides better throughput than assembling complete vehicles one at a time. +Although you can use the , , and methods to receive messages from source blocks, you can also connect message blocks to form a *dataflow pipeline*. A dataflow pipeline is a series of components, or *dataflow blocks*, each of which performs a specific task that contributes to a larger goal. Every dataflow block in a dataflow pipeline performs work when it receives a message from another dataflow block. An analogy to this is an assembly line for automobile manufacturing. As each vehicle passes through the assembly line, one station assembles the frame, the next one installs the engine, and so on. Because an assembly line enables multiple vehicles to be assembled at the same time, it provides better throughput than assembling complete vehicles one at a time. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. This document demonstrates a dataflow pipeline that downloads the book *The Iliad of Homer* from a website and searches the text to match individual words with words that reverse the first word's characters. The formation of the dataflow pipeline in this document consists of the following steps: @@ -97,7 +97,7 @@ Although you can use the to synchronously send data to the head of the pipeline. Use the method when you must asynchronously send data to a dataflow node. + This example uses to synchronously send data to the head of the pipeline. Use the method when you must asynchronously send data to a dataflow node. ## Completing Pipeline Activity Add the following code to mark the head of the pipeline as completed. The head of the pipeline runs its continuation task after it processes all buffered messages. This continuation task propagates the completed state through the pipeline. @@ -105,7 +105,7 @@ Although you can use the method after you submit all the input. You can omit this step if your application has no well-defined point at which data is no longer available or the application does not have to wait for the pipeline to finish. + This example sends one URL through the dataflow pipeline to be processed. If you send more than one input through a pipeline, call the method after you submit all the input. You can omit this step if your application has no well-defined point at which data is no longer available or the application does not have to wait for the pipeline to finish. ## Waiting for the Pipeline to Finish Add the following code to wait for the pipeline to finish. Because this example uses continuation tasks to propagate completion through the pipeline, the overall operation is finished when the tail of the pipeline finishes. @@ -124,7 +124,7 @@ Although you can use the method to process multiple items in the work list in parallel. The use of fine-grained parallelism in a coarse-grained pipeline can improve overall throughput. + The parallelism that is achieved by using dataflow pipelines is known as *coarse-grained parallelism* because it typically consists of fewer, larger tasks. You can also use a more *fine-grained parallelism* of smaller, short-running tasks in a dataflow pipeline. In this example, the `findReversedWords` member of the pipeline uses the method to process multiple items in the work list in parallel. The use of fine-grained parallelism in a coarse-grained pipeline can improve overall throughput. You can also connect a source dataflow block to multiple target blocks to create a *dataflow network*. The overloaded version of the method takes a object that defines whether the target block accepts each message based on its value. Most dataflow block types that act as sources offer messages to all connected target blocks, in the order in which they were connected, until one of the blocks accepts that message. By using this filtering mechanism, you can create systems of connected dataflow blocks that direct certain data through one path and other data through another path. For an example that uses filtering to create a dataflow network, see [Walkthrough: Using Dataflow in a Windows Forms Application](../../../docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md). diff --git a/docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md b/docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md index 36f70ffc35c1e..cb699fb779629 100644 --- a/docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md +++ b/docs/standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md @@ -18,10 +18,10 @@ ms.author: "ronpet" manager: "wpickett" --- # Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency -The TPL Dataflow Library provides the and classes so that you can receive and buffer data from one or more sources and then propagate out that buffered data as one collection. This batching mechanism is useful when you collect data from one or more sources and then process multiple data elements as a batch. For example, consider an application that uses dataflow to insert records into a database. This operation can be more efficient if multiple items are inserted at the same time instead of one at a time sequentially. This document describes how to use the class to improve the efficiency of such database insert operations. It also describes how to use the class to capture both the results and any exceptions that occur when the program reads from a database. +The TPL Dataflow Library provides the and classes so that you can receive and buffer data from one or more sources and then propagate out that buffered data as one collection. This batching mechanism is useful when you collect data from one or more sources and then process multiple data elements as a batch. For example, consider an application that uses dataflow to insert records into a database. This operation can be more efficient if multiple items are inserted at the same time instead of one at a time sequentially. This document describes how to use the class to improve the efficiency of such database insert operations. It also describes how to use the class to capture both the results and any exceptions that occur when the program reads from a database. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Prerequisites @@ -109,7 +109,7 @@ The TPL Dataflow Library provides the class to store `Employee` objects for successful calls to `GetEmployeeID` and objects for calls that fail. The object in this example acts on a object that holds a list of `Employee` objects and a list of objects. The object propagates out this data when the sum of the received `Employee` and object counts equals the batch size. + This method prints information about random employees to the console. It creates several random `Employee` objects and calls the `GetEmployeeID` method to retrieve the unique identifier for each object. Because the `GetEmployeeID` method throws an exception if there is no matching employee with the given first and last names, the `GetRandomEmployees` method uses the class to store `Employee` objects for successful calls to `GetEmployeeID` and objects for calls that fail. The object in this example acts on a object that holds a list of `Employee` objects and a list of objects. The object propagates out this data when the sum of the received `Employee` and object counts equals the batch size. ## The Complete Example diff --git a/docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md b/docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md index a691acf6fa13a..d5827085f92a8 100644 --- a/docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md +++ b/docs/standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md @@ -27,10 +27,10 @@ This document demonstrates how to create a network of dataflow blocks that perfo Read [Dataflow](../../../docs/standard/parallel-programming/dataflow-task-parallel-library.md) before you start this walkthrough. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. > [!TIP] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](../../../includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](../../../includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ## Sections This walkthrough contains the following sections: @@ -88,7 +88,7 @@ This document demonstrates how to create a network of dataflow blocks that perfo [!code-csharp[TPLDataflow_CompositeImages#5](../../../samples/snippets/csharp/VS_Snippets_Misc/tpldataflow_compositeimages/cs/compositeimages/form1.cs#5)] > [!NOTE] - > The C# version of the `CreateCompositeBitmap` method uses pointers to enable efficient processing of the objects. Therefore, you must enable the **Allow unsafe code** option in your project in order to use the [unsafe](~/docs/csharp/language-reference/keywords/unsafe.md) keyword. For more information about how to enable unsafe code in a [!INCLUDE[csprcs](../../../includes/csprcs-md.md)] project, see [Build Page, Project Designer (C#)]https://msdn.microsoft.com/library/kb4wyys2). + > The C# version of the `CreateCompositeBitmap` method uses pointers to enable efficient processing of the objects. Therefore, you must enable the **Allow unsafe code** option in your project in order to use the [unsafe](~/docs/csharp/language-reference/keywords/unsafe.md) keyword. For more information about how to enable unsafe code in a [!INCLUDE[csprcs](../../../includes/csprcs-md.md)] project, see [Build Page, Project Designer (C#)]https://msdn.microsoft.com/library/kb4wyys2). The following table describes the members of the network. @@ -105,7 +105,7 @@ This document demonstrates how to create a network of dataflow blocks that perfo ![The image processing network](../../../docs/standard/parallel-programming/media/dataflowwinforms.png "DataflowWinForms") - Because the `displayCompositeBitmap` and `operationCancelled` dataflow blocks act on the user interface, it is important that these actions occur on the user-interface thread. To accomplish this, during construction, these objects each provide a object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `CreateImageProcessingNetwork` method is called from the handler of the **Choose Folder** button, which runs on the user-interface thread, the actions for the `displayCompositeBitmap` and `operationCancelled` dataflow blocks also run on the user-interface thread. + Because the `displayCompositeBitmap` and `operationCancelled` dataflow blocks act on the user interface, it is important that these actions occur on the user-interface thread. To accomplish this, during construction, these objects each provide a object that has the property set to . The method creates a object that performs work on the current synchronization context. Because the `CreateImageProcessingNetwork` method is called from the handler of the **Choose Folder** button, which runs on the user-interface thread, the actions for the `displayCompositeBitmap` and `operationCancelled` dataflow blocks also run on the user-interface thread. This example uses a shared cancellation token instead of setting the property because the property permanently cancels dataflow block execution. A cancellation token enables this example to reuse the same dataflow network multiple times, even when the user cancels one or more operations. For an example that uses to permanently cancel the execution of a dataflow block, see [How to: Cancel a Dataflow Block](../../../docs/standard/parallel-programming/how-to-cancel-a-dataflow-block.md). diff --git a/docs/standard/security/cryptographic-services.md b/docs/standard/security/cryptographic-services.md index a9421b1bd0d26..6748fde9cc4b9 100644 --- a/docs/standard/security/cryptographic-services.md +++ b/docs/standard/security/cryptographic-services.md @@ -43,7 +43,7 @@ manager: "wpickett" # Cryptographic Services Public networks such as the Internet do not provide a means of secure communication between entities. Communication over such networks is susceptible to being read or even modified by unauthorized third parties. Cryptography helps protect data from being viewed, provides ways to detect whether data has been modified, and helps provide a secure means of communication over otherwise nonsecure channels. For example, data can be encrypted by using a cryptographic algorithm, transmitted in an encrypted state, and later decrypted by the intended party. If a third party intercepts the encrypted data, it will be difficult to decipher. - In the .NET Framework, the classes in the namespace manage many details of cryptography for you. Some are wrappers for the unmanaged Microsoft Cryptography API (CryptoAPI), while others are purely managed implementations. You do not need to be an expert in cryptography to use these classes. When you create a new instance of one of the encryption algorithm classes, keys are autogenerated for ease of use, and default properties are as safe and secure as possible. + In the .NET Framework, the classes in the namespace manage many details of cryptography for you. Some are wrappers for the unmanaged Microsoft Cryptography API (CryptoAPI), while others are purely managed implementations. You do not need to be an expert in cryptography to use these classes. When you create a new instance of one of the encryption algorithm classes, keys are autogenerated for ease of use, and default properties are as safe and secure as possible. This overview provides a synopsis of the encryption methods and practices supported by the .NET Framework, including the ClickOnce manifests, Suite B, and Cryptography Next Generation (CNG) support introduced in the [!INCLUDE[net_v35_long](../../../includes/net-v35-long-md.md)]. diff --git a/docs/standard/security/cryptographic-signatures.md b/docs/standard/security/cryptographic-signatures.md index ea160ffcb5c9b..b07d434edc3d9 100644 --- a/docs/standard/security/cryptographic-signatures.md +++ b/docs/standard/security/cryptographic-signatures.md @@ -36,7 +36,7 @@ manager: "wpickett" # Cryptographic Signatures Cryptographic digital signatures use public key algorithms to provide data integrity. When you sign data with a digital signature, someone else can verify the signature, and can prove that the data originated from you and was not altered after you signed it. For more information about digital signatures, see [Cryptographic Services](../../../docs/standard/security/cryptographic-services.md). - This topic explains how to generate and verify digital signatures using classes in the namespace. + This topic explains how to generate and verify digital signatures using classes in the namespace. - [Generating Signatures](#generate) @@ -145,7 +145,7 @@ RSAKeyInfo.Exponent = ExponentData; The following example illustrates this process. In this example, `HashValue` and `SignedHashValue` are arrays of bytes provided by a remote party. The remote party has signed the `HashValue` using the SHA1 algorithm, producing the digital signature `SignedHashValue`. The - method verifies that the digital signature is valid and was used to sign the `HashValue`. + method verifies that the digital signature is valid and was used to sign the `HashValue`. ```vb Dim RSA As New RSACryptoServiceProvider() diff --git a/docs/standard/security/encrypting-data.md b/docs/standard/security/encrypting-data.md index 93cdf26061c5c..5b1583d9981b2 100644 --- a/docs/standard/security/encrypting-data.md +++ b/docs/standard/security/encrypting-data.md @@ -177,7 +177,7 @@ The connection failed. ## Asymmetric Encryption Asymmetric algorithms are usually used to encrypt small amounts of data such as the encryption of a symmetric key and IV. Typically, an individual performing asymmetric encryption uses the public key generated by another party. The class is provided by the .NET Framework for this purpose. - The following example uses public key information to encrypt a symmetric key and IV. Two byte arrays are initialized that represent the public key of a third party. An object is initialized to these values. Next, the **RSAParameters** object (along with the public key it represents) is imported into an **RSACryptoServiceProvider** using the method. Finally, the private key and IV created by a class are encrypted. This example requires systems to have 128-bit encryption installed. + The following example uses public key information to encrypt a symmetric key and IV. Two byte arrays are initialized that represent the public key of a third party. An object is initialized to these values. Next, the **RSAParameters** object (along with the public key it represents) is imported into an **RSACryptoServiceProvider** using the method. Finally, the private key and IV created by a class are encrypted. This example requires systems to have 128-bit encryption installed. ```vb Imports System diff --git a/docs/standard/security/ensuring-data-integrity-with-hash-codes.md b/docs/standard/security/ensuring-data-integrity-with-hash-codes.md index 26032db5375ef..f5991bdf58dd5 100644 --- a/docs/standard/security/ensuring-data-integrity-with-hash-codes.md +++ b/docs/standard/security/ensuring-data-integrity-with-hash-codes.md @@ -30,7 +30,7 @@ manager: "wpickett" # Ensuring Data Integrity with Hash Codes A hash value is a numeric value of a fixed length that uniquely identifies data. Hash values represent large amounts of data as much smaller numeric values, so they are used with digital signatures. You can sign a hash value more efficiently than signing the larger value. Hash values are also useful for verifying the integrity of data sent through insecure channels. The hash value of received data can be compared to the hash value of data as it was sent to determine whether the data was altered. - This topic describes how to generate and verify hash codes by using the classes in the namespace. + This topic describes how to generate and verify hash codes by using the classes in the namespace. ## Generating a Hash The managed hash classes can hash either an array of bytes or a managed stream object. The following example uses the SHA1 hash algorithm to create a hash value for a string. The example uses the class to convert the string into an array of bytes that are hashed by using the class. The hash value is then displayed to the console. diff --git a/docs/standard/security/how-to-create-a-windowsprincipal-object.md b/docs/standard/security/how-to-create-a-windowsprincipal-object.md index b347e9633c0a8..0de2198e90a2d 100644 --- a/docs/standard/security/how-to-create-a-windowsprincipal-object.md +++ b/docs/standard/security/how-to-create-a-windowsprincipal-object.md @@ -31,7 +31,7 @@ There are two ways to create a ### To create a WindowsPrincipal object for repeated validation -1. Call the method on the object that is returned by the static property, passing the method a enumeration value that indicates what the new policy should be. Supported values are , , and . The following code demonstrates this method call. +1. Call the method on the object that is returned by the static property, passing the method a enumeration value that indicates what the new policy should be. Supported values are , , and . The following code demonstrates this method call. ```csharp AppDomain.CurrentDomain.SetPrincipalPolicy( @@ -43,7 +43,7 @@ There are two ways to create a PrincipalPolicy.WindowsPrincipal) ``` -2. With the policy set, use the static property to retrieve the principal that encapsulates the current Windows user. Because the property return type is , you must cast the result to a type. The following code initializes a new object to the value of the principal associated with the current thread. +2. With the policy set, use the static property to retrieve the principal that encapsulates the current Windows user. Because the property return type is , you must cast the result to a type. The following code initializes a new object to the value of the principal associated with the current thread. ```csharp WindowsPrincipal MyPrincipal = @@ -59,7 +59,7 @@ There are two ways to create a ### To create a WindowsPrincipal object for a single validation -1. Initialize a new object by calling the static method, which queries the current Windows account and places information about that account into the newly created identity object. The following code creates a new object and initializes it to the current authenticated user. +1. Initialize a new object by calling the static method, which queries the current Windows account and places information about that account into the newly created identity object. The following code creates a new object and initializes it to the current authenticated user. ```csharp WindowsIdentity MyIdentity = WindowsIdentity.GetCurrent(); diff --git a/docs/standard/security/how-to-store-asymmetric-keys-in-a-key-container.md b/docs/standard/security/how-to-store-asymmetric-keys-in-a-key-container.md index 72f1e9b937693..deac3d79cc5d5 100644 --- a/docs/standard/security/how-to-store-asymmetric-keys-in-a-key-container.md +++ b/docs/standard/security/how-to-store-asymmetric-keys-in-a-key-container.md @@ -33,7 +33,7 @@ Asymmetric private keys should never be stored verbatim or in plain text on the ### To create an asymmetric key and save it in a key container -1. Create a new instance of a class and pass the name that you want to call the key container to the field. +1. Create a new instance of a class and pass the name that you want to call the key container to the field. 2. Create a new instance of a class that derives from the class (usually **RSACryptoServiceProvider** or **DSACryptoServiceProvider**) and pass the previously created **CspParameters** object to its constructor. diff --git a/docs/standard/security/impersonating-and-reverting.md b/docs/standard/security/impersonating-and-reverting.md index 6051f144e2317..c33071bedb466 100644 --- a/docs/standard/security/impersonating-and-reverting.md +++ b/docs/standard/security/impersonating-and-reverting.md @@ -40,7 +40,7 @@ Sometimes you might need to obtain a Windows account token to impersonate a Wind Dim ImpersonatedIdentity As New WindowsIdentity(hToken) ``` -3. Begin impersonation by creating a new instance of the class and initializing it with the method of the initialized class, as shown in the following code. +3. Begin impersonation by creating a new instance of the class and initializing it with the method of the initialized class, as shown in the following code. ```csharp WindowsImpersonationContext MyImpersonation = ImpersonatedIdentity.Impersonate(); @@ -50,7 +50,7 @@ Sometimes you might need to obtain a Windows account token to impersonate a Wind WindowsImpersonationContext MyImpersonation = ImpersonatedIdentity.Impersonate() ``` -4. When you no longer need to impersonate, call the method to revert the impersonation, as shown in the following code. +4. When you no longer need to impersonate, call the method to revert the impersonation, as shown in the following code. ```csharp MyImpersonation.Undo(); diff --git a/docs/standard/security/key-security-concepts.md b/docs/standard/security/key-security-concepts.md index 3f5d792b2e4dc..eeee6b5ea68c3 100644 --- a/docs/standard/security/key-security-concepts.md +++ b/docs/standard/security/key-security-concepts.md @@ -47,7 +47,7 @@ The Microsoft .NET Framework offers role-based security to help address security For more information, see [Principal and Identity Objects](../../../docs/standard/security/principal-and-identity-objects.md). ## Authentication - Authentication is the process of discovering and verifying the identity of a principal by examining the user's credentials and validating those credentials against some authority. The information obtained during authentication is directly usable by your code. You can also use .NET Framework role-based security to authenticate the current user and to determine whether to allow that principal to access your code. See the overloads of the method for examples of how to authenticate the principal for specific roles. For example, you can use the overload to determine if the current user is a member of the Administrators group. + Authentication is the process of discovering and verifying the identity of a principal by examining the user's credentials and validating those credentials against some authority. The information obtained during authentication is directly usable by your code. You can also use .NET Framework role-based security to authenticate the current user and to determine whether to allow that principal to access your code. See the overloads of the method for examples of how to authenticate the principal for specific roles. For example, you can use the overload to determine if the current user is a member of the Administrators group. A variety of authentication mechanisms are used today, many of which can be used with .NET Framework role-based security. Some of the most commonly used mechanisms are basic, digest, Passport, operating system (such as NTLM or Kerberos), or application-defined mechanisms. diff --git a/docs/standard/security/principal-and-identity-objects.md b/docs/standard/security/principal-and-identity-objects.md index ae63702149526..de94393550c63 100644 --- a/docs/standard/security/principal-and-identity-objects.md +++ b/docs/standard/security/principal-and-identity-objects.md @@ -45,7 +45,7 @@ Managed code can discover the identity or the role of a principal through a for controlling domain policy. + Trusted code that creates an application domain can set the application domain policy that controls construction of the default **Principal** and **Identity** objects. This application domain-specific policy applies to all execution threads in that application domain. An unmanaged, trusted host inherently has the ability to set this policy, but managed code that sets this policy must have the for controlling domain policy. When transmitting a **Principal** object across application domains but within the same process (and therefore on the same computer), the remoting infrastructure copies a reference to the **Principal** object associated with the caller's context to the callee's context. diff --git a/docs/standard/security/replacing-a-principal-object.md b/docs/standard/security/replacing-a-principal-object.md index b51ccca33a1b1..3a57e14929ec6 100644 --- a/docs/standard/security/replacing-a-principal-object.md +++ b/docs/standard/security/replacing-a-principal-object.md @@ -24,7 +24,7 @@ ms.author: "mairaw" manager: "wpickett" --- # Replacing a Principal Object -Applications that provide authentication services must be able to replace the **Principal** object () for a given thread. Furthermore, the security system must help protect the ability to replace **Principal** objects because a maliciously attached, incorrect **Principal** compromises the security of your application by claiming an untrue identity or role. Therefore, applications that require the ability to replace **Principal** objects must be granted the object for principal control. (Note that this permission is not required for performing role-based security checks or for creating **Principal** objects.) +Applications that provide authentication services must be able to replace the **Principal** object () for a given thread. Furthermore, the security system must help protect the ability to replace **Principal** objects because a maliciously attached, incorrect **Principal** compromises the security of your application by claiming an untrue identity or role. Therefore, applications that require the ability to replace **Principal** objects must be granted the object for principal control. (Note that this permission is not required for performing role-based security checks or for creating **Principal** objects.) The current **Principal** object can be replaced by performing the following tasks: @@ -39,5 +39,5 @@ Applications that provide authentication services must be able to replace the ** [!code-vb[SetCurrentPrincipal#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/SetCurrentPrincipal/VB/program.vb#1)] ## See Also - + [Principal and Identity Objects](../../../docs/standard/security/principal-and-identity-objects.md) diff --git a/docs/standard/security/role-based-security.md b/docs/standard/security/role-based-security.md index 2e9e67c762651..8e9154e5208fd 100644 --- a/docs/standard/security/role-based-security.md +++ b/docs/standard/security/role-based-security.md @@ -32,7 +32,7 @@ Roles are often used in financial or business applications to enforce policy. Fo .NET Framework role-based security supports authorization by making information about the principal, which is constructed from an associated identity, available to the current thread. The identity (and the principal it helps to define) can be either based on a Windows account or be a custom identity unrelated to a Windows account. .NET Framework applications can make authorization decisions based on the principal's identity or role membership, or both. A role is a named set of principals that have the same privileges with respect to security (such as a teller or a manager). A principal can be a member of one or more roles. Therefore, applications can use role membership to determine whether a principal is authorized to perform a requested action. - To provide ease of use and consistency with code access security, .NET Framework role-based security provides objects that enable the common language runtime to perform authorization in a way that is similar to code access security checks. The class represents the identity or role that the principal must match and is compatible with both declarative and imperative security checks. You can also access a principal's identity information directly and perform role and identity checks in your code when needed. + To provide ease of use and consistency with code access security, .NET Framework role-based security provides objects that enable the common language runtime to perform authorization in a way that is similar to code access security checks. The class represents the identity or role that the principal must match and is compatible with both declarative and imperative security checks. You can also access a principal's identity information directly and perform role and identity checks in your code when needed. The .NET Framework provides role-based security support that is flexible and extensible enough to meet the needs of a wide spectrum of applications. You can choose to interoperate with existing authentication infrastructures, such as COM+ 1.0 Services, or to create a custom authentication system. Role-based security is particularly well-suited for use in ASP.NET Web applications, which are processed primarily on the server. However, .NET Framework role-based security can be used on either the client or the server. @@ -46,4 +46,4 @@ Roles are often used in financial or business applications to enforce policy. Fo |[Key Security Concepts](../../../docs/standard/security/key-security-concepts.md)|Introduces fundamental concepts you must understand before using .NET Framework security.| ## Reference - + diff --git a/docs/standard/serialization/binary-serialization.md b/docs/standard/serialization/binary-serialization.md index 9a306cd07daec..ceab9924b2951 100644 --- a/docs/standard/serialization/binary-serialization.md +++ b/docs/standard/serialization/binary-serialization.md @@ -34,104 +34,104 @@ As the nature of binary serialization allows the modification of private members ### Serializable types -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- (available in .NET Core 2.0.2 and later versions) -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- (not serializable in .NET Framework 4.7 and earlier versions) -- -- -- -- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- (available in .NET Core 2.0.2 and later versions) +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- +- (not serializable in .NET Framework 4.7 and earlier versions) +- +- +- +- ## In this section diff --git a/docs/standard/serialization/steps-in-the-serialization-process.md b/docs/standard/serialization/steps-in-the-serialization-process.md index 79c09090b1555..c83a92a433a0a 100644 --- a/docs/standard/serialization/steps-in-the-serialization-process.md +++ b/docs/standard/serialization/steps-in-the-serialization-process.md @@ -15,7 +15,7 @@ manager: "erikre" # Steps in the serialization process When the method is called on a [formatter](xref:System.Runtime.Serialization.Formatter), object serialization proceeds according to the following sequence of rules: -- A check is made to determine whether the formatter has a surrogate selector. If the formatter does, check whether the surrogate selector handles objects of the given type. If the selector handles the object type, is called on the surrogate selector. +- A check is made to determine whether the formatter has a surrogate selector. If the formatter does, check whether the surrogate selector handles objects of the given type. If the selector handles the object type, is called on the surrogate selector. - If there is no surrogate selector or if it does not handle the object type, a check is made to determine whether the object is marked with the [Serializable](xref:System.SerializableAttribute) attribute. If the object is not, a is thrown. diff --git a/docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md b/docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md index f4936364f07b2..55dd7f7fe31e9 100644 --- a/docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md +++ b/docs/standard/serialization/xml-schema-definition-tool-xsd-exe.md @@ -59,7 +59,7 @@ xsd {file.dll | file.exe} [/outputdir:directory] [/type:typename [...]][/paramet |**/enableDataBinding**|Implements the interface on all generated types to enable data binding. The short form is `/edb`.| |**/enableLinqDataSet**|(Short form: `/eld`.) Specifies that the generated DataSet can be queried against using LINQ to DataSet. This option is used when the /dataset option is also specified. For more information, see [LINQ to DataSet Overview](../../../docs/framework/data/adonet/linq-to-dataset-overview.md) and [Querying Typed DataSets](../../../docs/framework/data/adonet/querying-typed-datasets.md). For general information about using LINQ, see [LINQ (Language-Integrated Query)](http://msdn.microsoft.com/library/a73c4aec-5d15-4e98-b962-1274021ea93d).| |**/f**[**ields**]|Generates fields instead of properties. By default, properties are generated.| -|**/l**[**anguage**]**:***language*|Specifies the programming language to use. Choose from `CS` (C#, which is the default), `VB` (Visual Basic), `JS` (JScript), or `VJS` (Visual J#). You can also specify a fully qualified name for a class implementing | +|**/l**[**anguage**]**:***language*|Specifies the programming language to use. Choose from `CS` (C#, which is the default), `VB` (Visual Basic), `JS` (JScript), or `VJS` (Visual J#). You can also specify a fully qualified name for a class implementing | |**/n**[**amespace**]**:***namespace*|Specifies the runtime namespace for the generated types. The default namespace is `Schemas`.| |**/nologo**|Suppresses the banner.| |**/order**|Generates explicit order identifiers on all particle members.| @@ -85,7 +85,7 @@ xsd {file.dll | file.exe} [/outputdir:directory] [/type:typename [...]][/paramet Generates common language runtime classes from an XSD schema file. The generated classes provide a rich object model for regular XML data. XSD to Classes - Generates runtime classes from an XSD schema file. The generated classes can be used in conjunction with to read and write XML code that follows the schema. + Generates runtime classes from an XSD schema file. The generated classes can be used in conjunction with to read and write XML code that follows the schema. Classes to XSD Generates an XML schema from a type or types in a runtime assembly file. The generated schema defines the XML format used by `System.Xml.Serialization.XmlSerializer`. @@ -227,7 +227,7 @@ xsd myAssembly.dll ## See Also - + [Tools](../../../docs/framework/tools/index.md) [Command Prompts](../../../docs/framework/tools/developer-command-prompt-for-vs.md) [LINQ to DataSet Overview](../../../docs/framework/data/adonet/linq-to-dataset-overview.md) diff --git a/docs/standard/threading/barrier.md b/docs/standard/threading/barrier.md index 6a34667bedfff..fb45907dc83d9 100644 --- a/docs/standard/threading/barrier.md +++ b/docs/standard/threading/barrier.md @@ -36,7 +36,7 @@ A *barrier* is a user-defined synchronization primitive that enables multiple th If the post-phase delegate throws an exception, it is wrapped in a object which is then propagated to all participants. ## Barrier Versus ContinueWhenAll - Barriers are especially useful when the threads are performing multiple phases in loops. If your code requires only one or two phases of work, consider whether to use objects with any kind of implicit join, including: + Barriers are especially useful when the threads are performing multiple phases in loops. If your code requires only one or two phases of work, consider whether to use objects with any kind of implicit join, including: - diff --git a/docs/standard/threading/canceling-threads-cooperatively.md b/docs/standard/threading/canceling-threads-cooperatively.md index 0c3d597e6d4c4..aae8297398a88 100644 --- a/docs/standard/threading/canceling-threads-cooperatively.md +++ b/docs/standard/threading/canceling-threads-cooperatively.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Canceling Threads Cooperatively -Prior to the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], the .NET Framework provided no built-in way to cancel a thread cooperatively after it was started. However, in [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], you can use cancellation tokens to cancel threads, just as you can use them to cancel objects or PLINQ queries. Although the class does not offer built-in support for cancellation tokens, you can pass a token to a thread procedure by using the constructor that takes a delegate. The following example demonstrates how to do this. +Prior to the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], the .NET Framework provided no built-in way to cancel a thread cooperatively after it was started. However, in [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], you can use cancellation tokens to cancel threads, just as you can use them to cancel objects or PLINQ queries. Although the class does not offer built-in support for cancellation tokens, you can pass a token to a thread procedure by using the constructor that takes a delegate. The following example demonstrates how to do this. [!code-csharp[Cancellation#14](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/CooperativeThreads.cs#14)] [!code-vb[Cancellation#14](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/CooperativeThreads.vb#14)] diff --git a/docs/standard/threading/cancellation-in-managed-threads.md b/docs/standard/threading/cancellation-in-managed-threads.md index fd42111d9552f..54087b15fee76 100644 --- a/docs/standard/threading/cancellation-in-managed-threads.md +++ b/docs/standard/threading/cancellation-in-managed-threads.md @@ -23,14 +23,14 @@ Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)] - Instantiate a object, which manages and sends cancellation notification to the individual cancellation tokens. -- Pass the token returned by the property to each task or thread that listens for cancellation. +- Pass the token returned by the property to each task or thread that listens for cancellation. - Provide a mechanism for each task or thread to respond to cancellation. -- Call the method to provide notification of cancellation. +- Call the method to provide notification of cancellation. > [!IMPORTANT] -> The class implements the interface. You should be sure to call the method when you have finished using the cancellation token source to free any unmanaged resources it holds. +> The class implements the interface. You should be sure to call the method when you have finished using the cancellation token source to free any unmanaged resources it holds. The following illustration shows the relationship between a token source and all the copies of its token. @@ -59,13 +59,13 @@ Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)] ||Lightweight value type passed to one or more listeners, typically as a method parameter. Listeners monitor the value of the `IsCancellationRequested` property of the token by polling, callback, or wait handle.| ||Overloads of this exception's constructor accept a as a parameter. Listeners can optionally throw this exception to verify the source of the cancellation and notify others that it has responded to a cancellation request.| - The new cancellation model is integrated into the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] in several types. The most important ones are , , and . We recommend that you use this new cancellation model for all new library and application code. + The new cancellation model is integrated into the [!INCLUDE[dnprdnshort](../../../includes/dnprdnshort-md.md)] in several types. The most important ones are , , and . We recommend that you use this new cancellation model for all new library and application code. ## Code Example In the following example, the requesting object creates a object, and then passes its property to the cancelable operation. The operation that receives the request monitors the value of the property of the token by polling. When the value becomes `true`, the listener can terminate in whatever manner is appropriate. In this example, the method just exits, which is all that is required in many cases. > [!NOTE] -> The example uses the method to demonstrate that the new cancellation framework is compatible with legacy APIs. For an example that uses the new, preferred type, see [How to: Cancel a Task and Its Children](../../../docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md). +> The example uses the method to demonstrate that the new cancellation framework is compatible with legacy APIs. For an example that uses the new, preferred type, see [How to: Cancel a Task and Its Children](../../../docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md). [!code-csharp[Cancellation#1](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex1.cs#1)] [!code-vb[Cancellation#1](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex1.vb#1)] @@ -73,7 +73,7 @@ Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)] ## Operation Cancellation Versus Object Cancellation In the new cancellation framework, cancellation refers to operations, not objects. The cancellation request means that the operation should stop as soon as possible after any required cleanup is performed. One cancellation token should refer to one "cancelable operation," however that operation may be implemented in your program. After the property of the token has been set to `true`, it cannot be reset to `false`. Therefore, cancellation tokens cannot be reused after they have been canceled. - If you require an object cancellation mechanism, you can base it on the operation cancellation mechanism by calling the method, as shown in the following example. + If you require an object cancellation mechanism, you can base it on the operation cancellation mechanism by calling the method, as shown in the following example. [!code-csharp[Cancellation#2](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/objectcancellation1.cs#2)] [!code-vb[Cancellation#2](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/objectcancellation1.vb#2)] @@ -88,7 +88,7 @@ Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)] The class handles in this way. For more information, see [Task Cancellation](../../../docs/standard/parallel-programming/task-cancellation.md). ### Listening by Polling - For long-running computations that loop or recurse, you can listen for a cancellation request by periodically polling the value of the property. If its value is `true`, the method should clean up and terminate as quickly as possible. The optimal frequency of polling depends on the type of application. It is up to the developer to determine the best polling frequency for any given program. Polling itself does not significantly impact performance. The following example shows one possible way to poll. + For long-running computations that loop or recurse, you can listen for a cancellation request by periodically polling the value of the property. If its value is `true`, the method should clean up and terminate as quickly as possible. The optimal frequency of polling depends on the type of application. It is up to the developer to determine the best polling frequency for any given program. Polling itself does not significantly impact performance. The following example shows one possible way to poll. [!code-csharp[Cancellation#3](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex11.cs#3)] [!code-vb[Cancellation#3](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex11.vb#3)] @@ -111,17 +111,17 @@ Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)] - If you call while the callback is running, and you hold a lock that the callback is waiting on, your program can deadlock. After `Dispose` returns, you can free any resources required by the callback. -- Callbacks should not perform any manual thread or usage in a callback. If a callback must run on a particular thread, use the constructor that enables you to specify that the target syncContext is the active . Performing manual threading in a callback can cause deadlock. +- Callbacks should not perform any manual thread or usage in a callback. If a callback must run on a particular thread, use the constructor that enables you to specify that the target syncContext is the active . Performing manual threading in a callback can cause deadlock. For a more complete example, see [How to: Register Callbacks for Cancellation Requests](../../../docs/standard/threading/how-to-register-callbacks-for-cancellation-requests.md). ### Listening by Using a Wait Handle - When a cancelable operation can block while it waits on a synchronization primitive such as a or , you can use the property to enable the operation to wait on both the event and the cancellation request. The wait handle of the cancellation token will become signaled in response to a cancellation request, and the method can use the return value of the method to determine whether it was the cancellation token that signaled. The operation can then just exit, or throw a , as appropriate. + When a cancelable operation can block while it waits on a synchronization primitive such as a or , you can use the property to enable the operation to wait on both the event and the cancellation request. The wait handle of the cancellation token will become signaled in response to a cancellation request, and the method can use the return value of the method to determine whether it was the cancellation token that signaled. The operation can then just exit, or throw a , as appropriate. [!code-csharp[Cancellation#5](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex9.cs#5)] [!code-vb[Cancellation#5](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex9.vb#5)] - In new code that targets the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], and both support the new cancellation framework in their `Wait` methods. You can pass the to the method, and when the cancellation is requested, the event wakes up and throws an . + In new code that targets the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], and both support the new cancellation framework in their `Wait` methods. You can pass the to the method, and when the cancellation is requested, the event wakes up and throws an . [!code-csharp[Cancellation#6](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex10.cs#6)] [!code-vb[Cancellation#6](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex10.vb#6)] @@ -145,7 +145,7 @@ Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)] - User-delegates should attempt to respond to cancellation requests from library code in a timely manner. - and are examples of classes that follows these guidelines. For more information, see [Task Cancellation](../../../docs/standard/parallel-programming/task-cancellation.md)and [How to: Cancel a PLINQ Query](../../../docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md). + and are examples of classes that follows these guidelines. For more information, see [Task Cancellation](../../../docs/standard/parallel-programming/task-cancellation.md)and [How to: Cancel a PLINQ Query](../../../docs/standard/parallel-programming/how-to-cancel-a-plinq-query.md). ## See Also [Managed Threading Basics](../../../docs/standard/threading/managed-threading-basics.md) diff --git a/docs/standard/threading/countdownevent.md b/docs/standard/threading/countdownevent.md index dc518a6a78923..0bc79073e8050 100644 --- a/docs/standard/threading/countdownevent.md +++ b/docs/standard/threading/countdownevent.md @@ -17,10 +17,10 @@ ms.author: "ronpet" manager: "wpickett" --- # CountdownEvent - is a synchronization primitive that unblocks its waiting threads after it has been signaled a certain number of times. is designed for scenarios in which you would otherwise have to use a or and manually decrement a variable before signaling the event. For example, in a fork/join scenario, you can just create a that has a signal count of 5, and then start five work items on the thread pool and have each work item call when it completes. Each call to decrements the signal count by 1. On the main thread, the call to will block until the signal count is zero. + is a synchronization primitive that unblocks its waiting threads after it has been signaled a certain number of times. is designed for scenarios in which you would otherwise have to use a or and manually decrement a variable before signaling the event. For example, in a fork/join scenario, you can just create a that has a signal count of 5, and then start five work items on the thread pool and have each work item call when it completes. Each call to decrements the signal count by 1. On the main thread, the call to will block until the signal count is zero. > [!NOTE] -> For code that does not have to interact with legacy .NET Framework synchronization APIs, consider using objects or the method for an even easier approach to expressing fork-join parallelism. +> For code that does not have to interact with legacy .NET Framework synchronization APIs, consider using objects or the method for an even easier approach to expressing fork-join parallelism. has these additional features: diff --git a/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md b/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md index 57b25a7b318c1..8056c547cb358 100644 --- a/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md +++ b/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md @@ -36,9 +36,9 @@ When an operating-system process is created, the operating system injects a thre [!code-vb[System.Threading.ThreadStart2#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadStart2/VB/source2.vb#2)] ## Passing Data to Threads and Retrieving Data from Threads - In the .NET Framework version 2.0, the delegate provides an easy way to pass an object containing data to a thread when you call the method overload. See for a code example. + In the .NET Framework version 2.0, the delegate provides an easy way to pass an object containing data to a thread when you call the method overload. See for a code example. - Using the delegate is not a type-safe way to pass data, because the method overload accepts any object. An alternative is to encapsulate the thread procedure and the data in a helper class and use the delegate to execute the thread procedure. This technique is shown in the two code examples that follow. + Using the delegate is not a type-safe way to pass data, because the method overload accepts any object. An alternative is to encapsulate the thread procedure and the data in a helper class and use the delegate to execute the thread procedure. This technique is shown in the two code examples that follow. Neither of these delegates has a return value, because there is no place to return the data from an asynchronous call. To retrieve the results of a thread method, you can use a callback method, as demonstrated in the second code example. @@ -57,6 +57,6 @@ When an operating-system process is created, the operating system injects a thre - + [Threading](../../../docs/standard/threading/index.md) [Using Threads and Threading](../../../docs/standard/threading/using-threads-and-threading.md) diff --git a/docs/standard/threading/destroying-threads.md b/docs/standard/threading/destroying-threads.md index b9df14b5f0ee3..17b92348bd8d1 100644 --- a/docs/standard/threading/destroying-threads.md +++ b/docs/standard/threading/destroying-threads.md @@ -18,19 +18,19 @@ ms.author: "ronpet" manager: "wpickett" --- # Destroying Threads -The method is used to stop a managed thread permanently. When you call , the common language runtime throws a in the target thread, which the target thread can catch. For more information, see . +The method is used to stop a managed thread permanently. When you call , the common language runtime throws a in the target thread, which the target thread can catch. For more information, see . > [!NOTE] -> If a thread is executing unmanaged code when its method is called, the runtime marks it . The exception is thrown when the thread returns to managed code. +> If a thread is executing unmanaged code when its method is called, the runtime marks it . The exception is thrown when the thread returns to managed code. Once a thread is aborted, it cannot be restarted. - The method does not cause the thread to abort immediately, because the target thread can catch the and execute arbitrary amounts of code in a `finally` block. You can call if you need to wait until the thread has ended. is a blocking call that does not return until the thread has actually stopped executing or an optional timeout interval has elapsed. The aborted thread could call the method or perform unbounded processing in a `finally` block, so if you do not specify a timeout, the wait is not guaranteed to end. + The method does not cause the thread to abort immediately, because the target thread can catch the and execute arbitrary amounts of code in a `finally` block. You can call if you need to wait until the thread has ended. is a blocking call that does not return until the thread has actually stopped executing or an optional timeout interval has elapsed. The aborted thread could call the method or perform unbounded processing in a `finally` block, so if you do not specify a timeout, the wait is not guaranteed to end. - Threads that are waiting on a call to the method can be interrupted by other threads that call . + Threads that are waiting on a call to the method can be interrupted by other threads that call . ## Handling ThreadAbortException - If you expect your thread to be aborted, either as a result of calling from your own code or as a result of unloading an application domain in which the thread is running ( uses to terminate threads), your thread must handle the and perform any final processing in a `finally` clause, as shown in the following code. + If you expect your thread to be aborted, either as a result of calling from your own code or as a result of unloading an application domain in which the thread is running ( uses to terminate threads), your thread must handle the and perform any final processing in a `finally` clause, as shown in the following code. ```vb Try @@ -63,7 +63,7 @@ catch (ThreadAbortException ex) Your clean-up code must be in the `catch` clause or the `finally` clause, because a is rethrown by the system at the end of the `finally` clause, or at the end of the `catch` clause if there is no `finally` clause. - You can prevent the system from rethrowing the exception by calling the method. However, you should do this only if your own code caused the . + You can prevent the system from rethrowing the exception by calling the method. However, you should do this only if your own code caused the . ## See Also diff --git a/docs/standard/threading/eventwaithandle-autoresetevent-countdownevent-manualresetevent.md b/docs/standard/threading/eventwaithandle-autoresetevent-countdownevent-manualresetevent.md index 4704e6fc305dc..48806111c10f0 100644 --- a/docs/standard/threading/eventwaithandle-autoresetevent-countdownevent-manualresetevent.md +++ b/docs/standard/threading/eventwaithandle-autoresetevent-countdownevent-manualresetevent.md @@ -21,7 +21,7 @@ manager: "wpickett" # EventWaitHandle, AutoResetEvent, CountdownEvent, ManualResetEvent Event wait handles allow threads to synchronize activities by signaling each other and by waiting on each other's signals. These synchronization events are based on Win32 wait handles and can be divided into two types: those that reset automatically when signaled and those that are reset manually. - Event wait handles are useful in many of the same synchronization scenarios as the class. Event wait handles are often easier to use than the and methods, and they offer more control over signaling. Named event wait handles can also be used to synchronize activities across application domains and processes, whereas monitors are local to an application domain. + Event wait handles are useful in many of the same synchronization scenarios as the class. Event wait handles are often easier to use than the and methods, and they offer more control over signaling. Named event wait handles can also be used to synchronize activities across application domains and processes, whereas monitors are local to an application domain. ## In This Section [EventWaitHandle](../../../docs/standard/threading/eventwaithandle.md) diff --git a/docs/standard/threading/eventwaithandle.md b/docs/standard/threading/eventwaithandle.md index af266db3dce6e..3fb4187599a87 100644 --- a/docs/standard/threading/eventwaithandle.md +++ b/docs/standard/threading/eventwaithandle.md @@ -28,7 +28,7 @@ The class allows threads to communicate Both local and named event wait handles use system synchronization objects, which are protected by wrappers to ensure that the resources are released. You can use the method to free the resources immediately when you have finished using the object. ## Event Wait Handles That Reset Automatically - You create an automatic reset event by specifying when you create the object. As its name implies, this synchronization event resets automatically when signaled, after releasing a single waiting thread. Signal the event by calling its method. + You create an automatic reset event by specifying when you create the object. As its name implies, this synchronization event resets automatically when signaled, after releasing a single waiting thread. Signal the event by calling its method. Automatic reset events are usually used to provide exclusive access to a resource for a single thread at a time. A thread requests the resource by calling the method. If no other thread is holding the wait handle, the method returns `true` and the calling thread has control of the resource. @@ -38,16 +38,16 @@ The class allows threads to communicate If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread attempts to wait on it. The event releases the thread and immediately resets, blocking subsequent threads. ## Event Wait Handles That Reset Manually - You create a manual reset event by specifying when you create the object. As its name implies, this synchronization event must be reset manually after it has been signaled. Until it is reset, by calling its method, threads that wait on the event handle proceed immediately without blocking. + You create a manual reset event by specifying when you create the object. As its name implies, this synchronization event must be reset manually after it has been signaled. Until it is reset, by calling its method, threads that wait on the event handle proceed immediately without blocking. A manual reset event acts like the gate of a corral. When the event is not signaled, threads that wait on it block, like horses in a corral. When the event is signaled, by calling its method, all waiting threads are free to proceed. The event remains signaled until its method is called. This makes the manual reset event an ideal way to hold up threads that need to wait until one thread finishes a task. Like horses leaving a corral, it takes time for the released threads to be scheduled by the operating system and to resume execution. If the method is called before all the threads have resumed execution, the remaining threads once again block. Which threads resume and which threads block depends on random factors like the load on the system, the number of threads waiting for the scheduler, and so on. This is not a problem if the thread that signals the event ends after signaling, which is the most common usage pattern. If you want the thread that signaled the event to begin a new task after all the waiting threads have resumed, you must block it until all the waiting threads have resumed. Otherwise, you have a race condition, and the behavior of your code is unpredictable. ## Features Common to Automatic and Manual Events - Typically, one or more threads block on an until an unblocked thread calls the method, which releases one of the waiting threads (in the case of automatic reset events) or all of them (in the case of manual reset events). A thread can signal an and then block on it, as an atomic operation, by calling the static method. + Typically, one or more threads block on an until an unblocked thread calls the method, which releases one of the waiting threads (in the case of automatic reset events) or all of them (in the case of manual reset events). A thread can signal an and then block on it, as an atomic operation, by calling the static method. - objects can be used with the static and methods. Because the and classes both derive from , you can use both classes with these methods. + objects can be used with the static and methods. Because the and classes both derive from , you can use both classes with these methods. ### Named Events The Windows operating system allows event wait handles to have names. A named event is system wide. That is, once the named event is created, it is visible to all threads in all processes. Thus, named events can be used to synchronize the activities of processes as well as threads. diff --git a/docs/standard/threading/exceptions-in-managed-threads.md b/docs/standard/threading/exceptions-in-managed-threads.md index 7c7059422a9c5..6760fcc5fd420 100644 --- a/docs/standard/threading/exceptions-in-managed-threads.md +++ b/docs/standard/threading/exceptions-in-managed-threads.md @@ -64,7 +64,7 @@ Starting with the .NET Framework version 2.0, the common language runtime allows - Restructure the code so the thread exits gracefully when a signal is received. -- Use the method to abort the thread. +- Use the method to abort the thread. - 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. diff --git a/docs/standard/threading/foreground-and-background-threads.md b/docs/standard/threading/foreground-and-background-threads.md index 897a5861156e7..35e5b918d9ad2 100644 --- a/docs/standard/threading/foreground-and-background-threads.md +++ b/docs/standard/threading/foreground-and-background-threads.md @@ -23,9 +23,9 @@ manager: "wpickett" A managed thread is either a background thread or a foreground thread. Background threads are identical to foreground threads with one exception: a background thread does not keep the managed execution environment running. Once all foreground threads have been stopped in a managed process (where the .exe file is a managed assembly), the system stops all background threads and shuts down. > [!NOTE] -> When the runtime stops a background thread because the process is shutting down, no exception is thrown in the thread. However, when threads are stopped because the method unloads the application domain, a is thrown in both foreground and background threads. +> When the runtime stops a background thread because the process is shutting down, no exception is thrown in the thread. However, when threads are stopped because the method unloads the application domain, a is thrown in both foreground and background threads. - Use the property to determine whether a thread is a background or a foreground thread, or to change its status. A thread can be changed to a background thread at any time by setting its property to `true`. + Use the property to determine whether a thread is a background or a foreground thread, or to change its status. A thread can be changed to a background thread at any time by setting its property to `true`. > [!IMPORTANT] > The foreground or background status of a thread does not affect the outcome of an unhandled exception in the thread. In the .NET Framework version 2.0, an unhandled exception in either foreground or background threads results in termination of the application. See [Exceptions in Managed Threads](../../../docs/standard/threading/exceptions-in-managed-threads.md). @@ -35,6 +35,6 @@ A managed thread is either a background thread or a foreground thread. Backgroun If you use a thread to monitor an activity, such as a socket connection, set its property to `true` so that the thread does not prevent your process from terminating. ## See Also - + diff --git a/docs/standard/threading/how-to-enable-thread-tracking-mode-in-spinlock.md b/docs/standard/threading/how-to-enable-thread-tracking-mode-in-spinlock.md index 083f7a7d789ae..5a714b5eb453c 100644 --- a/docs/standard/threading/how-to-enable-thread-tracking-mode-in-spinlock.md +++ b/docs/standard/threading/how-to-enable-thread-tracking-mode-in-spinlock.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Enable Thread-Tracking Mode in SpinLock - is a low-level mutual exclusion lock that you can use for scenarios that have very short wait times. is not re-entrant. After a thread enters the lock, it must exit the lock correctly before it can enter again. Typically, any attempt to re-enter the lock would cause deadlock, and deadlocks can be very difficult to debug. As an aid to development, supports a thread-tracking mode that causes an exception to be thrown when a thread attempts to re-enter a lock that it already holds. This lets you more easily locate the point at which the lock was not exited correctly. You can turn on thread-tracking mode by using the constructor that takes a Boolean input parameter, and passing in an argument of `true`. After you complete the development and testing phases, turn off thread-tracking mode for better performance. + is a low-level mutual exclusion lock that you can use for scenarios that have very short wait times. is not re-entrant. After a thread enters the lock, it must exit the lock correctly before it can enter again. Typically, any attempt to re-enter the lock would cause deadlock, and deadlocks can be very difficult to debug. As an aid to development, supports a thread-tracking mode that causes an exception to be thrown when a thread attempts to re-enter a lock that it already holds. This lets you more easily locate the point at which the lock was not exited correctly. You can turn on thread-tracking mode by using the constructor that takes a Boolean input parameter, and passing in an argument of `true`. After you complete the development and testing phases, turn off thread-tracking mode for better performance. ## Example The following example demonstrates thread-tracking mode. The lines that correctly exit the lock are commented out to simulate a coding error that causes one of the following results: diff --git a/docs/standard/threading/how-to-listen-for-cancellation-requests-by-polling.md b/docs/standard/threading/how-to-listen-for-cancellation-requests-by-polling.md index cb69b8403fb9c..9b8d3a342c559 100644 --- a/docs/standard/threading/how-to-listen-for-cancellation-requests-by-polling.md +++ b/docs/standard/threading/how-to-listen-for-cancellation-requests-by-polling.md @@ -17,10 +17,10 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Listen for Cancellation Requests by Polling -The following example shows one way that user code can poll a cancellation token at regular intervals to see whether cancellation has been requested from the calling thread. This example uses the type, but the same pattern applies to asynchronous operations created directly by the type or the type. +The following example shows one way that user code can poll a cancellation token at regular intervals to see whether cancellation has been requested from the calling thread. This example uses the type, but the same pattern applies to asynchronous operations created directly by the type or the type. ## Example - Polling requires some kind of loop or recursive code that can periodically read the value of the Boolean property. If you are using the type and you are waiting for the task to complete on the calling thread, you can use the method to check the property and throw the exception. By using this method, you ensure that the correct exception is thrown in response to a request. If you are using a , then calling this method is better than manually throwing an . If you do not have to throw the exception, then you can just check the property and return from the method if the property is `true`. + Polling requires some kind of loop or recursive code that can periodically read the value of the Boolean property. If you are using the type and you are waiting for the task to complete on the calling thread, you can use the method to check the property and throw the exception. By using this method, you ensure that the correct exception is thrown in response to a request. If you are using a , then calling this method is better than manually throwing an . If you do not have to throw the exception, then you can just check the property and return from the method if the property is `true`. [!code-csharp[Cancellation#11](../../../samples/snippets/csharp/VS_Snippets_Misc/cancellation/cs/cancellationex11.cs#11)] [!code-vb[Cancellation#11](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cancellation/vb/cancellationex11.vb#11)] diff --git a/docs/standard/threading/how-to-listen-for-cancellation-requests-that-have-wait-handles.md b/docs/standard/threading/how-to-listen-for-cancellation-requests-that-have-wait-handles.md index b6fa896a6906c..ee8f062f081be 100644 --- a/docs/standard/threading/how-to-listen-for-cancellation-requests-that-have-wait-handles.md +++ b/docs/standard/threading/how-to-listen-for-cancellation-requests-that-have-wait-handles.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Listen for Cancellation Requests That Have Wait Handles -If a method is blocked while it is waiting for an event to be signaled, it cannot check the value of the cancellation token and respond in a timely manner. The first example shows how to solve this problem when you are working with events such as that do not natively support the unified cancellation framework. The second example shows a more streamlined approach that uses , which does support unified cancellation. +If a method is blocked while it is waiting for an event to be signaled, it cannot check the value of the cancellation token and respond in a timely manner. The first example shows how to solve this problem when you are working with events such as that do not natively support the unified cancellation framework. The second example shows a more streamlined approach that uses , which does support unified cancellation. > [!NOTE] > When "Just My Code" is enabled, Visual Studio in some cases will break on the line that throws the exception and display an error message that says "exception not handled by user code." This error is benign. You can press F5 to continue from it, and see the exception-handling behavior that is demonstrated in the examples below. To prevent Visual Studio from breaking on the first error, just uncheck the "Just My Code" checkbox under **Tools, Options, Debugging, General**. diff --git a/docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md b/docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md index 0a512545ae4d4..95271a5f80d5a 100644 --- a/docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md +++ b/docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md @@ -27,7 +27,7 @@ The following example demonstrates how to use a might be useful when a lock on a shared resource is not going to be held for very long. In such cases, on multi-core computers it can be efficient for the blocked thread to spin for a few cycles until the lock is released. By spinning, the thread does not become blocked, which is a CPU-intensive process. will stop spinning under certain conditions to prevent starvation of logical processors or priority inversion on systems with Hyper-Threading. - This example uses the class, which requires user synchronization for multi-threaded access. In applications that target the .NET Framework version 4, another option is to use the , which does not require any user locks. + This example uses the class, which requires user synchronization for multi-threaded access. In applications that target the .NET Framework version 4, another option is to use the , which does not require any user locks. Note the use of `false` (`False` in Visual Basic) in the call to . This provides the best performance. Specify `true` (`True`)on IA64 architectures to use the memory fence, which flushes the write buffers to ensure that the lock is now available for other threads to exit. diff --git a/docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md b/docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md index c886fe8438391..48563b34c3fe7 100644 --- a/docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md +++ b/docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md @@ -17,10 +17,10 @@ ms.author: "ronpet" manager: "wpickett" --- # How to: Use SpinWait to Implement a Two-Phase Wait Operation -The following example shows how to use a object to implement a two-phase wait operation. In the first phase, the synchronization object, a `Latch`, spins for a few cycles while it checks whether the lock has become available. In the second phase, if the lock becomes available, then the `Wait` method returns without using the to perform its wait; otherwise, `Wait` performs the wait. +The following example shows how to use a object to implement a two-phase wait operation. In the first phase, the synchronization object, a `Latch`, spins for a few cycles while it checks whether the lock has become available. In the second phase, if the lock becomes available, then the `Wait` method returns without using the to perform its wait; otherwise, `Wait` performs the wait. ## Example - This example shows a very basic implementation of a Latch synchronization primitive. You can use this data structure when wait times are expected to be very short. This example is for demonstration purposes only. If you require latch-type functionality in your program, consider using . + This example shows a very basic implementation of a Latch synchronization primitive. You can use this data structure when wait times are expected to be very short. This example is for demonstration purposes only. If you require latch-type functionality in your program, consider using . [!code-csharp[CDS_SpinWait#03](../../../samples/snippets/csharp/VS_Snippets_Misc/cds_spinwait/cs/spinwait03.cs#03)] [!code-vb[CDS_SpinWait#03](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_spinwait/vb/spinwait2.vb#03)] diff --git a/docs/standard/threading/index.md b/docs/standard/threading/index.md index 3798d82c7b3f0..61ea5825da4ce 100644 --- a/docs/standard/threading/index.md +++ b/docs/standard/threading/index.md @@ -21,7 +21,7 @@ manager: "wpickett" Whether you are developing for computers with one processor or several, you want your application to provide the most responsive interaction with the user, even if the application is currently doing other work. Using multiple threads of execution is one of the most powerful ways to keep your application responsive to the user and at the same time make use of the processor in between or even during user events. While this section introduces the basic concepts of threading, it focuses on managed threading concepts and using managed threading. > [!NOTE] -> Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], multithreaded programming is greatly simplified with the and classes, [Parallel LINQ (PLINQ)](../../../docs/standard/parallel-programming/parallel-linq-plinq.md), new concurrent collection classes in the namespace, and a new programming model that is based on the concept of tasks rather than threads. For more information, see [Parallel Programming](../../../docs/standard/parallel-programming/index.md). +> Starting with the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], multithreaded programming is greatly simplified with the and classes, [Parallel LINQ (PLINQ)](../../../docs/standard/parallel-programming/parallel-linq-plinq.md), new concurrent collection classes in the namespace, and a new programming model that is based on the concept of tasks rather than threads. For more information, see [Parallel Programming](../../../docs/standard/parallel-programming/index.md). ## In This Section [Managed Threading Basics](../../../docs/standard/threading/managed-threading-basics.md) diff --git a/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md b/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md index 5963178346129..64de088b1b9ea 100644 --- a/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md +++ b/docs/standard/threading/managed-and-unmanaged-threading-in-windows.md @@ -23,33 +23,33 @@ Management of all threads is done through the cla When an unmanaged thread enters the runtime through, for example, a COM callable wrapper, the system checks the thread-local store of that thread to look for an internal managed object. If one is found, the runtime is already aware of this thread. If it cannot find one, however, the runtime builds a new object and installs it in the thread-local store of that thread. - In managed threading, is the stable managed thread identification. For the lifetime of your thread, it will not collide with the value from any other thread, regardless of the application domain from which you obtain this value. + In managed threading, is the stable managed thread identification. For the lifetime of your thread, it will not collide with the value from any other thread, regardless of the application domain from which you obtain this value. > [!NOTE] > An operating-system **ThreadId** has no fixed relationship to a managed thread, because an unmanaged host can control the relationship between managed and unmanaged threads. Specifically, a sophisticated host can use the Fiber API to schedule many managed threads against the same operating system thread, or to move a managed thread among different operating system threads. ## Mapping from Win32 Threading to Managed Threading - The following table maps Win32 threading elements to their approximate runtime equivalent. Note that this mapping does not represent identical functionality. For example, **TerminateThread** does not execute **finally** clauses or free up resources, and cannot be prevented. However, executes all your rollback code, reclaims all the resources, and can be denied using . Be sure to read the documentation closely before making assumptions about functionality. + The following table maps Win32 threading elements to their approximate runtime equivalent. Note that this mapping does not represent identical functionality. For example, **TerminateThread** does not execute **finally** clauses or free up resources, and cannot be prevented. However, executes all your rollback code, reclaims all the resources, and can be denied using . Be sure to read the documentation closely before making assumptions about functionality. |In Win32|In the common language runtime| |--------------|------------------------------------| |**CreateThread**|Combination of **Thread** and | -|**TerminateThread**|| -|**SuspendThread**|| -|**ResumeThread**|| -|**Sleep**|| -|**WaitForSingleObject** on the thread handle|| +|**TerminateThread**|| +|**SuspendThread**|| +|**ResumeThread**|| +|**Sleep**|| +|**WaitForSingleObject** on the thread handle|| |**ExitThread**|No equivalent| -|**GetCurrentThread**|| -|**SetThreadPriority**|| -|No equivalent|| -|No equivalent|| -|Close to **CoInitializeEx** (OLE32.DLL)|| +|**GetCurrentThread**|| +|**SetThreadPriority**|| +|No equivalent|| +|No equivalent|| +|Close to **CoInitializeEx** (OLE32.DLL)|| ## Managed Threads and COM Apartments - A managed thread can be marked to indicate that it will host a [single-threaded](http://msdn.microsoft.com/library/windows/desktop/ms680112.aspx) or [multithreaded](http://msdn.microsoft.com/library/windows/desktop/ms693421.aspx) apartment. (For more information on the COM threading architecture, see [Processes, threads, and Apartments](http://msdn.microsoft.com/library/windows/desktop/ms693344.aspx).) The , , and methods of the class return and assign the apartment state of a thread. If the state has not been set, returns . + A managed thread can be marked to indicate that it will host a [single-threaded](http://msdn.microsoft.com/library/windows/desktop/ms680112.aspx) or [multithreaded](http://msdn.microsoft.com/library/windows/desktop/ms693421.aspx) apartment. (For more information on the COM threading architecture, see [Processes, threads, and Apartments](http://msdn.microsoft.com/library/windows/desktop/ms693344.aspx).) The , , and methods of the class return and assign the apartment state of a thread. If the state has not been set, returns . - The property can be set only when the thread is in the state; it can be set only once for a thread. + The property can be set only when the thread is in the state; it can be set only once for a thread. If the apartment state is not set before the thread is started, the thread is initialized as a multithreaded apartment (MTA). The finalizer thread and all threads controlled by are MTA. @@ -63,10 +63,10 @@ Management of all threads is done through the cla When managed code calls out to COM objects, it always follows COM rules. In other words, it calls through COM apartment proxies and COM+ 1.0 context wrappers as dictated by OLE32. ## Blocking Issues - If a thread makes an unmanaged call into the operating system that has blocked the thread in unmanaged code, the runtime will not take control of it for or . In the case of , the runtime marks the thread for **Abort** and takes control of it when it re-enters managed code. It is preferable for you to use managed blocking rather than unmanaged blocking. ,, , , , , , and so on are all responsive to and to . Also, if your thread is in a single-threaded apartment, all these managed blocking operations will correctly pump messages in your apartment while your thread is blocked. + If a thread makes an unmanaged call into the operating system that has blocked the thread in unmanaged code, the runtime will not take control of it for or . In the case of , the runtime marks the thread for **Abort** and takes control of it when it re-enters managed code. It is preferable for you to use managed blocking rather than unmanaged blocking. ,, , , , , , and so on are all responsive to and to . Also, if your thread is in a single-threaded apartment, all these managed blocking operations will correctly pump messages in your apartment while your thread is blocked. ## See Also - + diff --git a/docs/standard/threading/managed-thread-states.md b/docs/standard/threading/managed-thread-states.md index deb2396a30023..83811629223f0 100644 --- a/docs/standard/threading/managed-thread-states.md +++ b/docs/standard/threading/managed-thread-states.md @@ -17,7 +17,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Managed Thread States -The property provides a bit mask that indicates the thread's current state. A thread is always in at least one of the possible states in the enumeration, and can be in multiple states at the same time. +The property provides a bit mask that indicates the thread's current state. A thread is always in at least one of the possible states in the enumeration, and can be in multiple states at the same time. > [!IMPORTANT] > Thread state is only of interest in a few debugging scenarios. Your code should never use thread state to synchronize the activities of threads. @@ -29,16 +29,16 @@ The property class is called.|| -|Another thread calls .|| -|The thread responds to and starts running.|| -|The thread calls .|| -|The thread calls on another object.|| -|The thread calls on another thread.|| -|Another thread calls .|| -|The thread responds to a request.|| -|Another thread calls .|| -|Another thread calls .|| -|The thread responds to an .|, then | +|Another thread calls .|| +|The thread responds to and starts running.|| +|The thread calls .|| +|The thread calls on another object.|| +|The thread calls on another thread.|| +|Another thread calls .|| +|The thread responds to a request.|| +|Another thread calls .|| +|Another thread calls .|| +|The thread responds to an .|, then | Because the state has a value of 0, it is not possible to perform a bit test to discover this state. Instead, the following test (in pseudo-code) can be used: @@ -46,7 +46,7 @@ The property call and another thread calls on that same thread, the thread will be in both the and the states at the same time. In that case, as soon as the thread returns from the call to or is interrupted, it will receive the . + Threads are often in more than one state at any given time. For example, if a thread is blocked on a call and another thread calls on that same thread, the thread will be in both the and the states at the same time. In that case, as soon as the thread returns from the call to or is interrupted, it will receive the . Once a thread leaves the state as the result of a call to , it can never return to the state. A thread can never leave the state. diff --git a/docs/standard/threading/managed-threading-best-practices.md b/docs/standard/threading/managed-threading-best-practices.md index 29eab0edbb797..4566a18d57a98 100644 --- a/docs/standard/threading/managed-threading-best-practices.md +++ b/docs/standard/threading/managed-threading-best-practices.md @@ -30,7 +30,7 @@ Multithreading requires careful programming. For most tasks, you can reduce comp ### Deadlocks A deadlock occurs when each of two threads tries to lock a resource the other has already locked. Neither thread can make any further progress. - Many methods of the managed threading classes provide time-outs to help you detect deadlocks. For example, the following code attempts to acquire a lock on the current instance. If the lock is not obtained in 300 milliseconds, returns **false**. + Many methods of the managed threading classes provide time-outs to help you detect deadlocks. For example, the following code attempts to acquire a lock on the current instance. If the lock is not obtained in 300 milliseconds, returns **false**. ```vb If Monitor.TryEnter(lockObject, 300) Then @@ -65,7 +65,7 @@ else { In a multithreaded application, a thread that has loaded and incremented the value might be preempted by another thread which performs all three steps; when the first thread resumes execution and stores its value, it overwrites `objCt` without taking into account the fact that the value has changed in the interim. - This particular race condition is easily avoided by using methods of the class, such as . To read about other techniques for synchronizing data among multiple threads, see [Synchronizing Data for Multithreading](../../../docs/standard/threading/synchronizing-data-for-multithreading.md). + This particular race condition is easily avoided by using methods of the class, such as . To read about other techniques for synchronizing data among multiple threads, see [Synchronizing Data for Multithreading](../../../docs/standard/threading/synchronizing-data-for-multithreading.md). Race conditions can also occur when you synchronize the activities of multiple threads. Whenever you write a line of code, you must consider what might happen if a thread were preempted before executing the line (or before any of the individual machine instructions that make up the line), and another thread overtook it. @@ -79,7 +79,7 @@ else { - A background thread executes only when the number of foreground threads executing is smaller than the number of processors. -- When you call the method on a thread, that thread might or might not start executing immediately, depending on the number of processors and the number of threads currently waiting to execute. +- When you call the method on a thread, that thread might or might not start executing immediately, depending on the number of processors and the number of threads currently waiting to execute. - Race conditions can occur not only because threads are preempted unexpectedly, but because two threads executing on different processors might be racing to reach the same code block. @@ -90,7 +90,7 @@ else { - A background thread executes only when the main user thread is idle. A foreground thread that executes constantly starves background threads of processor time. -- When you call the method on a thread, that thread does not start executing until the current thread yields or is preempted by the operating system. +- When you call the method on a thread, that thread does not start executing until the current thread yields or is preempted by the operating system. - Race conditions typically occur because the programmer did not anticipate the fact that a thread can be preempted at an awkward moment, sometimes allowing another thread to reach a code block first. @@ -104,17 +104,17 @@ else { ## General Recommendations Consider the following guidelines when using multiple threads: -- Don't use to terminate other threads. Calling **Abort** on another thread is akin to throwing an exception on that thread, without knowing what point that thread has reached in its processing. +- Don't use to terminate other threads. Calling **Abort** on another thread is akin to throwing an exception on that thread, without knowing what point that thread has reached in its processing. -- Don't use and to synchronize the activities of multiple threads. Do use , , , and . +- Don't use and to synchronize the activities of multiple threads. Do use , , , and . -- Don't control the execution of worker threads from your main program (using events, for example). Instead, design your program so that worker threads are responsible for waiting until work is available, executing it, and notifying other parts of your program when finished. If your worker threads do not block, consider using thread pool threads. is useful in situations where worker threads block. +- Don't control the execution of worker threads from your main program (using events, for example). Instead, design your program so that worker threads are responsible for waiting until work is available, executing it, and notifying other parts of your program when finished. If your worker threads do not block, consider using thread pool threads. is useful in situations where worker threads block. -- Don't use types as lock objects. That is, avoid code such as `lock(typeof(X))` in C# or `SyncLock(GetType(X))` in Visual Basic, or the use of with objects. For a given type, there is only one instance of per application domain. If the type you take a lock on is public, code other than your own can take locks on it, leading to deadlocks. For additional issues, see [Reliability Best Practices](../../../docs/framework/performance/reliability-best-practices.md). +- Don't use types as lock objects. That is, avoid code such as `lock(typeof(X))` in C# or `SyncLock(GetType(X))` in Visual Basic, or the use of with objects. For a given type, there is only one instance of per application domain. If the type you take a lock on is public, code other than your own can take locks on it, leading to deadlocks. For additional issues, see [Reliability Best Practices](../../../docs/framework/performance/reliability-best-practices.md). - Use caution when locking on instances, for example `lock(this)` in C# or `SyncLock(Me)` in Visual Basic. If other code in your application, external to the type, takes a lock on the object, deadlocks could occur. -- Do ensure that a thread that has entered a monitor always leaves that monitor, even if an exception occurs while the thread is in the monitor. The C# [lock](~/docs/csharp/language-reference/keywords/lock-statement.md) statement and the Visual Basic [SyncLock](~/docs/visual-basic/language-reference/statements/synclock-statement.md) statement provide this behavior automatically, employing a **finally** block to ensure that is called. If you cannot ensure that **Exit** will be called, consider changing your design to use **Mutex**. A mutex is automatically released when the thread that currently owns it terminates. +- Do ensure that a thread that has entered a monitor always leaves that monitor, even if an exception occurs while the thread is in the monitor. The C# [lock](~/docs/csharp/language-reference/keywords/lock-statement.md) statement and the Visual Basic [SyncLock](~/docs/visual-basic/language-reference/statements/synclock-statement.md) statement provide this behavior automatically, employing a **finally** block to ensure that is called. If you cannot ensure that **Exit** will be called, consider changing your design to use **Mutex**. A mutex is automatically released when the thread that currently owns it terminates. - Do use multiple threads for tasks that require different resources, and avoid assigning multiple threads to a single resource. For example, any task involving I/O benefits from having its own thread, because that thread will block during I/O operations and thus allow other threads to execute. User input is another resource that benefits from a dedicated thread. On a single-processor computer, a task that involves intensive computation coexists with user input and with tasks that involve I/O, but multiple computation-intensive tasks contend with each other. diff --git a/docs/standard/threading/manualresetevent-and-manualreseteventslim.md b/docs/standard/threading/manualresetevent-and-manualreseteventslim.md index 28db884d71e77..c11d6acc577a9 100644 --- a/docs/standard/threading/manualresetevent-and-manualreseteventslim.md +++ b/docs/standard/threading/manualresetevent-and-manualreseteventslim.md @@ -18,11 +18,11 @@ ms.author: "ronpet" manager: "wpickett" --- # ManualResetEvent and ManualResetEventSlim -The class represents a local wait handle event that must be reset manually after it is signaled. This class represents a special case of its base class, . See the [EventWaitHandle](../../../docs/standard/threading/eventwaithandle.md) conceptual documentation for the use and features of manual reset events. +The class represents a local wait handle event that must be reset manually after it is signaled. This class represents a special case of its base class, . See the [EventWaitHandle](../../../docs/standard/threading/eventwaithandle.md) conceptual documentation for the use and features of manual reset events. - A object remains signaled until its method is called. Any number of waiting threads, or threads that wait on the event after it has been signaled, can be released while the object's state is signaled. corresponds to a Win32 `CreateEvent` call, specifying `true` for the `bManualReset` argument. + A object remains signaled until its method is called. Any number of waiting threads, or threads that wait on the event after it has been signaled, can be released while the object's state is signaled. corresponds to a Win32 `CreateEvent` call, specifying `true` for the `bManualReset` argument. - In the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], you can use the class for better performance when wait times are expected to be very short, and when the event does not cross a process boundary. uses busy spinning for a short time while it waits for the event to become signaled. When wait times are short, spinning can be much less expensive than waiting by using wait handles. However, if the event does not become signaled within a certain period of time, resorts to a regular event handle wait. + In the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], you can use the class for better performance when wait times are expected to be very short, and when the event does not cross a process boundary. uses busy spinning for a short time while it waits for the event to become signaled. When wait times are short, spinning can be much less expensive than waiting by using wait handles. However, if the event does not become signaled within a certain period of time, resorts to a regular event handle wait. ## See Also [Threading](../../../docs/standard/threading/index.md) diff --git a/docs/standard/threading/overview-of-synchronization-primitives.md b/docs/standard/threading/overview-of-synchronization-primitives.md index 80be08921ad20..60179ef7fc738 100644 --- a/docs/standard/threading/overview-of-synchronization-primitives.md +++ b/docs/standard/threading/overview-of-synchronization-primitives.md @@ -42,7 +42,7 @@ manager: "wpickett" Locks give control of a resource to one thread at a time, or to a specified number of threads. A thread that requests an exclusive lock when the lock is in use blocks until the lock becomes available. ### Exclusive Locks - The simplest form of locking is the `lock` statement in C# and the `SyncLock` statement in Visual Basic, which controls access to a block of code. Such a block is frequently referred to as a critical section. The `lock` statement is implemented by using the and methods, and it uses `try…catch…finally` block to ensure that the lock is released. + The simplest form of locking is the `lock` statement in C# and the `SyncLock` statement in Visual Basic, which controls access to a block of code. Such a block is frequently referred to as a critical section. The `lock` statement is implemented by using the and methods, and it uses `try…catch…finally` block to ensure that the lock is released. In general, using the `lock` or `SyncLock` statement to protect small blocks of code, never spanning more than a single method, is the best way to use the class. Although powerful, the class is prone to orphan locks and deadlocks. @@ -96,7 +96,7 @@ manager: "wpickett" For a conceptual overview, see [Semaphore and SemaphoreSlim](../../../docs/standard/threading/semaphore-and-semaphoreslim.md). - is a lightweight semaphore for synchronization within a single process boundary. + is a lightweight semaphore for synchronization within a single process boundary. [Back to top](#top) @@ -116,7 +116,7 @@ manager: "wpickett" #### Event Wait Handles Event wait handles include the class and its derived classes, and . Threads are released from an event wait handle when the event wait handle is signaled by calling its method or by using the method. - Event wait handles either reset themselves automatically, like a turnstile that allows only one thread through each time it is signaled, or must be reset manually, like a gate that is closed until signaled and then open until someone closes it. As their names imply, and represent the former and latter, respectively. is a lightweight event for synchronization within a single process boundary. + Event wait handles either reset themselves automatically, like a turnstile that allows only one thread through each time it is signaled, or must be reset manually, like a gate that is closed until signaled and then open until someone closes it. As their names imply, and represent the former and latter, respectively. is a lightweight event for synchronization within a single process boundary. An can represent either type of event, and can be either local or global. The derived classes and are always local. @@ -138,19 +138,19 @@ manager: "wpickett" ## Lightweight Synchronization Types Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], you can use synchronization primitives that provide fast performance by avoiding expensive reliance on Win32 kernel objects such as wait handles whenever possible. In general, you should use these types when wait times are short and only when the original synchronization types have been tried and found to be unsatisfactory. The lightweight types cannot be used in scenarios that require cross-process communication. -- is a lightweight version of . +- is a lightweight version of . -- is a lightweight version of . +- is a lightweight version of . -- represents an event that becomes signaled when its count is zero. +- represents an event that becomes signaled when its count is zero. -- enables multiple threads to synchronize with one another without requiring control by a master thread. A barrier prevents each thread from continuing until all threads have reached a specified point. +- enables multiple threads to synchronize with one another without requiring control by a master thread. A barrier prevents each thread from continuing until all threads have reached a specified point. [Back to top](#top) ## SpinWait - Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], you can use the structure when a thread has to wait for an event to be signaled or a condition to be met, but when the actual wait time is expected to be less than the waiting time required by using a wait handle or by otherwise blocking the current thread. By using , you can specify a short period of time to spin while waiting, and then yield (for example, by waiting or sleeping) only if the condition was not met in the specified time. + Starting with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], you can use the structure when a thread has to wait for an event to be signaled or a condition to be met, but when the actual wait time is expected to be less than the waiting time required by using a wait handle or by otherwise blocking the current thread. By using , you can specify a short period of time to spin while waiting, and then yield (for example, by waiting or sleeping) only if the condition was not met in the specified time. [Back to top](#top) diff --git a/docs/standard/threading/pausing-and-resuming-threads.md b/docs/standard/threading/pausing-and-resuming-threads.md index 7ba98418a4b13..16f25a4e97b7b 100644 --- a/docs/standard/threading/pausing-and-resuming-threads.md +++ b/docs/standard/threading/pausing-and-resuming-threads.md @@ -24,26 +24,26 @@ The most common ways to synchronize the activities of threads are to block and r You can also have threads put themselves to sleep. When threads are blocked or sleeping, you can use a to break them out of their wait states. ## The Thread.Sleep Method - Calling the method causes the current thread to immediately block for the number of milliseconds or the time interval you pass to the method, and yields the remainder of its time slice to another thread. Once that interval elapses, the sleeping thread resumes execution. + Calling the method causes the current thread to immediately block for the number of milliseconds or the time interval you pass to the method, and yields the remainder of its time slice to another thread. Once that interval elapses, the sleeping thread resumes execution. - One thread cannot call on another thread. is a static method that always causes the current thread to sleep. + One thread cannot call on another thread. is a static method that always causes the current thread to sleep. - Calling with a value of causes a thread to sleep until it is interrupted by another thread that calls the method on the sleeping thread, or until it is terminated by a call to its method. The following example illustrates both methods of interrupting a sleeping thread. + Calling with a value of causes a thread to sleep until it is interrupted by another thread that calls the method on the sleeping thread, or until it is terminated by a call to its method. The following example illustrates both methods of interrupting a sleeping thread. [!code-csharp[Conceptual.Threading.Resuming#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.Threading.Resuming/cs/Sleep1.cs#1)] [!code-vb[Conceptual.Threading.Resuming#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.Threading.Resuming/vb/Sleep1.vb#1)] ## Interrupting Threads - You can interrupt a waiting thread by calling the method on the blocked thread to throw a , which breaks the thread out of the blocking call. The thread should catch the and do whatever is appropriate to continue working. If the thread ignores the exception, the runtime catches the exception and stops the thread. + You can interrupt a waiting thread by calling the method on the blocked thread to throw a , which breaks the thread out of the blocking call. The thread should catch the and do whatever is appropriate to continue working. If the thread ignores the exception, the runtime catches the exception and stops the thread. > [!NOTE] -> If the target thread is not blocked when is called, the thread is not interrupted until it blocks. If the thread never blocks, it could complete without ever being interrupted. +> If the target thread is not blocked when is called, the thread is not interrupted until it blocks. If the thread never blocks, it could complete without ever being interrupted. - If a wait is a managed wait, then and both wake the thread immediately. If a wait is an unmanaged wait (for example, a platform invoke call to the Win32 [WaitForSingleObject](https://msdn.microsoft.com/library/windows/desktop/ms687032\(v=vs.85\).aspx) function), neither nor can take control of the thread until it returns to or calls into managed code. In managed code, the behavior is as follows: + If a wait is a managed wait, then and both wake the thread immediately. If a wait is an unmanaged wait (for example, a platform invoke call to the Win32 [WaitForSingleObject](https://msdn.microsoft.com/library/windows/desktop/ms687032\(v=vs.85\).aspx) function), neither nor can take control of the thread until it returns to or calls into managed code. In managed code, the behavior is as follows: -- wakes a thread out of any wait it might be in and causes a to be thrown in the destination thread. +- wakes a thread out of any wait it might be in and causes a to be thrown in the destination thread. -- wakes a thread out of any wait it might be in and causes a to be thrown on the thread. For details, see [Destroying Threads](../../../docs/standard/threading/destroying-threads.md). +- wakes a thread out of any wait it might be in and causes a to be thrown on the thread. For details, see [Destroying Threads](../../../docs/standard/threading/destroying-threads.md). ## See Also diff --git a/docs/standard/threading/semaphore-and-semaphoreslim.md b/docs/standard/threading/semaphore-and-semaphoreslim.md index 420f3c5fc2ee6..6b0d5c521a95a 100644 --- a/docs/standard/threading/semaphore-and-semaphoreslim.md +++ b/docs/standard/threading/semaphore-and-semaphoreslim.md @@ -22,17 +22,17 @@ ms.author: "ronpet" manager: "wpickett" --- # Semaphore and SemaphoreSlim -The class represents a named (systemwide) or local semaphore. It is a thin wrapper around the Win32 semaphore object. Win32 semaphores are counting semaphores, which can be used to control access to a pool of resources. +The class represents a named (systemwide) or local semaphore. It is a thin wrapper around the Win32 semaphore object. Win32 semaphores are counting semaphores, which can be used to control access to a pool of resources. The class represents a lightweight, fast semaphore that can be used for waiting within a single process when wait times are expected to be very short. relies as much as possible on synchronization primitives provided by the common language runtime (CLR). However, it also provides lazily initialized, kernel-based wait handles as necessary to support waiting on multiple semaphores. also supports the use of cancellation tokens, but it does not support named semaphores or the use of a wait handle for synchronization. ## Managing a Limited Resource - Threads enter the semaphore by calling the method, which is inherited from the class, in the case of a object, or the or method, in the case of a object.. When the call returns, the count on the semaphore is decremented. When a thread requests entry and the count is zero, the thread blocks. As threads release the semaphore by calling the or method, blocked threads are allowed to enter. There is no guaranteed order, such as first-in, first-out (FIFO) or last-in, first-out (LIFO), for blocked threads to enter the semaphore. + Threads enter the semaphore by calling the method, which is inherited from the class, in the case of a object, or the or method, in the case of a object.. When the call returns, the count on the semaphore is decremented. When a thread requests entry and the count is zero, the thread blocks. As threads release the semaphore by calling the or method, blocked threads are allowed to enter. There is no guaranteed order, such as first-in, first-out (FIFO) or last-in, first-out (LIFO), for blocked threads to enter the semaphore. - A thread can enter the semaphore multiple times by calling the object's method or the object's method repeatedly. To release the semaphore, the thread can either call the or method overload the same number of times, or call the or method overload and specify the number of entries to be released. + A thread can enter the semaphore multiple times by calling the object's method or the object's method repeatedly. To release the semaphore, the thread can either call the or method overload the same number of times, or call the or method overload and specify the number of entries to be released. ### Semaphores and Thread Identity - The two semaphore types do not enforce thread identity on calls to the , , , and methods. For example, a common usage scenario for semaphores involves a producer thread and a consumer thread, with one thread always incrementing the semaphore count and the other always decrementing it. + The two semaphore types do not enforce thread identity on calls to the , , , and methods. For example, a common usage scenario for semaphores involves a producer thread and a consumer thread, with one thread always incrementing the semaphore count and the other always decrementing it. It is the programmer's responsibility to ensure that a thread does not release the semaphore too many times. For example, suppose a semaphore has a maximum count of two, and that thread A and thread B both enter the semaphore. If a programming error in thread B causes it to call `Release` twice, both calls succeed. The count on the semaphore is full, and when thread A eventually calls `Release`, , a is thrown. @@ -42,11 +42,11 @@ The class represents You can create a object that represents a named system semaphore by using one of the constructors that specifies a name. > [!NOTE] -> Because named semaphores are system wide, it is possible to have multiple objects that represent the same named semaphore. Each time you call a constructor or the method, a new object is created. Specifying the same name repeatedly creates multiple objects that represent the same named semaphore. +> Because named semaphores are system wide, it is possible to have multiple objects that represent the same named semaphore. Each time you call a constructor or the method, a new object is created. Specifying the same name repeatedly creates multiple objects that represent the same named semaphore. Be careful when you use named semaphores. Because they are system wide, another process that uses the same name can enter your semaphore unexpectedly. Malicious code executing on the same computer could use this as the basis of a denial-of-service attack. - Use access control security to protect a object that represents a named semaphore, preferably by using a constructor that specifies a object. You can also apply access control security using the method, but this leaves a window of vulnerability between the time the semaphore is created and the time it is protected. Protecting semaphores with access control security helps prevent malicious attacks, but does not solve the problem of unintentional name collisions. + Use access control security to protect a object that represents a named semaphore, preferably by using a constructor that specifies a object. You can also apply access control security using the method, but this leaves a window of vulnerability between the time the semaphore is created and the time it is protected. Protecting semaphores with access control security helps prevent malicious attacks, but does not solve the problem of unintentional name collisions. ## See Also diff --git a/docs/standard/threading/spinlock.md b/docs/standard/threading/spinlock.md index a672e36aa0171..012f4dcdc4436 100644 --- a/docs/standard/threading/spinlock.md +++ b/docs/standard/threading/spinlock.md @@ -17,13 +17,13 @@ ms.author: "ronpet" manager: "wpickett" --- # SpinLock -The structure is a low-level, mutual-exclusion synchronization primitive that spins while it waits to acquire a lock. On multicore computers, when wait times are expected to be short and when contention is minimal, can perform better than other kinds of locks. However, we recommend that you use only when you determine by profiling that the method or the methods are significantly slowing the performance of your program. +The structure is a low-level, mutual-exclusion synchronization primitive that spins while it waits to acquire a lock. On multicore computers, when wait times are expected to be short and when contention is minimal, can perform better than other kinds of locks. However, we recommend that you use only when you determine by profiling that the method or the methods are significantly slowing the performance of your program. may yield the time slice of the thread even if it has not yet acquired the lock. It does this to avoid thread-priority inversion, and to enable the garbage collector to make progress. When you use a , ensure that no thread can hold the lock for more than a very brief time span, and that no thread can block while it holds the lock. Because SpinLock is a value type, you must explicitly pass it by reference if you intend the two copies to refer to the same lock. - For more information about how to use this type, see . For an example, see [How to: Use SpinLock for Low-Level Synchronization](../../../docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md). + For more information about how to use this type, see . For an example, see [How to: Use SpinLock for Low-Level Synchronization](../../../docs/standard/threading/how-to-use-spinlock-for-low-level-synchronization.md). supports a *thread*-*tracking* mode that you can use during the development phase to help track the thread that is holding the lock at a specific time. Thread-tracking mode is very useful for debugging, but we recommend that you turn it off in the release version of your program because it may slow performance. For more information, see [How to: Enable Thread-Tracking Mode in SpinLock](../../../docs/standard/threading/how-to-enable-thread-tracking-mode-in-spinlock.md). diff --git a/docs/standard/threading/spinwait.md b/docs/standard/threading/spinwait.md index 334e122835fc8..eb3bf6faf127a 100644 --- a/docs/standard/threading/spinwait.md +++ b/docs/standard/threading/spinwait.md @@ -17,13 +17,13 @@ ms.author: "ronpet" manager: "wpickett" --- # SpinWait - is a lightweight synchronization type that you can use in low-level scenarios to avoid the expensive context switches and kernel transitions that are required for kernel events. On multicore computers, when a resource is not expected to be held for long periods of time, it can be more efficient for a waiting thread to spin in user mode for a few dozen or a few hundred cycles, and then retry to acquire the resource. If the resource is available after spinning, then you have saved several thousand cycles. If the resource is still not available, then you have spent only a few cycles and can still enter a kernel-based wait. This spinning-then-waiting combination is sometimes referred to as a *two-phase wait operation*. + is a lightweight synchronization type that you can use in low-level scenarios to avoid the expensive context switches and kernel transitions that are required for kernel events. On multicore computers, when a resource is not expected to be held for long periods of time, it can be more efficient for a waiting thread to spin in user mode for a few dozen or a few hundred cycles, and then retry to acquire the resource. If the resource is available after spinning, then you have saved several thousand cycles. If the resource is still not available, then you have spent only a few cycles and can still enter a kernel-based wait. This spinning-then-waiting combination is sometimes referred to as a *two-phase wait operation*. is designed to be used in conjunction with the .NET Framework types that wrap kernel events such as . can also be used by itself for basic spinning functionality in just one program. is more than just an empty loop. It is carefully implemented to provide correct spinning behavior for the general case, and will itself initiate context switches if it spins long enough (roughly the length of time required for a kernel transition). For example, on single-core computers, yields the time slice of the thread immediately because spinning blocks forward progress on all threads. also yields even on multi-core machines to prevent the waiting thread from blocking higher-priority threads or the garbage collector. Therefore, if you are using a in a two-phase wait operation, we recommend that you invoke the kernel wait before the itself initiates a context switch. provides the property, which you can check before every call to . When the property returns `true`, initiate your own Wait operation. For an example, see [How to: Use SpinWait to Implement a Two-Phase Wait Operation](../../../docs/standard/threading/how-to-use-spinwait-to-implement-a-two-phase-wait-operation.md). - If you are not performing a two-phase wait operation but are just spinning until some condition is true, you can enable to perform its context switches so that it is a good citizen in the Windows operating system environment. The following basic example shows a in a lock-free stack. If you require a high-performance, thread-safe stack, consider using . + If you are not performing a two-phase wait operation but are just spinning until some condition is true, you can enable to perform its context switches so that it is a good citizen in the Windows operating system environment. The following basic example shows a in a lock-free stack. If you require a high-performance, thread-safe stack, consider using . [!code-csharp[CDS_SpinWait#05](../../../samples/snippets/csharp/VS_Snippets_Misc/cds_spinwait/cs/spinwait.cs#05)] [!code-vb[CDS_SpinWait#05](../../../samples/snippets/visualbasic/VS_Snippets_Misc/cds_spinwait/vb/cds_spinwait1.vb#05)] diff --git a/docs/standard/threading/synchronizing-data-for-multithreading.md b/docs/standard/threading/synchronizing-data-for-multithreading.md index 17923d343205c..d519c2f79af84 100644 --- a/docs/standard/threading/synchronizing-data-for-multithreading.md +++ b/docs/standard/threading/synchronizing-data-for-multithreading.md @@ -29,7 +29,7 @@ When multiple threads can make calls to the properties and methods of a single o - Synchronized contexts. You can use the to enable simple, automatic synchronization for objects. -- Collection classes in the namespace. These classes provide built-in synchronized add and remove operations. For more information, see [Thread-Safe Collections](../../../docs/standard/collections/thread-safe/index.md). +- Collection classes in the namespace. These classes provide built-in synchronized add and remove operations. For more information, see [Thread-Safe Collections](../../../docs/standard/collections/thread-safe/index.md). The common language runtime provides a thread model in which classes fall into a number of categories that can be synchronized in a variety of different ways depending on the requirements. The following table shows what synchronization support is provided for fields and methods with a given synchronization category. @@ -52,17 +52,17 @@ When multiple threads can make calls to the properties and methods of a single o Both Visual Basic and C# support the marking of blocks of code with a particular language keyword, the `lock` statement in C# or the `SyncLock` statement in Visual Basic. When the code is executed by a thread, an attempt is made to acquire the lock. If the lock has already been acquired by another thread, the thread blocks until the lock becomes available. When the thread exits the synchronized block of code, the lock is released, no matter how the thread exits the block. > [!NOTE] -> The `lock` and `SyncLock` statements are implemented using and , so other methods of can be used in conjunction with them within the synchronized region. +> The `lock` and `SyncLock` statements are implemented using and , so other methods of can be used in conjunction with them within the synchronized region. You can also decorate a method with a **MethodImplAttribute** and **MethodImplOptions.Synchronized**, which has the same effect as using **Monitor** or one of the compiler keywords to lock the entire body of the method. - can be used to break a thread out of blocking operations such as waiting for access to a synchronized region of code. **Thread.Interrupt** is also used to break threads out of operations like . + can be used to break a thread out of blocking operations such as waiting for access to a synchronized region of code. **Thread.Interrupt** is also used to break threads out of operations like . > [!IMPORTANT] > Do not lock the type — that is, `typeof(MyType)` in C#, `GetType(MyType)` in Visual Basic, or `MyType::typeid` in C++ — in order to protect `static` methods (`Shared` methods in Visual Basic). Use a private static object instead. Similarly, do not use `this` in C# (`Me` in Visual Basic) to lock instance methods. Use a private object instead. A class or instance can be locked by code other than your own, potentially causing deadlocks or performance problems. ### Compiler Support - Both Visual Basic and C# support a language keyword that uses and to lock the object. Visual Basic supports the [SyncLock](~/docs/visual-basic/language-reference/statements/synclock-statement.md) statement; C# supports the [lock](~/docs/csharp/language-reference/keywords/lock-statement.md) statement. + Both Visual Basic and C# support a language keyword that uses and to lock the object. Visual Basic supports the [SyncLock](~/docs/visual-basic/language-reference/statements/synclock-statement.md) statement; C# supports the [lock](~/docs/csharp/language-reference/keywords/lock-statement.md) statement. In both cases, if an exception is thrown in the code block, the lock acquired by the **lock** or **SyncLock** is released automatically. The C# and Visual Basic compilers emit a **try**/**finally** block with **Monitor.Enter** at the beginning of the try, and **Monitor.Exit** in the **finally** block. If an exception is thrown inside the **lock** or **SyncLock** block, the **finally** handler runs to allow you to do any clean-up work. diff --git a/docs/standard/threading/the-managed-thread-pool.md b/docs/standard/threading/the-managed-thread-pool.md index 617c799c10b34..8dea643552f04 100644 --- a/docs/standard/threading/the-managed-thread-pool.md +++ b/docs/standard/threading/the-managed-thread-pool.md @@ -81,13 +81,13 @@ The class provides your application with a po > You can use the method to increase the minimum number of idle threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads. ## Skipping Security Checks - The thread pool also provides the and methods. Use these methods only when you are certain that the caller's stack is irrelevant to any security checks performed during the execution of the queued task. and both capture the caller's stack, which is merged into the stack of the thread pool thread when the thread begins to execute a task. If a security check is required, the entire stack must be checked. Although the check provides safety, it also has a performance cost. + The thread pool also provides the and methods. Use these methods only when you are certain that the caller's stack is irrelevant to any security checks performed during the execution of the queued task. and both capture the caller's stack, which is merged into the stack of the thread pool thread when the thread begins to execute a task. If a security check is required, the entire stack must be checked. Although the check provides safety, it also has a performance cost. ## Using the Thread Pool - Beginning with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], the easiest way to use the thread pool is to use the [Task Parallel Library (TPL)](../../../docs/standard/parallel-programming/task-parallel-library-tpl.md). By default, parallel library types like and use thread pool threads to run tasks. You can also use the thread pool by calling from managed code (or `CorQueueUserWorkItem` from unmanaged code) and passing a delegate representing the method that performs the task. Another way to use the thread pool is to queue work items that are related to a wait operation by using the method and passing a that, when signaled or when timed out, calls the method represented by the delegate. Thread pool threads are used to invoke callback methods. + Beginning with the [!INCLUDE[net_v40_short](../../../includes/net-v40-short-md.md)], the easiest way to use the thread pool is to use the [Task Parallel Library (TPL)](../../../docs/standard/parallel-programming/task-parallel-library-tpl.md). By default, parallel library types like and use thread pool threads to run tasks. You can also use the thread pool by calling from managed code (or `CorQueueUserWorkItem` from unmanaged code) and passing a delegate representing the method that performs the task. Another way to use the thread pool is to queue work items that are related to a wait operation by using the method and passing a that, when signaled or when timed out, calls the method represented by the delegate. Thread pool threads are used to invoke callback methods. ## ThreadPool Examples - The code examples in this section demonstrate the thread pool by using the class, the method, and the method. + The code examples in this section demonstrate the thread pool by using the class, the method, and the method. - [Executing Asynchronous Tasks with the Task Parallel Library](#TaskParallelLibrary) @@ -99,7 +99,7 @@ The class provides your application with a po ### Executing Asynchronous Tasks with the Task Parallel Library - The following example shows how to create and use a object by calling the method. For an example that uses the class to return a value from an asynchronous task, see [How to: Return a Value from a Task](../../../docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md). + The following example shows how to create and use a object by calling the method. For an example that uses the class to return a value from an asynchronous task, see [How to: Return a Value from a Task](../../../docs/standard/parallel-programming/how-to-return-a-value-from-a-task.md). [!code-csharp[System.Threading.Tasks.Task#01](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task/cs/startnew.cs#01)] [!code-vb[System.Threading.Tasks.Task#01](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/startnew.vb#01)] diff --git a/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md b/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md index e074460056090..e9042ad119614 100644 --- a/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md +++ b/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md @@ -28,7 +28,7 @@ You can use managed thread local storage (TLS) to store data that is unique to a In unmanaged C++, you use `TlsAlloc` to allocate slots dynamically and `__declspec(thread)` to declare that a variable should be allocated in thread-relative storage. Thread-relative static fields and data slots provide the managed version of this behavior. - In the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], you can use the class to create thread-local objects that are initialized lazily when the object is first consumed. For more information, see [Lazy Initialization](../../../docs/framework/performance/lazy-initialization.md). + In the [!INCLUDE[net_v40_long](../../../includes/net-v40-long-md.md)], you can use the class to create thread-local objects that are initialized lazily when the object is first consumed. For more information, see [Lazy Initialization](../../../docs/framework/performance/lazy-initialization.md). ## Uniqueness of Data in Managed TLS Whether you use thread-relative static fields or data slots, data in managed TLS is unique to the combination of thread and application domain. @@ -51,17 +51,17 @@ You can use managed thread local storage (TLS) to store data that is unique to a ## Data Slots The .NET Framework provides dynamic data slots that are unique to a combination of thread and application-domain. There are two types of data slots: named slots and unnamed slots. Both are implemented by using the structure. -- To create a named data slot, use the or method. To get a reference to an existing named slot, pass its name to the method. +- To create a named data slot, use the or method. To get a reference to an existing named slot, pass its name to the method. -- To create an unnamed data slot, use the method. +- To create an unnamed data slot, use the method. - For both named and unnamed slots, use the and methods to set and retrieve the information in the slot. These are static methods that always act on the data for the thread that is currently executing them. + For both named and unnamed slots, use the and methods to set and retrieve the information in the slot. These are static methods that always act on the data for the thread that is currently executing them. Named slots can be convenient, because you can retrieve the slot when you need it by passing its name to the method, instead of maintaining a reference to an unnamed slot. However, if another component uses the same name for its thread-relative storage and a thread executes code from both your component and the other component, the two components might corrupt each other's data. (This scenario assumes that both components are running in the same application domain, and that they are not designed to share the same data.) ## See Also - + [Threading](../../../docs/standard/threading/index.md) diff --git a/docs/standard/threading/thread-suspend-garbage-collection-and-safe-points.md b/docs/standard/threading/thread-suspend-garbage-collection-and-safe-points.md index 9a38c38e37fe8..0cc46d0f15eab 100644 --- a/docs/standard/threading/thread-suspend-garbage-collection-and-safe-points.md +++ b/docs/standard/threading/thread-suspend-garbage-collection-and-safe-points.md @@ -21,7 +21,7 @@ ms.author: "ronpet" manager: "wpickett" --- # Thread.Suspend, Garbage Collection, and Safe Points -When you call on a thread, the system notes that a thread suspension has been requested and allows the thread to execute until it has reached a safe point before actually suspending the thread. A safe point for a thread is a point in its execution at which garbage collection can be performed. +When you call on a thread, the system notes that a thread suspension has been requested and allows the thread to execute until it has reached a safe point before actually suspending the thread. A safe point for a thread is a point in its execution at which garbage collection can be performed. Once a safe point is reached, the runtime guarantees that the suspended thread will not make any further progress in managed code. A thread executing outside managed code is always safe for garbage collection, and its execution continues until it attempts to resume execution of managed code. diff --git a/docs/standard/threading/threads-and-threading.md b/docs/standard/threading/threads-and-threading.md index 0fa2202668ed7..5c39fbfedea56 100644 --- a/docs/standard/threading/threads-and-threading.md +++ b/docs/standard/threading/threads-and-threading.md @@ -21,7 +21,7 @@ manager: "wpickett" # Threads and Threading Operating systems use processes to separate the different applications that they are executing. Threads are the basic unit to which an operating system allocates processor time, and more than one thread can be executing code inside that process. Each thread maintains exception handlers, a scheduling priority, and a set of structures the system uses to save the thread context until it is scheduled. The thread context includes all the information the thread needs to seamlessly resume execution, including the thread's set of CPU registers and stack, in the address space of the thread's host process. - The .NET Framework further subdivides an operating system process into lightweight managed subprocesses, called application domains, represented by . One or more managed threads (represented by ) can run in one or any number of application domains within the same managed process. Although each application domain is started with a single thread, code in that application domain can create additional application domains and additional threads. The result is that a managed thread can move freely between application domains inside the same managed process; you might have only one thread moving among several application domains. + The .NET Framework further subdivides an operating system process into lightweight managed subprocesses, called application domains, represented by . One or more managed threads (represented by ) can run in one or any number of application domains within the same managed process. Although each application domain is started with a single thread, code in that application domain can create additional application domains and additional threads. The result is that a managed thread can move freely between application domains inside the same managed process; you might have only one thread moving among several application domains. An operating system that supports preemptive multitasking creates the effect of simultaneous execution of multiple threads from multiple processes. It does this by dividing the available processor time among the threads that need it, allocating a processor time slice to each thread one after another. The currently executing thread is suspended when its time slice elapses, and another thread resumes running. When the system switches from one thread to another, it saves the thread context of the preempted thread and reloads the saved thread context of the next thread in the thread queue. diff --git a/docs/standard/threading/timers.md b/docs/standard/threading/timers.md index 7e86e98af9704..05cab805e4b03 100644 --- a/docs/standard/threading/timers.md +++ b/docs/standard/threading/timers.md @@ -20,10 +20,10 @@ manager: "wpickett" # Timers Timers are lightweight objects that enable you to specify a delegate to be called at a specified time. A thread in the thread pool performs the wait operation. - Using the class is straightforward. You create a **Timer**, passing a delegate to the callback method, an object representing state that will be passed to the callback, an initial raise time, and a time representing the period between callback invocations. To cancel a pending timer, call the **Timer.Dispose** function. + Using the class is straightforward. You create a **Timer**, passing a delegate to the callback method, an object representing state that will be passed to the callback, an initial raise time, and a time representing the period between callback invocations. To cancel a pending timer, call the **Timer.Dispose** function. > [!NOTE] -> There are two other timer classes. The class is a control that works with visual designers and is meant to be used in user interface contexts; it raises events on the user interface thread. The class derives from , so it can be used with visual designers; it also raises events, but it raises them on a thread. The class makes callbacks on a thread and does not use the event model at all. It also provides a state object to the callback method, which the other timers do not. It is extremely lightweight. +> There are two other timer classes. The class is a control that works with visual designers and is meant to be used in user interface contexts; it raises events on the user interface thread. The class derives from , so it can be used with visual designers; it also raises events, but it raises them on a thread. The class makes callbacks on a thread and does not use the event model at all. It also provides a state object to the callback method, which the other timers do not. It is extremely lightweight. The following code example starts a timer that starts after one second (1000 milliseconds) and ticks every second until you press the **Enter** key. The variable containing the reference to the timer is a class-level field, to ensure that the timer is not subject to garbage collection while it is still running. For more information on aggressive garbage collection, see . diff --git a/docs/visual-basic/developing-apps/creating-and-using-components.md b/docs/visual-basic/developing-apps/creating-and-using-components.md index b9f80676d808c..944c2d093d59a 100644 --- a/docs/visual-basic/developing-apps/creating-and-using-components.md +++ b/docs/visual-basic/developing-apps/creating-and-using-components.md @@ -34,7 +34,7 @@ translation.priority.ht: - "zh-tw" --- # Creating and Using Components in Visual Basic -A *component* is a class that implements the interface or that derives directly or indirectly from a class that implements . A [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] component is an object that is reusable, can interact with other objects, and provides control over external resources and design-time support. +A *component* is a class that implements the interface or that derives directly or indirectly from a class that implements . A [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] component is an object that is reusable, can interact with other objects, and provides control over external resources and design-time support. An important feature of components is that they are designable, which means that a class that is a component can be used in the [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] Integrated Development Environment. A component can be added to the Toolbox, dragged and dropped onto a form, and manipulated on a design surface. Notice that base design-time support for components is built into the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)]; a component developer does not have to do any additional work to take advantage of the base design-time functionality. diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md b/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md index e1cfa1b97dc67..a8003e14ba85d 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md @@ -61,7 +61,7 @@ The `My.Computer.Ports` object provides a property and a method for accessing th Describes the `SerialPortNames` property, which gets a collection of the names of the serial ports on the computer. - Describes the `OpenSerialPort` method, which creates and opens a object. + Describes the `OpenSerialPort` method, which creates and opens a object. ## Related Sections diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-keyboard.md b/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-keyboard.md index 1a10322e5ccdd..3948c0cde13c4 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-keyboard.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/accessing-the-keyboard.md @@ -54,4 +54,4 @@ The `My.Computer.Keyboard` object provides properties for accessing the current ## See Also - + diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-check-connection-status.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-check-connection-status.md index 13e73616933e2..8fdeca3ac633e 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-check-connection-status.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-check-connection-status.md @@ -50,5 +50,5 @@ The property can be This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Connectivity and Networking**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). ## See Also - + diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md index 0853f71e1b586..88171cad0c8aa 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md @@ -64,7 +64,7 @@ This topic describes how to use `My.Computer.Ports` to dial a modem in [!INCLUDE This code example is also available as an IntelliSense code snippet. In the code snippet picker, it is located in **Connectivity and Networking**. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). ## Compiling the Code - This example requires a reference to the namespace. + This example requires a reference to the namespace. ## Robust Programming This example assumes the modem is connected to COM1. We recommend that your code allow the user to select the desired serial port from a list of available ports. For more information, see [How to: Show Available Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-show-available-serial-ports.md). @@ -75,7 +75,7 @@ This topic describes how to use `My.Computer.Ports` to dial a modem in [!INCLUDE ## See Also - + [How to: Send Strings to Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md) [How to: Receive Strings From Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md) [How to: Show Available Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-show-available-serial-ports.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md index 88678164f4d49..9960d303ecb8d 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-receive-strings-from-serial-ports.md @@ -87,7 +87,7 @@ This topic describes how to use `My.Computer.Ports` to receive strings from the ## See Also - + [How to: Dial Modems Attached to Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md) [How to: Send Strings to Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md) [How to: Show Available Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-show-available-serial-ports.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md index ccd7f80fada17..b2180e50b12c1 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-send-strings-to-serial-ports.md @@ -61,6 +61,6 @@ This topic describes how to use `My.Computer.Ports` to send strings to the compu ## See Also - + [How to: Dial Modems Attached to Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-dial-modems-attached-to-serial-ports.md) [How to: Show Available Serial Ports](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-show-available-serial-ports.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-upload-a-file.md b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-upload-a-file.md index 9087607d63c53..aaf6b891e3ba3 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/how-to-upload-a-file.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/how-to-upload-a-file.md @@ -68,7 +68,7 @@ The method can be use - The connection timed out (). ## See Also - + [How to: Download a File](../../../../visual-basic/developing-apps/programming/computer-resources/how-to-download-a-file.md) [How to: Parse File Paths](../../../../visual-basic/developing-apps/programming/drives-directories-files/how-to-parse-file-paths.md) diff --git a/docs/visual-basic/developing-apps/programming/computer-resources/port-operations-in-the-net-framework.md b/docs/visual-basic/developing-apps/programming/computer-resources/port-operations-in-the-net-framework.md index 6e86c8a4ee3f6..82b446806524e 100644 --- a/docs/visual-basic/developing-apps/programming/computer-resources/port-operations-in-the-net-framework.md +++ b/docs/visual-basic/developing-apps/programming/computer-resources/port-operations-in-the-net-framework.md @@ -34,7 +34,7 @@ translation.priority.ht: - "zh-tw" --- # Port Operations in the .NET Framework with Visual Basic -You can access your computer's serial ports through the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] classes in the namespace. The most important class, , provides a framework for synchronous and event-driven I/O, access to pin and break states, and access to serial driver properties. It can be wrapped in a object, accessible through the property. Wrapping in a object allows the serial port to be accessed by classes that use streams. The namespace includes enumerations that simplify the control of serial ports. +You can access your computer's serial ports through the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] classes in the namespace. The most important class, , provides a framework for synchronous and event-driven I/O, access to pin and break states, and access to serial driver properties. It can be wrapped in a object, accessible through the property. Wrapping in a object allows the serial port to be accessed by classes that use streams. The namespace includes enumerations that simplify the control of serial ports. The simplest way to create a object is through the method. diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/classes-used-in-net-framework-file-io-and-the-file-system.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/classes-used-in-net-framework-file-io-and-the-file-system.md index bd4ebbc0cc5d4..f334aec4ad2de 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/classes-used-in-net-framework-file-io-and-the-file-system.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/classes-used-in-net-framework-file-io-and-the-file-system.md @@ -43,40 +43,40 @@ The following tables list the classes commonly used for .NET Framework file I/O, |Class|Description| |-----------|-----------------| -||Provides static methods for creating, moving, and enumerating through directories and subdirectories.| -||Provides instance methods for creating, moving, and enumerating through directories and subdirectories.| -||Provides instance methods for creating, moving, and enumerating through drives.| -||Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of a `FileStream`.| -||Defines constants for read, write, or read/write access to a file.| -||Provides attributes for files and directories such as `Archive`, `Hidden`, and `ReadOnly`.| -||Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of a `FileStream`.| -||Controls how a file is opened. This parameter is specified in many of the constructors for `FileStream` and `IsolatedStorageFileStream`, and for the `Open` methods of and .| -||Defines constants for controlling the type of access other file streams can have to the same file.| -||Provides methods and properties for processing directory strings.| -||Controls the access of files and folders by defining , , and permissions.| +||Provides static methods for creating, moving, and enumerating through directories and subdirectories.| +||Provides instance methods for creating, moving, and enumerating through directories and subdirectories.| +||Provides instance methods for creating, moving, and enumerating through drives.| +||Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of a `FileStream`.| +||Defines constants for read, write, or read/write access to a file.| +||Provides attributes for files and directories such as `Archive`, `Hidden`, and `ReadOnly`.| +||Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of a `FileStream`.| +||Controls how a file is opened. This parameter is specified in many of the constructors for `FileStream` and `IsolatedStorageFileStream`, and for the `Open` methods of and .| +||Defines constants for controlling the type of access other file streams can have to the same file.| +||Provides methods and properties for processing directory strings.| +||Controls the access of files and folders by defining , , and permissions.| ## Classes Used to Create Streams The following table lists and describes the main classes used to create streams. |Class|Description| |-----------|-----------------| -||Adds a buffering layer to read and write operations on another stream.| -||Supports random access to files through its method. opens files synchronously by default but also supports asynchronous operation.| -||Creates a stream whose backing store is memory, rather than a file.| -||Provides the underlying stream of data for network access.| -||Defines a stream that links data streams to cryptographic transformations.| +||Adds a buffering layer to read and write operations on another stream.| +||Supports random access to files through its method. opens files synchronously by default but also supports asynchronous operation.| +||Creates a stream whose backing store is memory, rather than a file.| +||Provides the underlying stream of data for network access.| +||Defines a stream that links data streams to cryptographic transformations.| ## Classes Used to Read from and Write to Streams The following table shows the specific classes used for reading from and writing to files with streams. |**Class**|**Description**| |---------------|---------------------| -||Reads encoded strings and primitive data types from a .| -||Writes encoded strings and primitive data types to a .| -||Reads characters from a , using to convert characters to and from bytes. has a constructor that attempts to ascertain the correct for a given stream, based on the presence of a -specific preamble, such as a byte order mark.| -||Writes characters to a `FileStream`, using to convert characters to bytes.| -||Reads characters from a `String`. Output can be either a stream in any encoding or a `String`.| -||Writes characters to a `String`. Output can be either a stream in any encoding or a `String`.| +||Reads encoded strings and primitive data types from a .| +||Writes encoded strings and primitive data types to a .| +||Reads characters from a , using to convert characters to and from bytes. has a constructor that attempts to ascertain the correct for a given stream, based on the presence of a -specific preamble, such as a byte order mark.| +||Writes characters to a `FileStream`, using to convert characters to bytes.| +||Reads characters from a `String`. Output can be either a stream in any encoding or a `String`.| +||Writes characters to a `String`. Output can be either a stream in any encoding or a `String`.| ## See Also [Composing Streams](https://msdn.microsoft.com/library/e4y2dch9) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory.md index aed6365446f29..19344b747f90c 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-get-the-collection-of-files-in-a-directory.md @@ -35,17 +35,17 @@ translation.priority.ht: - "zh-tw" --- # How to: Get the Collection of Files in a Directory in Visual Basic -The overloads of the method return a read-only collection of strings representing the names of the files within a directory: +The overloads of the method return a read-only collection of strings representing the names of the files within a directory: - Use the overload for a simple file search in a specified directory, without searching subdirectories. -- Use the overload to specify additional options for your search. You can use the `wildCards` parameter to specify a search pattern. To include subdirectories in the search, set the `searchType` parameter to . +- Use the overload to specify additional options for your search. You can use the `wildCards` parameter to specify a search pattern. To include subdirectories in the search, set the `searchType` parameter to . An empty collection is returned if no files matching the specified pattern are found. ### To list files in a directory -- Use one of the method overloads, supplying the name and path of the directory to search in the `directory` parameter. The following example returns all files in the directory and adds them to `ListBox1`. +- Use one of the method overloads, supplying the name and path of the directory to search in the `directory` parameter. The following example returns all files in the directory and adds them to `ListBox1`. [!code-vb[VbVbcnMyFileSystem#32](../../../../visual-basic/developing-apps/programming/drives-directories-files/codesnippet/VisualBasic/how-to-get-the-collection-of-files-in-a-directory_1.vb)] diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md index bc442fe7acd7d..9dc488a748304 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md @@ -76,7 +76,7 @@ The `TextFieldParser` object provides a way to easily and efficiently parse stru - The user does not have sufficient permissions to access the file (). ## See also - + [How to: Read From Fixed-width Text Files](../../../../visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md) [How to: Read From Text Files with Multiple Formats](../../../../visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md) [Parsing Text Files with the TextFieldParser Object](../../../../visual-basic/developing-apps/programming/drives-directories-files/parsing-text-files-with-the-textfieldparser-object.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md index a5693ffb60e8e..e5e32f21ef954 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-fixed-width-text-files.md @@ -79,7 +79,7 @@ The `TextFieldParser` object provides a way to easily and efficiently parse stru - The user does not have sufficient permissions to access the file (). ## See also - + [How to: Read From Comma-Delimited Text Files](../../../../visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-comma-delimited-text-files.md) [How to: Read From Text Files with Multiple Formats](../../../../visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md) [Parsing Text Files with the TextFieldParser Object](../../../../visual-basic/developing-apps/programming/drives-directories-files/parsing-text-files-with-the-textfieldparser-object.md) diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md index 60c96612c2cf5..433ae087dc83a 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-read-from-text-files-with-multiple-formats.md @@ -91,7 +91,7 @@ The object provides a way to - The user does not have sufficient permissions to access the file (). ## See Also - + diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory.md index a61a78f8e831a..c145686f42e7c 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-in-the-my-documents-directory.md @@ -66,7 +66,7 @@ The `My.Computer.FileSystem.SpecialDirectories` object allows you to access spec This example creates a new file. If an application needs to create a file, that application needs Create permission for the folder. Permissions are set using access control lists. If the file already exists, the application needs only Write permission, a lesser privilege. Where possible, it is more secure to create the file during deployment, and only grant Read privileges to a single file, rather than to grant Create privileges for a folder. Also, it is more secure to write data to user folders than to the root folder or the **Program Files** folder. For more information, see [ACL Technology Overview](http://msdn.microsoft.com/en-us/06fbf66d-6f02-4378-b863-b2f12e349045). ## See Also - + diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/writing-to-files.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/writing-to-files.md index b9fc6a59a1c49..e3d3d15586f5a 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/writing-to-files.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/writing-to-files.md @@ -54,7 +54,7 @@ This section explains how to perform tasks that involve writing to files. Demonstrates how to create and write to a new text file in the **My Documents** directory. [How to: Write Text to Files with a StreamWriter](../../../../visual-basic/developing-apps/programming/drives-directories-files/how-to-write-text-to-files-with-a-streamwriter.md) - Demonstrates how to write to a file with a object. + Demonstrates how to write to a file with a object. ## Reference diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md index 781c98f37443a..75d95050741fb 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md @@ -88,7 +88,7 @@ You can use the `My.Application.Log` and `My.Log` objects to log information abo [!code-vb[VbVbalrMyApplicationLog#5](../../../../visual-basic/developing-apps/programming/log-info/codesnippet/VisualBasic/how-to-log-exceptions_7.vb)] ## See Also - + [Working with Application Logs](../../../../visual-basic/developing-apps/programming/log-info/working-with-application-logs.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-log-messages-when-the-application-starts-or-shuts-down.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-log-messages-when-the-application-starts-or-shuts-down.md index cb2aeb559e453..c6336da8d091a 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-log-messages-when-the-application-starts-or-shuts-down.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-log-messages-when-the-application-starts-or-shuts-down.md @@ -82,7 +82,7 @@ You can use the `My.Application.Log` and `My.Log` objects to log information abo [!code-vb[VbVbalrMyApplicationLog#3](../../../../visual-basic/developing-apps/programming/log-info/codesnippet/VisualBasic/how-to-log-messages-when-the-application-starts-or-shuts-down_3.vb)] ## See Also - + [Application Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/application-page-project-designer-visual-basic) diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md index babf91ba4b0d6..98d61f7c4a729 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md @@ -88,7 +88,7 @@ You can use the `My.Application.Log` and `My.Log` objects to log information abo After you configure the file log listener for an assembly, it receives all messages that `My.Application.Log` writes from that assembly. ## See Also - + [Working with Application Logs](../../../../visual-basic/developing-apps/programming/log-info/working-with-application-logs.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md index 2f7d8d93708e5..4ea63b7decd25 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md @@ -48,7 +48,7 @@ You can use the `My.Application.Log` and `My.Log` objects to log information abo Make sure the data you write to the log does not include sensitive information such as user passwords. For more information, see [Working with Application Logs](../../../../visual-basic/developing-apps/programming/log-info/working-with-application-logs.md). ## See Also - + [Working with Application Logs](../../../../visual-basic/developing-apps/programming/log-info/working-with-application-logs.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md index b2ea2f189d5ee..aae3adc302d08 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md +++ b/docs/visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md @@ -93,7 +93,7 @@ You can use the `My.Application.Log` and `My.Log` objects to write information a After you configure the event log listener for an assembly, it receives all messages that `My.Applcation.Log` writes from that assembly. ## See Also - + [Working with Application Logs](../../../../visual-basic/developing-apps/programming/log-info/working-with-application-logs.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/logging-information-from-the-application.md b/docs/visual-basic/developing-apps/programming/log-info/logging-information-from-the-application.md index 63180ef5324a9..b80daebe56ed7 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/logging-information-from-the-application.md +++ b/docs/visual-basic/developing-apps/programming/log-info/logging-information-from-the-application.md @@ -60,6 +60,6 @@ This section contains topics that cover how to log information from your applica |Filter the output of the `My.Application.Log` logs.|[Walkthrough: Filtering My.Application.Log Output](../../../../visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md)| ## See Also - + [Working with Application Logs](../../../../visual-basic/developing-apps/programming/log-info/working-with-application-logs.md) [Troubleshooting: Log Listeners](../../../../visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md b/docs/visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md index eb7a5116da76a..d4b12b5c2be7e 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md +++ b/docs/visual-basic/developing-apps/programming/log-info/troubleshooting-log-listeners.md @@ -61,6 +61,6 @@ You can use the `My.Application.Log` and `My.Log` objects to log information abo For more information, see . ## See Also - + [Working with Application Logs](../../../../visual-basic/developing-apps/programming/log-info/working-with-application-logs.md) [Walkthrough: Determining Where My.Application.Log Writes Information](../../../../visual-basic/developing-apps/programming/log-info/walkthrough-determining-where-my-application-log-writes-information.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information.md b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information.md index 1bb1639754026..eef245e13d269 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information.md +++ b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information.md @@ -176,13 +176,13 @@ You can use the `My.Application.Log` and `My.Log` objects to log information abo Some types that you can use are: - - A listener, which writes to a file log. + - A listener, which writes to a file log. - - A listener, which writes information to the computer event log specified by the `initializeData` parameter. + - A listener, which writes information to the computer event log specified by the `initializeData` parameter. - - The and listeners, which write to the file specified in the `initializeData` parameter. + - The and listeners, which write to the file specified in the `initializeData` parameter. - - A listener, which writes to the command-line console. + - A listener, which writes to the command-line console. For information about where other types of log listeners write information, consult that type's documentation. @@ -205,9 +205,9 @@ You can use the `My.Application.Log` and `My.Log` objects to log information abo `Microsoft.VisualBasic.Logging.FileLogTraceListener, Microsoft.VisualBasic, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a` ## See Also - + - - + + [How to: Write Event Information to a Text File](../../../../visual-basic/developing-apps/programming/log-info/how-to-write-event-information-to-a-text-file.md) [How to: Write to an Application Event Log](../../../../visual-basic/developing-apps/programming/log-info/how-to-write-to-an-application-event-log.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-creating-custom-log-listeners.md b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-creating-custom-log-listeners.md index 0e775987b87fe..183c279ada0ca 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-creating-custom-log-listeners.md +++ b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-creating-custom-log-listeners.md @@ -127,7 +127,7 @@ This walkthrough demonstrates how to create a custom log listener and configure Change the value of `SimpleLogStrongName` to be the strong name of the listener. ## See Also - + [Working with Application Logs](../../../../visual-basic/developing-apps/programming/log-info/working-with-application-logs.md) [How to: Log Exceptions](../../../../visual-basic/developing-apps/programming/log-info/how-to-log-exceptions.md) [How to: Write Log Messages](../../../../visual-basic/developing-apps/programming/log-info/how-to-write-log-messages.md) diff --git a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-determining-where-my-application-log-writes-information.md b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-determining-where-my-application-log-writes-information.md index fa39122d0bbad..f6136fe2ce418 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-determining-where-my-application-log-writes-information.md +++ b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-determining-where-my-application-log-writes-information.md @@ -75,18 +75,18 @@ The `My.Application.Log` object can write information to several log listeners. 5. For many types of shared listeners, the listener's initialization data includes a description of where the listener directs the data: - - A listener writes to a file log, as described in the introduction. + - A listener writes to a file log, as described in the introduction. - - A listener writes information to the computer event log specified by the `initializeData` parameter. To view an event log, you can use **Server Explorer** or **Windows Event Viewer**. For more information, see [ETW Events in the .NET Framework](http://msdn.microsoft.com/library/d186276f-6afb-4dfd-bf3c-4251edc2c299). + - A listener writes information to the computer event log specified by the `initializeData` parameter. To view an event log, you can use **Server Explorer** or **Windows Event Viewer**. For more information, see [ETW Events in the .NET Framework](http://msdn.microsoft.com/library/d186276f-6afb-4dfd-bf3c-4251edc2c299). - - The and listeners write to the file specified in the `initializeData` parameter. + - The and listeners write to the file specified in the `initializeData` parameter. - - A listener writes to the command-line console. + - A listener writes to the command-line console. - For information about where other types of log listeners write information, consult that type's documentation. ## See Also - + diff --git a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md index e42479c16d41d..7575d986e1ff5 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md +++ b/docs/visual-basic/developing-apps/programming/log-info/walkthrough-filtering-my-application-log-output.md @@ -158,7 +158,7 @@ This walkthrough demonstrates how to change the default log filtering for the `M 9. Change the value of the `value` attribute back to "Information". > [!NOTE] - > The `DefaultSwitch` switch setting controls only `My.Application.Log`. It does not change how the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] and classes behave. + > The `DefaultSwitch` switch setting controls only `My.Application.Log`. It does not change how the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] and classes behave. ## Individual Filtering For My.Application.Log Listeners The previous example shows how to change the filtering for all `My.Application.Log` output. This example demonstrates how to filter an individual log listener. By default, an application has two listeners that write to the application's debug output and the log file. diff --git a/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md b/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md index a01b0e8794d31..4b58d90dc7647 100644 --- a/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md +++ b/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md @@ -124,5 +124,5 @@ The `My.Applicaton.Log` and `My.Log` objects make it easy to write logging and t - **Avoid denial of service.** If your application writes too much information to the log, it could fill the log or make finding important information difficult. ## See Also - + [Logging Information from the Application](../../../../visual-basic/developing-apps/programming/log-info/logging-information-from-the-application.md) diff --git a/docs/visual-basic/language-reference/data-types/boolean-data-type.md b/docs/visual-basic/language-reference/data-types/boolean-data-type.md index 2a4ed06e31add..6842a7d606b1c 100644 --- a/docs/visual-basic/language-reference/data-types/boolean-data-type.md +++ b/docs/visual-basic/language-reference/data-types/boolean-data-type.md @@ -62,7 +62,7 @@ Holds values that can be only `True` or `False`. The keywords `True` and `False` - **Type Characters.** `Boolean` has no literal type character or identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## Example In the following example, `runningVB` is a `Boolean` variable, which stores a simple yes/no setting. @@ -76,7 +76,7 @@ End If ``` ## See Also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Type Conversion Functions](../../../visual-basic/language-reference/functions/type-conversion-functions.md) [Conversion Summary](../../../visual-basic/language-reference/keywords/conversion-summary.md) diff --git a/docs/visual-basic/language-reference/data-types/byte-data-type.md b/docs/visual-basic/language-reference/data-types/byte-data-type.md index f09ae17a6d257..d69c3a08edab2 100644 --- a/docs/visual-basic/language-reference/data-types/byte-data-type.md +++ b/docs/visual-basic/language-reference/data-types/byte-data-type.md @@ -44,7 +44,7 @@ The default value of `Byte` is 0. ## Literal assignments -You can declare and initialize a `Byte` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integral literal is outside the range of a `Byte` (that is, if it is less than or greater than ), a compilation error occurs. +You can declare and initialize a `Byte` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integral literal is outside the range of a `Byte` (that is, if it is less than or greater than ), a compilation error occurs. In the following example, integers equal to 201 that are represented as decimal, hexadecimal, and binary literals are implicitly converted from [Integer](integer-data-type.md) to `byte` values. @@ -63,11 +63,11 @@ Starting with Visual Basic 2017, you can also use the underscore character, `_`, - **Format Conversions.** When Visual Basic reads or writes files, or when it calls DLLs, methods, and properties, it can automatically convert between data formats. Binary data stored in `Byte` variables and arrays is preserved during such format conversions. You should not use a `String` variable for binary data, because its contents can be corrupted during conversion between ANSI and Unicode formats. -- **Widening.** The `Byte` data type widens to `Short`, `UShort`, `Integer`, `UInteger`, `Long`, `ULong`, `Decimal`, `Single`, or `Double`. This means you can convert `Byte` to any of these types without encountering a error. +- **Widening.** The `Byte` data type widens to `Short`, `UShort`, `Integer`, `UInteger`, `Long`, `ULong`, `Decimal`, `Single`, or `Double`. This means you can convert `Byte` to any of these types without encountering a error. - **Type Characters.** `Byte` has no literal type character or identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## Example @@ -77,7 +77,7 @@ Starting with Visual Basic 2017, you can also use the underscore character, `_`, ## See Also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Type Conversion Functions](../../../visual-basic/language-reference/functions/type-conversion-functions.md) [Conversion Summary](../../../visual-basic/language-reference/keywords/conversion-summary.md) diff --git a/docs/visual-basic/language-reference/data-types/char-data-type.md b/docs/visual-basic/language-reference/data-types/char-data-type.md index 3ff2a9de2006e..8a857384fd280 100644 --- a/docs/visual-basic/language-reference/data-types/char-data-type.md +++ b/docs/visual-basic/language-reference/data-types/char-data-type.md @@ -73,14 +73,14 @@ charVar = "Z"C - **Interop Considerations.** If you interface with components not written for the .NET Framework, for example Automation or COM objects, remember that character types have a different data width (8 bits) in other environments. If you pass an 8-bit argument to such a component, declare it as `Byte` instead of `Char` in your new Visual Basic code. -- **Widening.** The `Char` data type widens to `String`. This means you can convert `Char` to `String` and will not encounter a error. +- **Widening.** The `Char` data type widens to `String`. This means you can convert `Char` to `String` and will not encounter a error. - **Type Characters.** Appending the literal type character `C` to a single-character string literal forces it to the `Char` data type. `Char` has no identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See Also - + diff --git a/docs/visual-basic/language-reference/data-types/date-data-type.md b/docs/visual-basic/language-reference/data-types/date-data-type.md index 7775a2eb612dd..004a61d74514d 100644 --- a/docs/visual-basic/language-reference/data-types/date-data-type.md +++ b/docs/visual-basic/language-reference/data-types/date-data-type.md @@ -83,11 +83,11 @@ Dim dateInMay As New System.DateTime(1993, 5, 31, 12, 14, 0) ## Programming Tips -- **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, for example Automation or COM objects, keep in mind that date/time types in other environments are not compatible with the Visual Basic `Date` type. If you are passing a date/time argument to such a component, declare it as `Double` instead of `Date` in your new Visual Basic code, and use the conversion methods and . +- **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, for example Automation or COM objects, keep in mind that date/time types in other environments are not compatible with the Visual Basic `Date` type. If you are passing a date/time argument to such a component, declare it as `Double` instead of `Date` in your new Visual Basic code, and use the conversion methods and . - **Type Characters.** `Date` has no literal type character or identifier type character. However, the compiler treats literals enclosed within number signs (`# #`) as `Date`. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## Example A variable or constant of the `Date` data type holds both the date and the time. The following example illustrates this. @@ -97,7 +97,7 @@ Dim someDateAndTime As Date = #8/13/2002 12:14 PM# ``` ## See Also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Standard Date and Time Format Strings](../../../standard/base-types/standard-date-and-time-format-strings.md) [Custom Date and Time Format Strings](../../../standard/base-types/custom-date-and-time-format-strings.md) diff --git a/docs/visual-basic/language-reference/data-types/decimal-data-type.md b/docs/visual-basic/language-reference/data-types/decimal-data-type.md index 424a2396f7bc2..29d858883cc23 100644 --- a/docs/visual-basic/language-reference/data-types/decimal-data-type.md +++ b/docs/visual-basic/language-reference/data-types/decimal-data-type.md @@ -63,7 +63,7 @@ Holds signed 128-bit (16-byte) values representing 96-bit (12-byte) integer numb - **Performance.** The `Decimal` data type is the slowest of all the numeric types. You should weigh the importance of precision against performance before choosing a data type. -- **Widening.** The `Decimal` data type widens to `Single` or `Double`. This means you can convert `Decimal` to either of these types without encountering a error. +- **Widening.** The `Decimal` data type widens to `Single` or `Double`. This means you can convert `Decimal` to either of these types without encountering a error. - **Trailing Zeros.** Visual Basic does not store trailing zeros in a `Decimal` literal. However, a `Decimal` variable preserves any trailing zeros acquired computationally. The following example illustrates this. @@ -83,7 +83,7 @@ Holds signed 128-bit (16-byte) values representing 96-bit (12-byte) integer numb - **Type Characters.** Appending the literal type character `D` to a literal forces it to the `Decimal` data type. Appending the identifier type character `@` to any identifier forces it to `Decimal`. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## Range You might need to use the `D` type character to assign a large value to a `Decimal` variable or constant. This requirement is because the compiler interprets a literal as `Long` unless a literal type character follows the literal, as the following example shows. @@ -101,9 +101,9 @@ Dim bigDec3 As Decimal = 9223372036854775808D ' No overflow. For `bigDec3`, the literal type character `D` solves the problem by forcing the compiler to interpret the literal as a `Decimal` instead of as a `Long`. ## See Also - - - + + + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Single Data Type](../../../visual-basic/language-reference/data-types/single-data-type.md) [Double Data Type](../../../visual-basic/language-reference/data-types/double-data-type.md) diff --git a/docs/visual-basic/language-reference/data-types/double-data-type.md b/docs/visual-basic/language-reference/data-types/double-data-type.md index 6ee399e0f0411..0579040437bbb 100644 --- a/docs/visual-basic/language-reference/data-types/double-data-type.md +++ b/docs/visual-basic/language-reference/data-types/double-data-type.md @@ -75,10 +75,10 @@ Holds signed IEEE 64-bit (8-byte) double-precision floating-point numbers that r Dim num# = 3 ``` -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See Also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Decimal Data Type](../../../visual-basic/language-reference/data-types/decimal-data-type.md) [Single Data Type](../../../visual-basic/language-reference/data-types/single-data-type.md) diff --git a/docs/visual-basic/language-reference/data-types/integer-data-type.md b/docs/visual-basic/language-reference/data-types/integer-data-type.md index 4bb1d6b294a8e..39f77c6e88a93 100644 --- a/docs/visual-basic/language-reference/data-types/integer-data-type.md +++ b/docs/visual-basic/language-reference/data-types/integer-data-type.md @@ -59,7 +59,7 @@ Holds signed 32-bit (4-byte) integers that range in value from -2,147,483,648 th ## Literal assignments -You can declare and initialize an `Integer` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `Integer` (that is, if it is less than or greater than , a compilation error occurs. +You can declare and initialize an `Integer` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `Integer` (that is, if it is less than or greater than , a compilation error occurs. In the following example, integers equal to 16,342 that are represented as decimal, hexadecimal, and binary literals are assigned to `Integer` values. @@ -82,11 +82,11 @@ Dim number = &H035826I - **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, such as Automation or COM objects, remember that `Integer` has a different data width (16 bits) in other environments. If you are passing a 16-bit argument to such a component, declare it as `Short` instead of `Integer` in your new Visual Basic code. -- **Widening.** The `Integer` data type widens to `Long`, `Decimal`, `Single`, or `Double`. This means you can convert `Integer` to any one of these types without encountering a error. +- **Widening.** The `Integer` data type widens to `Long`, `Decimal`, `Single`, or `Double`. This means you can convert `Integer` to any one of these types without encountering a error. - **Type Characters.** Appending the literal type character `I` to a literal forces it to the `Integer` data type. Appending the identifier type character `%` to any identifier forces it to `Integer`. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## Range @@ -108,7 +108,7 @@ k = 5.5 ## See also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Long Data Type](../../../visual-basic/language-reference/data-types/long-data-type.md) [Short Data Type](../../../visual-basic/language-reference/data-types/short-data-type.md) diff --git a/docs/visual-basic/language-reference/data-types/long-data-type.md b/docs/visual-basic/language-reference/data-types/long-data-type.md index 379c9fae3ce00..290298173a936 100644 --- a/docs/visual-basic/language-reference/data-types/long-data-type.md +++ b/docs/visual-basic/language-reference/data-types/long-data-type.md @@ -60,7 +60,7 @@ Holds signed 64-bit (8-byte) integers ranging in value from -9,223,372,036,854,7 ## Literal assignments -You can declare and initialize a `Long` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `Long` (that is, if it is less than or greater than , a compilation error occurs. +You can declare and initialize a `Long` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `Long` (that is, if it is less than or greater than , a compilation error occurs. In the following example, integers equal to 4,294,967,296 that are represented as decimal, hexadecimal, and binary literals are assigned to `Long` values. @@ -83,11 +83,11 @@ Dim number = &H0FAC0326L - **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, for example Automation or COM objects, remember that `Long` has a different data width (32 bits) in other environments. If you are passing a 32-bit argument to such a component, declare it as `Integer` instead of `Long` in your new Visual Basic code. -- **Widening.** The `Long` data type widens to `Decimal`, `Single`, or `Double`. This means you can convert `Long` to any one of these types without encountering a error. +- **Widening.** The `Long` data type widens to `Decimal`, `Single`, or `Double`. This means you can convert `Long` to any one of these types without encountering a error. - **Type Characters.** Appending the literal type character `L` to a literal forces it to the `Long` data type. Appending the identifier type character `&` to any identifier forces it to `Long`. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See also diff --git a/docs/visual-basic/language-reference/data-types/object-data-type.md b/docs/visual-basic/language-reference/data-types/object-data-type.md index 565420ce4027c..2a570fd2cec8d 100644 --- a/docs/visual-basic/language-reference/data-types/object-data-type.md +++ b/docs/visual-basic/language-reference/data-types/object-data-type.md @@ -48,7 +48,7 @@ Holds addresses that refer to objects. You can assign any reference type (string The default value of `Object` is `Nothing` (a null reference). ## Data Types - You can assign a variable, constant, or expression of any data type to an `Object` variable. To determine the data type an `Object` variable currently refers to, you can use the method of the class. The following example illustrates this. + You can assign a variable, constant, or expression of any data type to an `Object` variable. To determine the data type an `Object` variable currently refers to, you can use the method of the class. The following example illustrates this. ``` Dim myObject As Object @@ -70,13 +70,13 @@ datTyp = Type.GetTypeCode(myObject.GetType()) When you declare an object variable, try to use a specific class type, for example , instead of the generalized `Object` type. You should also use the most specific class available, such as instead of , so that you can access its properties and methods. You can usually use the **Classes** list in the **Object Browser** to find available class names. -- **Widening.** All data types and all reference types widen to the `Object` data type. This means you can convert any type to `Object` without encountering a error. +- **Widening.** All data types and all reference types widen to the `Object` data type. This means you can convert any type to `Object` without encountering a error. However, if you convert between value types and `Object`, Visual Basic performs operations called *boxing* and *unboxing*, which make execution slower. - **Type Characters.** `Object` has no literal type character or identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the class. +- **Framework Type.** The corresponding type in the .NET Framework is the class. ## Example The following example illustrates an `Object` variable pointing to an object instance. diff --git a/docs/visual-basic/language-reference/data-types/sbyte-data-type.md b/docs/visual-basic/language-reference/data-types/sbyte-data-type.md index 2e5e641679564..448df5abca561 100644 --- a/docs/visual-basic/language-reference/data-types/sbyte-data-type.md +++ b/docs/visual-basic/language-reference/data-types/sbyte-data-type.md @@ -68,7 +68,7 @@ Starting with Visual Basic 2017, you can also use the underscore character, `_`, [!code-vb[SByteSeparator](../../../../samples/snippets/visualbasic/language-reference/data-types/numeric-literals.vb#SByteS)] -If the integer literal is outside the range of `SByte` (that is, if it is less than or greater than , a compilation error occurs. When an integer literal has no suffix, an [Integer](integer-data-type.md) is inferred. If the integer literal is outside the range of the `Integer` type, a [Long](long-data-type.md) is inferred. This means that, in the previous examples, the numeric literals `0x9A` and `0b10011010` are interpreted as 32-bit signed integers with a value of 156, which exceeds . To successfully compile code like this that assigns a non-decimal integer to an `SByte`, you can do either of the following: +If the integer literal is outside the range of `SByte` (that is, if it is less than or greater than , a compilation error occurs. When an integer literal has no suffix, an [Integer](integer-data-type.md) is inferred. If the integer literal is outside the range of the `Integer` type, a [Long](long-data-type.md) is inferred. This means that, in the previous examples, the numeric literals `0x9A` and `0b10011010` are interpreted as 32-bit signed integers with a value of 156, which exceeds . To successfully compile code like this that assigns a non-decimal integer to an `SByte`, you can do either of the following: - Disable integer bounds checks by compiling with the `/removeintchecks` compiler switch. @@ -80,15 +80,15 @@ If the integer literal is outside the range of `SByte` (that is, if it is less t - **CLS Compliance.** The `SByte` data type is not part of the [Common Language Specification](http://www.ecma-international.org/publications/standards/Ecma-335.htm) (CLS), so CLS-compliant code cannot consume a component that uses it. -- **Widening.** The `SByte` data type widens to `Short`, `Integer`, `Long`, `Decimal`, `Single`, and `Double`. This means you can convert `SByte` to any of these types without encountering a error. +- **Widening.** The `SByte` data type widens to `Short`, `Integer`, `Long`, `Decimal`, `Single`, and `Double`. This means you can convert `SByte` to any of these types without encountering a error. - **Type Characters.** `SByte` has no literal type character or identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Type Conversion Functions](../../../visual-basic/language-reference/functions/type-conversion-functions.md) [Conversion Summary](../../../visual-basic/language-reference/keywords/conversion-summary.md) diff --git a/docs/visual-basic/language-reference/data-types/short-data-type.md b/docs/visual-basic/language-reference/data-types/short-data-type.md index 82c441ac62182..fff4ba0722639 100644 --- a/docs/visual-basic/language-reference/data-types/short-data-type.md +++ b/docs/visual-basic/language-reference/data-types/short-data-type.md @@ -56,7 +56,7 @@ Holds signed 16-bit (2-byte) integers that range in value from -32,768 through 3 ## Literal assignments -You can declare and initialize a `Short` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `Short` (that is, if it is less than or greater than , a compilation error occurs. +You can declare and initialize a `Short` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `Short` (that is, if it is less than or greater than , a compilation error occurs. In the following example, integers equal to 1,034 that are represented as decimal, hexadecimal, and binary literals are implicitly converted from [Integer](integer-data-type.md) to `Short` values. @@ -77,15 +77,15 @@ Dim number = &H0326S ## Programming tips -- **Widening.** The `Short` data type widens to `Integer`, `Long`, `Decimal`, `Single`, or `Double`. This means you can convert `Short` to any one of these types without encountering a error. +- **Widening.** The `Short` data type widens to `Integer`, `Long`, `Decimal`, `Single`, or `Double`. This means you can convert `Short` to any one of these types without encountering a error. - **Type Characters.** Appending the literal type character `S` to a literal forces it to the `Short` data type. `Short` has no identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Type Conversion Functions](../../../visual-basic/language-reference/functions/type-conversion-functions.md) [Conversion Summary](../../../visual-basic/language-reference/keywords/conversion-summary.md) diff --git a/docs/visual-basic/language-reference/data-types/single-data-type.md b/docs/visual-basic/language-reference/data-types/single-data-type.md index 216a501a70033..5ae9d654b5157 100644 --- a/docs/visual-basic/language-reference/data-types/single-data-type.md +++ b/docs/visual-basic/language-reference/data-types/single-data-type.md @@ -61,16 +61,16 @@ Holds signed IEEE 32-bit (4-byte) single-precision floating-point numbers rangin - **Precision.** When you work with floating-point numbers, keep in mind that they do not always have a precise representation in memory. This could lead to unexpected results from certain operations, such as value comparison and the `Mod` operator. For more information, see [Troubleshooting Data Types](../../../visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md). -- **Widening.** The `Single` data type widens to `Double`. This means you can convert `Single` to `Double` without encountering a error. +- **Widening.** The `Single` data type widens to `Double`. This means you can convert `Single` to `Double` without encountering a error. - **Trailing Zeros.** The floating-point data types do not have any internal representation of trailing 0 characters. For example, they do not distinguish between 4.2000 and 4.2. Consequently, trailing 0 characters do not appear when you display or print floating-point values. - **Type Characters.** Appending the literal type character `F` to a literal forces it to the `Single` data type. Appending the identifier type character `!` to any identifier forces it to `Single`. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See Also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Decimal Data Type](../../../visual-basic/language-reference/data-types/decimal-data-type.md) [Double Data Type](../../../visual-basic/language-reference/data-types/double-data-type.md) diff --git a/docs/visual-basic/language-reference/data-types/string-data-type.md b/docs/visual-basic/language-reference/data-types/string-data-type.md index 8aec1da08b964..890f26b91fd88 100644 --- a/docs/visual-basic/language-reference/data-types/string-data-type.md +++ b/docs/visual-basic/language-reference/data-types/string-data-type.md @@ -98,10 +98,10 @@ S = Microsoft.VisualBasic.Left(S, 4) - **Type Characters.** Appending the identifier type character `$` to any identifier forces it to the `String` data type. `String` has no literal type character. However, the compiler treats literals enclosed in quotation marks (`" "`) as `String`. -- **Framework Type.** The corresponding type in the .NET Framework is the class. +- **Framework Type.** The corresponding type in the .NET Framework is the class. ## See Also - + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Char Data Type](../../../visual-basic/language-reference/data-types/char-data-type.md) [Type Conversion Functions](../../../visual-basic/language-reference/functions/type-conversion-functions.md) diff --git a/docs/visual-basic/language-reference/data-types/uinteger-data-type.md b/docs/visual-basic/language-reference/data-types/uinteger-data-type.md index 5aac221cc37a6..5bde6c9cb7d88 100644 --- a/docs/visual-basic/language-reference/data-types/uinteger-data-type.md +++ b/docs/visual-basic/language-reference/data-types/uinteger-data-type.md @@ -57,7 +57,7 @@ Holds unsigned 32-bit (4-byte) integers ranging in value from 0 through 4,294,96 ## Literal assignments -You can declare and initialize a `UInteger` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `UInteger` (that is, if it is less than or greater than , a compilation error occurs. +You can declare and initialize a `UInteger` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `UInteger` (that is, if it is less than or greater than , a compilation error occurs. In the following example, integers equal to 3,000,000,000 that are represented as decimal, hexadecimal, and binary literals are assigned to `UInteger` values. @@ -86,11 +86,11 @@ Dim number = &H0FAC14D7ui - **Interop Considerations.** If you are interfacing with components not written for the .NET Framework, for example Automation or COM objects, keep in mind that types such as `uint` can have a different data width (16 bits) in other environments. If you are passing a 16-bit argument to such a component, declare it as `UShort` instead of `UInteger` in your managed Visual Basic code. -- **Widening.** The `UInteger` data type widens to `Long`, `ULong`, `Decimal`, `Single`, and `Double`. This means you can convert `UInteger` to any of these types without encountering a error. +- **Widening.** The `UInteger` data type widens to `Long`, `ULong`, `Decimal`, `Single`, and `Double`. This means you can convert `UInteger` to any of these types without encountering a error. - **Type Characters.** Appending the literal type characters `UI` to a literal forces it to the `UInteger` data type. `UInteger` has no identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See Also diff --git a/docs/visual-basic/language-reference/data-types/ulong-data-type.md b/docs/visual-basic/language-reference/data-types/ulong-data-type.md index 453c6bbde628d..507a5e5144ce6 100644 --- a/docs/visual-basic/language-reference/data-types/ulong-data-type.md +++ b/docs/visual-basic/language-reference/data-types/ulong-data-type.md @@ -57,7 +57,7 @@ The default value of `ULong` is 0. ## Literal assignments -You can declare and initialize a `ULong` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `ULong` (that is, if it is less than or greater than , a compilation error occurs. +You can declare and initialize a `ULong` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `ULong` (that is, if it is less than or greater than , a compilation error occurs. In the following example, integers equal to 7,934,076,125 that are represented as decimal, hexadecimal, and binary literals are assigned to `ULong` values. @@ -86,11 +86,11 @@ Dim number = &H00_00_0A_96_2F_AC_14_D7ul Furthermore, Automation does not support 64-bit integers on Windows 95, Windows 98, Windows ME, or Windows 2000. You cannot pass a Visual Basic `ULong` argument to an Automation component on these platforms. -- **Widening.** The `ULong` data type widens to `Decimal`, `Single`, and `Double`. This means you can convert `ULong` to any of these types without encountering a error. +- **Widening.** The `ULong` data type widens to `Decimal`, `Single`, and `Double`. This means you can convert `ULong` to any of these types without encountering a error. - **Type Characters.** Appending the literal type characters `UL` to a literal forces it to the `ULong` data type. `ULong` has no identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See also diff --git a/docs/visual-basic/language-reference/data-types/user-defined-data-type.md b/docs/visual-basic/language-reference/data-types/user-defined-data-type.md index cc81a4b5ede87..73dfdc29bad8b 100644 --- a/docs/visual-basic/language-reference/data-types/user-defined-data-type.md +++ b/docs/visual-basic/language-reference/data-types/user-defined-data-type.md @@ -80,7 +80,7 @@ Holds data in a format you define. The `Structure` statement defines the format. - **Type Characters.** Structure data types have no literal type character or identifier type character. -- **Framework Type.** There is no corresponding type in the .NET Framework. All structures inherit from the .NET Framework class , but no individual structure corresponds to . +- **Framework Type.** There is no corresponding type in the .NET Framework. All structures inherit from the .NET Framework class , but no individual structure corresponds to . ## Example The following paradigm shows the outline of the declaration of a structure. diff --git a/docs/visual-basic/language-reference/data-types/ushort-data-type.md b/docs/visual-basic/language-reference/data-types/ushort-data-type.md index 6472a8ed84e32..1b083062e0521 100644 --- a/docs/visual-basic/language-reference/data-types/ushort-data-type.md +++ b/docs/visual-basic/language-reference/data-types/ushort-data-type.md @@ -57,7 +57,7 @@ Holds unsigned 16-bit (2-byte) integers ranging in value from 0 through 65,535. # Literal assignments -You can declare and initialize a `UShort` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `UShort` (that is, if it is less than or greater than , a compilation error occurs. +You can declare and initialize a `UShort` variable by assigning it a decimal literal, a hexadecimal literal, an octal literal, or (starting with Visual Basic 2017) a binary literal. If the integer literal is outside the range of `UShort` (that is, if it is less than or greater than , a compilation error occurs. In the following example, integers equal to 65,034 that are represented as decimal, hexadecimal, and binary literals are assigned to `UShort` values. @@ -82,11 +82,11 @@ Dim number = &H035826us - **CLS Compliance.** The `UShort` data type is not part of the [Common Language Specification](http://www.ecma-international.org/publications/standards/Ecma-335.htm) (CLS), so CLS-compliant code cannot consume a component that uses it. -- **Widening.** The `UShort` data type widens to `Integer`, `UInteger`, `Long`, `ULong`, `Decimal`, `Single`, and `Double`. This means you can convert `UShort` to any of these types without encountering a error. +- **Widening.** The `UShort` data type widens to `Integer`, `UInteger`, `Long`, `ULong`, `Decimal`, `Single`, and `Double`. This means you can convert `UShort` to any of these types without encountering a error. - **Type Characters.** Appending the literal type characters `US` to a literal forces it to the `UShort` data type. `UShort` has no identifier type character. -- **Framework Type.** The corresponding type in the .NET Framework is the structure. +- **Framework Type.** The corresponding type in the .NET Framework is the structure. ## See Also diff --git a/docs/visual-basic/language-reference/error-messages/extension-attribute-can-be-applied-only-to-module-sub-or-function-declarations.md b/docs/visual-basic/language-reference/error-messages/extension-attribute-can-be-applied-only-to-module-sub-or-function-declarations.md index f02f818aa9587..848b898e4ff23 100644 --- a/docs/visual-basic/language-reference/error-messages/extension-attribute-can-be-applied-only-to-module-sub-or-function-declarations.md +++ b/docs/visual-basic/language-reference/error-messages/extension-attribute-can-be-applied-only-to-module-sub-or-function-declarations.md @@ -37,7 +37,7 @@ translation.priority.ht: - "zh-tw" --- # 'Extension' attribute can be applied only to 'Module', 'Sub', or 'Function' declarations -The only way to extend a data type in Visual Basic is to define an extension method inside a standard module. The extension method can be a `Sub` procedure or a `Function` procedure. All extension methods must be marked with the extension attribute, ``, from the namespace. Optionally, a module that contains an extension method may be marked in the same way. No other use of the extension attribute is valid. +The only way to extend a data type in Visual Basic is to define an extension method inside a standard module. The extension method can be a `Sub` procedure or a `Function` procedure. All extension methods must be marked with the extension attribute, ``, from the namespace. Optionally, a module that contains an extension method may be marked in the same way. No other use of the extension attribute is valid. **Error ID:** BC36550 diff --git a/docs/visual-basic/language-reference/error-messages/for-each-on-type-typename-is-ambiguous.md b/docs/visual-basic/language-reference/error-messages/for-each-on-type-typename-is-ambiguous.md index 882c696112aed..26cec7c6d401d 100644 --- a/docs/visual-basic/language-reference/error-messages/for-each-on-type-typename-is-ambiguous.md +++ b/docs/visual-basic/language-reference/error-messages/for-each-on-type-typename-is-ambiguous.md @@ -39,7 +39,7 @@ translation.priority.ht: # 'For Each' on type '<typename>' is ambiguous because the type implements multiple instantiations of 'System.Collections.Generic.IEnumerable(Of T)' A `For Each` statement specifies an iterator variable that has more than one method. - The iterator variable must be of a type that implements the or interface in one of the `Collections` namespaces of the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)]. It is possible for a class to implement more than one constructed generic interface, using a different type argument for each construction. If a class that does this is used for the iterator variable, that variable has more than one method. In such a case, [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] cannot choose which method to call. + The iterator variable must be of a type that implements the or interface in one of the `Collections` namespaces of the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)]. It is possible for a class to implement more than one constructed generic interface, using a different type argument for each construction. If a class that does this is used for the iterator variable, that variable has more than one method. In such a case, [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] cannot choose which method to call. **Error ID:** BC32096 diff --git a/docs/visual-basic/language-reference/error-messages/late-bound-resolution;-runtime-errors-could-occur.md b/docs/visual-basic/language-reference/error-messages/late-bound-resolution;-runtime-errors-could-occur.md index d5c968847e0b4..febd717c5dcc3 100644 --- a/docs/visual-basic/language-reference/error-messages/late-bound-resolution;-runtime-errors-could-occur.md +++ b/docs/visual-basic/language-reference/error-messages/late-bound-resolution;-runtime-errors-could-occur.md @@ -39,7 +39,7 @@ translation.priority.ht: # Late bound resolution; runtime errors could occur An object is assigned to a variable declared to be of the [Object Data Type](../../../visual-basic/language-reference/data-types/object-data-type.md). - When you declare a variable as `Object`, the compiler must perform *late binding*, which causes extra operations at run time. It also exposes your application to potential run-time errors. For example, if you assign a to the `Object` variable and then try to access the property, the runtime throws a because the class does not expose a `NameTable` property. + When you declare a variable as `Object`, the compiler must perform *late binding*, which causes extra operations at run time. It also exposes your application to potential run-time errors. For example, if you assign a to the `Object` variable and then try to access the property, the runtime throws a because the class does not expose a `NameTable` property. If you declare the variable to be of a specific type, the compiler can perform *early binding* at compile time. This results in improved performance, controlled access to the members of the specific type, and better readability of your code. diff --git a/docs/visual-basic/language-reference/error-messages/overflow-visual-basic-run-time-error.md b/docs/visual-basic/language-reference/error-messages/overflow-visual-basic-run-time-error.md index 2882420662b6a..fa785e3eedeb3 100644 --- a/docs/visual-basic/language-reference/error-messages/overflow-visual-basic-run-time-error.md +++ b/docs/visual-basic/language-reference/error-messages/overflow-visual-basic-run-time-error.md @@ -45,7 +45,7 @@ An overflow results when you attempt an assignment that exceeds the limits of th 3. Make sure that numbers used in calculations that are coerced into integers do not have results larger than integers. ## See Also - - + + [Data Types](../../../visual-basic/language-reference/data-types/data-type-summary.md) [Error Types](../../../visual-basic/programming-guide/language-features/error-types.md) diff --git a/docs/visual-basic/language-reference/error-messages/some-subkeys-cannot-be-deleted.md b/docs/visual-basic/language-reference/error-messages/some-subkeys-cannot-be-deleted.md index 09433989cc13d..7fc9a235310aa 100644 --- a/docs/visual-basic/language-reference/error-messages/some-subkeys-cannot-be-deleted.md +++ b/docs/visual-basic/language-reference/error-messages/some-subkeys-cannot-be-deleted.md @@ -39,7 +39,7 @@ An attempt has been made to delete a registry key, but the operation failed beca - Make sure you have sufficient permissions to delete the specified subkeys. ## See Also - + diff --git a/docs/visual-basic/language-reference/error-messages/subscript-out-of-range.md b/docs/visual-basic/language-reference/error-messages/subscript-out-of-range.md index 5c4fb02961e92..300e0a52c8c08 100644 --- a/docs/visual-basic/language-reference/error-messages/subscript-out-of-range.md +++ b/docs/visual-basic/language-reference/error-messages/subscript-out-of-range.md @@ -41,5 +41,5 @@ An array subscript is not valid because it falls outside the allowable range. Th - Change the subscript so it falls within the valid range. ## See Also - + [Arrays](../../../visual-basic/programming-guide/language-features/arrays/index.md) diff --git a/docs/visual-basic/language-reference/error-messages/type-typename-is-not-defined.md b/docs/visual-basic/language-reference/error-messages/type-typename-is-not-defined.md index 034a39b487b1b..3fd0ab47b8884 100644 --- a/docs/visual-basic/language-reference/error-messages/type-typename-is-not-defined.md +++ b/docs/visual-basic/language-reference/error-messages/type-typename-is-not-defined.md @@ -47,7 +47,7 @@ The statement has made reference to a type that has not been defined. You can de - Ensure that the type definition is accessible to the reference. For example, if the type is in another module and has been declared `Private`, move the type definition to the referencing module or declare it `Public`. -- Ensure that the namespace of the type is not redefined within your project. If it is, use the `Global` keyword to fully qualify the type name. For example, if a project defines a namespace named `System`, the type cannot be accessed unless it is fully qualified with the `Global` keyword: `Global.System.Object`. +- Ensure that the namespace of the type is not redefined within your project. If it is, use the `Global` keyword to fully qualify the type name. For example, if a project defines a namespace named `System`, the type cannot be accessed unless it is fully qualified with the `Global` keyword: `Global.System.Object`. - If the type is defined, but the object library or type library in which it is defined is not registered in [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)], click **Add Reference** on the **Project** menu, and then select the appropriate object library or type library. diff --git a/docs/visual-basic/language-reference/functions/math-functions.md b/docs/visual-basic/language-reference/functions/math-functions.md index 09f6796299459..1bb2c3842f2c9 100644 --- a/docs/visual-basic/language-reference/functions/math-functions.md +++ b/docs/visual-basic/language-reference/functions/math-functions.md @@ -38,10 +38,10 @@ translation.priority.mt: - "tr-tr" --- # Math Functions (Visual Basic) -The methods of the class provide trigonometric, logarithmic, and other common mathematical functions. +The methods of the class provide trigonometric, logarithmic, and other common mathematical functions. ## Remarks - The following table lists methods of the class. You can use these in a Visual Basic program. + The following table lists methods of the class. You can use these in a Visual Basic program. |.NET Framework method|Description| |---------------------------|-----------------| @@ -72,7 +72,7 @@ The methods of the class provide tri ||Returns the hyperbolic tangent of the specified angle.| ||Calculates the integral part of a specified `Decimal` or `Double` number.| - To use these functions without qualification, import the namespace into your project by adding the following code to the top of your source file: + To use these functions without qualification, import the namespace into your project by adding the following code to the top of your source file: ``` Imports System.Math diff --git a/docs/visual-basic/language-reference/functions/return-values-for-the-cstr-function.md b/docs/visual-basic/language-reference/functions/return-values-for-the-cstr-function.md index f9dbe8027bef9..eaf46c2813c53 100644 --- a/docs/visual-basic/language-reference/functions/return-values-for-the-cstr-function.md +++ b/docs/visual-basic/language-reference/functions/return-values-for-the-cstr-function.md @@ -53,7 +53,7 @@ The following table describes the return values for `CStr` for different data ty The `Date` type always contains both date and time information. For purposes of type conversion, Visual Basic considers 1/1/0001 (January 1 of the year 1) to be a *neutral value* for the date, and 00:00:00 (midnight) to be a neutral value for the time. `CStr` does not include neutral values in the resulting string. For example, if you convert `#January 1, 0001 9:30:00#` to a string, the result is "9:30:00 AM"; the date information is suppressed. However, the date information is still present in the original `Date` value and can be recovered with functions such as . > [!NOTE] -> The `CStr` function performs its conversion based on the current culture settings for the application. To get the string representation of a number in a particular culture, use the number's `ToString(IFormatProvider)` method. For example, use when converting a value of type `Double` to a `String`. +> The `CStr` function performs its conversion based on the current culture settings for the application. To get the string representation of a number in a particular culture, use the number's `ToString(IFormatProvider)` method. For example, use when converting a value of type `Double` to a `String`. ## See Also diff --git a/docs/visual-basic/language-reference/functions/type-conversion-functions.md b/docs/visual-basic/language-reference/functions/type-conversion-functions.md index 1f77d499ec76f..45035eb99c29b 100644 --- a/docs/visual-basic/language-reference/functions/type-conversion-functions.md +++ b/docs/visual-basic/language-reference/functions/type-conversion-functions.md @@ -177,13 +177,13 @@ CUShort(expression) `CInt` and `CLng` differ from the and functions, which truncate, rather than round, the fractional part of a number. Also, `Fix` and `Int` always return a value of the same data type as you pass in. -- **Date/Time Conversions.** Use the function to determine if a value can be converted to a date and time. `CDate` recognizes date literals and time literals but not numeric values. To convert a Visual Basic 6.0 `Date` value to a `Date` value in Visual Basic 2005 or later versions, you can use the method. +- **Date/Time Conversions.** Use the function to determine if a value can be converted to a date and time. `CDate` recognizes date literals and time literals but not numeric values. To convert a Visual Basic 6.0 `Date` value to a `Date` value in Visual Basic 2005 or later versions, you can use the method. - **Neutral Date/Time Values.** The [Date Data Type](../../../visual-basic/language-reference/data-types/date-data-type.md) always contains both date and time information. For purposes of type conversion, Visual Basic considers 1/1/0001 (January 1 of the year 1) to be a *neutral value* for the date, and 00:00:00 (midnight) to be a neutral value for the time. If you convert a `Date` value to a string, `CStr` does not include neutral values in the resulting string. For example, if you convert `#January 1, 0001 9:30:00#` to a string, the result is "9:30:00 AM"; the date information is suppressed. However, the date information is still present in the original `Date` value and can be recovered with functions such as function. - **Culture Sensitivity.** The type conversion functions involving strings perform conversions based on the current culture settings for the application. For example, `CDate` recognizes date formats according to the locale setting of your system. You must provide the day, month, and year in the correct order for your locale, or the date might not be interpreted correctly. A long date format is not recognized if it contains a day-of-the-week string, such as "Wednesday". - If you need to convert to or from a string representation of a value in a format other than the one specified by your locale, you cannot use the Visual Basic type conversion functions. To do this, use the `ToString(IFormatProvider)` and `Parse(String, IFormatProvider)` methods of that value's type. For example, use when converting a string to a `Double`, and use when converting a value of type `Double` to a string. + If you need to convert to or from a string representation of a value in a format other than the one specified by your locale, you cannot use the Visual Basic type conversion functions. To do this, use the `ToString(IFormatProvider)` and `Parse(String, IFormatProvider)` methods of that value's type. For example, use when converting a string to a `Double`, and use when converting a value of type `Double` to a string. ## CType Function The [CType Function](../../../visual-basic/language-reference/functions/ctype-function.md) takes a second argument, `typename`, and coerces `expression` to `typename`, where `typename` can be any data type, structure, class, or interface to which there exists a valid conversion. diff --git a/docs/visual-basic/language-reference/index.md b/docs/visual-basic/language-reference/index.md index 070b0198faf5f..311d369df9417 100644 --- a/docs/visual-basic/language-reference/index.md +++ b/docs/visual-basic/language-reference/index.md @@ -47,7 +47,7 @@ This section provides reference information for various aspects of the [!INCLUDE Summarizes the way that keywords, placeholders, and other elements of the language are formatted in the [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] documentation. [Visual Basic Runtime Library Members](../../visual-basic/language-reference/runtime-library-members.md) - Lists the classes and modules of the namespace, with links to their member functions, methods, properties, constants, and enumerations. + Lists the classes and modules of the namespace, with links to their member functions, methods, properties, constants, and enumerations. [Keywords](../../visual-basic/language-reference/keywords/index.md) Lists all Visual Basic keywords and provides links to more information. diff --git a/docs/visual-basic/language-reference/keywords/derived-math-functions.md b/docs/visual-basic/language-reference/keywords/derived-math-functions.md index d81c1a278598f..2804b6a0bb344 100644 --- a/docs/visual-basic/language-reference/keywords/derived-math-functions.md +++ b/docs/visual-basic/language-reference/keywords/derived-math-functions.md @@ -51,7 +51,7 @@ translation.priority.ht: - "zh-tw" --- # Derived Math Functions (Visual Basic) -The following table shows non-intrinsic math functions that can be derived from the intrinsic math functions of the object. You can access the intrinsic math functions by adding `Imports System.Math` to your file or project. +The following table shows non-intrinsic math functions that can be derived from the intrinsic math functions of the object. You can access the intrinsic math functions by adding `Imports System.Math` to your file or project. |Function|Derived equivalents| |--------------|-------------------------| diff --git a/docs/visual-basic/language-reference/objects/my-application-info-object.md b/docs/visual-basic/language-reference/objects/my-application-info-object.md index 772ba198085ba..1fca9b2e31393 100644 --- a/docs/visual-basic/language-reference/objects/my-application-info-object.md +++ b/docs/visual-basic/language-reference/objects/my-application-info-object.md @@ -41,7 +41,7 @@ Provides properties for getting the information about the application, such as t For information about the methods and properties of the `My.Application.Info` object, see . > [!NOTE] -> You can use properties of the class to obtain information about a file on disk. +> You can use properties of the class to obtain information about a file on disk. ## Requirements **Namespace:** diff --git a/docs/visual-basic/language-reference/objects/my-computer-clipboard-object.md b/docs/visual-basic/language-reference/objects/my-computer-clipboard-object.md index 0b954c20c0686..8b54eb9cbdb23 100644 --- a/docs/visual-basic/language-reference/objects/my-computer-clipboard-object.md +++ b/docs/visual-basic/language-reference/objects/my-computer-clipboard-object.md @@ -43,7 +43,7 @@ Provides methods for manipulating the Clipboard. For more information, see [Storing Data to and Reading from the Clipboard](../../../visual-basic/developing-apps/programming/computer-resources/storing-data-to-and-reading-from-the-clipboard.md). > [!NOTE] -> You can also use methods of the class to manipulate the Clipboard. +> You can also use methods of the class to manipulate the Clipboard. ## Requirements **Namespace:** diff --git a/docs/visual-basic/language-reference/objects/my-computer-filesystem-object.md b/docs/visual-basic/language-reference/objects/my-computer-filesystem-object.md index 4c0bd293d0b4e..e7bcfa11f1ba3 100644 --- a/docs/visual-basic/language-reference/objects/my-computer-filesystem-object.md +++ b/docs/visual-basic/language-reference/objects/my-computer-filesystem-object.md @@ -50,7 +50,7 @@ Provides properties and methods for working with drives, files, and directories. For more information, see [File Access with Visual Basic](../../../visual-basic/developing-apps/programming/drives-directories-files/file-access.md). > [!NOTE] -> You can also use classes in the namespace to work with drives, files, and directories. +> You can also use classes in the namespace to work with drives, files, and directories. ## Requirements **Namespace:** diff --git a/docs/visual-basic/language-reference/objects/my-computer-network-object.md b/docs/visual-basic/language-reference/objects/my-computer-network-object.md index ddacb12440bcc..25f726698d494 100644 --- a/docs/visual-basic/language-reference/objects/my-computer-network-object.md +++ b/docs/visual-basic/language-reference/objects/my-computer-network-object.md @@ -42,7 +42,7 @@ Provides a property, event, and methods for interacting with the network to whic For more information, see [Performing Network Operations](../../../visual-basic/developing-apps/programming/computer-resources/performing-network-operations.md). ## Requirements - **Namespace:** + **Namespace:** **Class:** diff --git a/docs/visual-basic/language-reference/objects/my-computer-ports-object.md b/docs/visual-basic/language-reference/objects/my-computer-ports-object.md index 0abe4ca18ceb8..1277d07de47c1 100644 --- a/docs/visual-basic/language-reference/objects/my-computer-ports-object.md +++ b/docs/visual-basic/language-reference/objects/my-computer-ports-object.md @@ -43,7 +43,7 @@ Provides a property and a method for accessing the computer's serial ports. For more information, see [Accessing the Computer's Ports](../../../visual-basic/developing-apps/programming/computer-resources/accessing-the-computer-s-ports.md). > [!NOTE] -> You can also use properties and methods of the class to access the computer's serial ports. +> You can also use properties and methods of the class to access the computer's serial ports. ## Requirements **Namespace:** diff --git a/docs/visual-basic/language-reference/objects/my-computer-registry-object.md b/docs/visual-basic/language-reference/objects/my-computer-registry-object.md index 9200dbf81c027..e313bf14f2ce2 100644 --- a/docs/visual-basic/language-reference/objects/my-computer-registry-object.md +++ b/docs/visual-basic/language-reference/objects/my-computer-registry-object.md @@ -43,7 +43,7 @@ Provides properties and methods for manipulating the registry. For more information, see [Reading from and Writing to the Registry](../../../visual-basic/developing-apps/programming/computer-resources/reading-from-and-writing-to-the-registry.md). > [!NOTE] -> You can also manipulate the registry by using methods of the class. +> You can also manipulate the registry by using methods of the class. ## Requirements **Namespace:** diff --git a/docs/visual-basic/language-reference/objects/my-user-object.md b/docs/visual-basic/language-reference/objects/my-user-object.md index dda2170aa97ff..8f03cbef0c7eb 100644 --- a/docs/visual-basic/language-reference/objects/my-user-object.md +++ b/docs/visual-basic/language-reference/objects/my-user-object.md @@ -38,7 +38,7 @@ translation.priority.ht: Provides access to information about the current user. ## Remarks - For information about the methods and properties of the `My.User` object, see . + For information about the methods and properties of the `My.User` object, see . For more information, see [Accessing User Data](../../../visual-basic/developing-apps/programming/accessing-user-data.md). diff --git a/docs/visual-basic/language-reference/operators/await-operator.md b/docs/visual-basic/language-reference/operators/await-operator.md index 4a55fada32a13..b51165ebe5f10 100644 --- a/docs/visual-basic/language-reference/operators/await-operator.md +++ b/docs/visual-basic/language-reference/operators/await-operator.md @@ -86,12 +86,12 @@ Await AsyncMethodThatReturnsTask() If you await a task-returning async method that is canceled, the `Await` operator rethrows an . - A single task that is in a faulted state can reflect multiple exceptions. For example, the task might be the result of a call to . When you await such a task, the await operation rethrows only one of the exceptions. However, you can't predict which of the exceptions is rethrown. + A single task that is in a faulted state can reflect multiple exceptions. For example, the task might be the result of a call to . When you await such a task, the await operation rethrows only one of the exceptions. However, you can't predict which of the exceptions is rethrown. For examples of error handling in async methods, see [Try...Catch...Finally Statement](../../../visual-basic/language-reference/statements/try-catch-finally-statement.md). ## Example - The following Windows Forms example illustrates the use of `Await` in an async method, `WaitAsynchronouslyAsync`. Contrast the behavior of that method with the behavior of `WaitSynchronously`. Without an `Await` operator, `WaitSynchronously` runs synchronously despite the use of the `Async` modifier in its definition and a call to in its body. + The following Windows Forms example illustrates the use of `Await` in an async method, `WaitAsynchronouslyAsync`. Contrast the behavior of that method with the behavior of `WaitSynchronously`. Without an `Await` operator, `WaitSynchronously` runs synchronously despite the use of the `Async` modifier in its definition and a call to in its body. ```vb Private Async Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click diff --git a/docs/visual-basic/language-reference/operators/concatenation-operator.md b/docs/visual-basic/language-reference/operators/concatenation-operator.md index 04ade0b4bbfb4..1e44757f2eeb9 100644 --- a/docs/visual-basic/language-reference/operators/concatenation-operator.md +++ b/docs/visual-basic/language-reference/operators/concatenation-operator.md @@ -61,7 +61,7 @@ result = expression1 & expression2 ## Remarks If the data type of `expression1` or `expression2` is not `String` but widens to `String`, it is converted to `String`. If either of the data types does not widen to `String`, the compiler generates an error. - The data type of `result` is `String`. If one or both expressions evaluate to [Nothing](../../../visual-basic/language-reference/nothing.md) or have a value of , they are treated as a string with a value of "". + The data type of `result` is `String`. If one or both expressions evaluate to [Nothing](../../../visual-basic/language-reference/nothing.md) or have a value of , they are treated as a string with a value of "". > [!NOTE] > The `&` operator can be *overloaded*, which means that a class or structure can redefine its behavior when an operand has the type of that class or structure. If your code uses this operator on such a class or structure, be sure you understand its redefined behavior. For more information, see [Operator Procedures](../../../visual-basic/programming-guide/language-features/procedures/operator-procedures.md). diff --git a/docs/visual-basic/language-reference/operators/directcast-operator.md b/docs/visual-basic/language-reference/operators/directcast-operator.md index 504508865bc88..76fd62c2c82e2 100644 --- a/docs/visual-basic/language-reference/operators/directcast-operator.md +++ b/docs/visual-basic/language-reference/operators/directcast-operator.md @@ -64,6 +64,6 @@ Introduces a type conversion operation based on inheritance or implementation. In the preceding example, the run-time type of `q` is `Double`. `CType` succeeds because `Double` can be converted to `Integer`. However, the first `DirectCast` fails at run time because the run-time type of `Double` has no inheritance relationship with `Integer`, even though a conversion exists. The second `DirectCast` succeeds because it converts from type to type , from which inherits. ## See Also - + [Widening and Narrowing Conversions](../../../visual-basic/programming-guide/language-features/data-types/widening-and-narrowing-conversions.md) [Implicit and Explicit Conversions](../../../visual-basic/programming-guide/language-features/data-types/implicit-and-explicit-conversions.md) diff --git a/docs/visual-basic/language-reference/operators/gettype-operator.md b/docs/visual-basic/language-reference/operators/gettype-operator.md index 316de5494a1ce..0c2ab21f92dfd 100644 --- a/docs/visual-basic/language-reference/operators/gettype-operator.md +++ b/docs/visual-basic/language-reference/operators/gettype-operator.md @@ -56,7 +56,7 @@ GetType(typename) - Any Visual Basic data type, such as `Boolean` or `Date`. -- Any .NET Framework class, structure, module, or interface, such as or . +- Any .NET Framework class, structure, module, or interface, such as or . - Any class, structure, module, or interface defined by your application. @@ -66,11 +66,11 @@ GetType(typename) - Any enumeration defined by Visual Basic, the .NET Framework, or your application. - If you want to get the type object of an object variable, use the method. + If you want to get the type object of an object variable, use the method. The `GetType` operator can be useful in the following circumstances: -- You must access the metadata for a type at run time. The object supplies metadata such as type members and deployment information. You need this, for example, to reflect over an assembly. For more information, see . +- You must access the metadata for a type at run time. The object supplies metadata such as type members and deployment information. You need this, for example, to reflect over an assembly. For more information, see . - You want to compare two object references to see if they refer to instances of the same type. If they do, `GetType` returns references to the same object. diff --git a/docs/visual-basic/language-reference/statements/namespace-statement.md b/docs/visual-basic/language-reference/statements/namespace-statement.md index b52e09973d28f..3cd1f97e0fb1e 100644 --- a/docs/visual-basic/language-reference/statements/namespace-statement.md +++ b/docs/visual-basic/language-reference/statements/namespace-statement.md @@ -113,7 +113,7 @@ End Namespace [!code-vb[VbVbalrStatements#42](../../../visual-basic/language-reference/error-messages/codesnippet/VisualBasic/namespace-statement_3.vb)] ## Example - The following example defines the skeleton of a new generic list class and adds it to the namespace. + The following example defines the skeleton of a new generic list class and adds it to the namespace. ```vb Namespace System.Collections.Generic diff --git a/docs/visual-basic/language-reference/statements/of-clause.md b/docs/visual-basic/language-reference/statements/of-clause.md index 1dabcb4b8a5d3..4d0e26019a62f 100644 --- a/docs/visual-basic/language-reference/statements/of-clause.md +++ b/docs/visual-basic/language-reference/statements/of-clause.md @@ -50,7 +50,7 @@ translation.priority.ht: Introduces an `Of` clause, which identifies a *type parameter* on a *generic* class, structure, interface, delegate, or procedure. For information on generic types, see [Generic Types in Visual Basic](../../../visual-basic/programming-guide/language-features/data-types/generic-types.md). ## Using the Of Keyword - The following code example uses the `Of` keyword to define the outline of a class that takes two type parameters. It *constrains* the `keyType` parameter by the interface, which means the consuming code must supply a type argument that implements . This is necessary so that the `add` procedure can call the method. For more information on constraints, see [Type List](../../../visual-basic/language-reference/statements/type-list.md). + The following code example uses the `Of` keyword to define the outline of a class that takes two type parameters. It *constrains* the `keyType` parameter by the interface, which means the consuming code must supply a type argument that implements . This is necessary so that the `add` procedure can call the method. For more information on constraints, see [Type List](../../../visual-basic/language-reference/statements/type-list.md). ``` Public Class Dictionary(Of entryType, keyType As IComparable) diff --git a/docs/visual-basic/language-reference/statements/raiseevent-statement.md b/docs/visual-basic/language-reference/statements/raiseevent-statement.md index cd8750814acf3..4d0b28fc476cd 100644 --- a/docs/visual-basic/language-reference/statements/raiseevent-statement.md +++ b/docs/visual-basic/language-reference/statements/raiseevent-statement.md @@ -62,7 +62,7 @@ RaiseEvent eventname[( argumentlist )] [!code-vb[VbVbalrEvents#37](../../../visual-basic/language-reference/statements/codesnippet/VisualBasic/raiseevent-statement_1.vb)] - You cannot use `RaiseEvent` to raise events that are not explicitly declared in the module. For example, all forms inherit a event from , it cannot be raised using `RaiseEvent` in a derived form. If you declare a `Click` event in the form module, it shadows the form's own event. You can still invoke the form's event by calling the method. + You cannot use `RaiseEvent` to raise events that are not explicitly declared in the module. For example, all forms inherit a event from , it cannot be raised using `RaiseEvent` in a derived form. If you declare a `Click` event in the form module, it shadows the form's own event. You can still invoke the form's event by calling the method. By default, an event defined in Visual Basic raises its event handlers in the order that the connections are established. Because events can have `ByRef` parameters, a process that connects late may receive parameters that have been changed by an earlier event handler. After the event handlers execute, control is returned to the subroutine that raised the event. diff --git a/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md b/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md index 0cbe27a5b1818..6f27c9c9c5088 100644 --- a/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md +++ b/docs/visual-basic/language-reference/statements/try-catch-finally-statement.md @@ -145,7 +145,7 @@ End Try A task returned by an Async method may end in a faulted state, indicating that it completed due to an unhandled exception. A task may also end in a canceled state, which results in an `OperationCanceledException` being thrown out of the await expression. To catch either type of exception, place the `Await` expression that's associated with the task in a `Try` block, and catch the exception in the `Catch` block. An example is provided later in this topic. - A task can be in a faulted state because multiple exceptions were responsible for its faulting. For example, the task might be the result of a call to . When you await such a task, the caught exception is only one of the exceptions, and you can't predict which exception will be caught. An example is provided later in this topic. + A task can be in a faulted state because multiple exceptions were responsible for its faulting. For example, the task might be the result of a call to . When you await such a task, the caught exception is only one of the exceptions, and you can't predict which exception will be caught. An example is provided later in this topic. An `Await` expression can't be inside a `Catch` block or `Finally` block. @@ -197,7 +197,7 @@ End Try [!code-vb[csAsyncExceptions#1](../../../csharp/language-reference/keywords/codesnippet/VisualBasic/try-catch-finally-statement_7.vb)] ## Example - The following example illustrates exception handling where multiple tasks can result in multiple exceptions. The `Try` block has the `Await` expression for the task that returned. The task is complete when the three tasks to which is applied are complete. + The following example illustrates exception handling where multiple tasks can result in multiple exceptions. The `Try` block has the `Await` expression for the task that returned. The task is complete when the three tasks to which is applied are complete. Each of the three tasks causes an exception. The `Catch` block iterates through the exceptions, which are found in the `Exception.InnerExceptions` property of the task that `Task.WhenAll` returned. diff --git a/docs/visual-basic/misc/bc30128.md b/docs/visual-basic/misc/bc30128.md index 44b0eb3b76bc2..37ba82e0c5799 100644 --- a/docs/visual-basic/misc/bc30128.md +++ b/docs/visual-basic/misc/bc30128.md @@ -43,4 +43,4 @@ The common language runtime does not accept the attribute in a security context. ## See also [Attributes overview](~/docs/visual-basic/programming-guide/concepts/attributes/index.md) - + diff --git a/docs/visual-basic/misc/bc30129.md b/docs/visual-basic/misc/bc30129.md index 91fbbe73f5ebc..410652b95be15 100644 --- a/docs/visual-basic/misc/bc30129.md +++ b/docs/visual-basic/misc/bc30129.md @@ -43,4 +43,4 @@ The common language runtime does not accept the attribute on an assembly. ## See also [Attributes overview](~/docs/visual-basic/programming-guide/concepts/attributes/index.md) - + diff --git a/docs/visual-basic/misc/bc30130.md b/docs/visual-basic/misc/bc30130.md index 2cda46f689f3d..0148eee39f2a6 100644 --- a/docs/visual-basic/misc/bc30130.md +++ b/docs/visual-basic/misc/bc30130.md @@ -43,4 +43,4 @@ The common language runtime does not accept the attribute on a module. ## See also [Attributes overview](~/docs/visual-basic/programming-guide/concepts/attributes/index.md) - + diff --git a/docs/visual-basic/misc/bc30131.md b/docs/visual-basic/misc/bc30131.md index a54ef17fde258..884ec25680a42 100644 --- a/docs/visual-basic/misc/bc30131.md +++ b/docs/visual-basic/misc/bc30131.md @@ -41,4 +41,4 @@ The common language runtime does not accept the security attribute on a module. ## See also [Attributes overview](~/docs/visual-basic/programming-guide/concepts/attributes/index.md) - + diff --git a/docs/visual-basic/misc/bc30532.md b/docs/visual-basic/misc/bc30532.md index 198b477cc42d1..28ba162fdb0b6 100644 --- a/docs/visual-basic/misc/bc30532.md +++ b/docs/visual-basic/misc/bc30532.md @@ -36,13 +36,13 @@ translation.priority.mt: - "tr-tr" --- # Conversion from 'Date' to 'Double' requires calling the 'Date.ToOADate' method -You have attempted to cast a `Date` value to a `Double` value, which cannot be done without using the method. +You have attempted to cast a `Date` value to a `Double` value, which cannot be done without using the method. **Error ID:** BC30532 ## To correct this error -- Use the method to convert the value. +- Use the method to convert the value. ## See Also [Type Conversions in Visual Basic](../../visual-basic/programming-guide/language-features/data-types/type-conversions.md) diff --git a/docs/visual-basic/misc/bc30533.md b/docs/visual-basic/misc/bc30533.md index 7a024c8cf7cbe..6ab581d4b4733 100644 --- a/docs/visual-basic/misc/bc30533.md +++ b/docs/visual-basic/misc/bc30533.md @@ -36,7 +36,7 @@ translation.priority.mt: - "tr-tr" --- # Conversion from 'Double' to 'Date' requires calling the 'Date.FromOADate' -You have attempted to cast a `Date` value to a `Double` value, which cannot be done without using the method. +You have attempted to cast a `Date` value to a `Double` value, which cannot be done without using the method. **Error ID:** BC30533 diff --git a/docs/visual-basic/misc/bc30768.md b/docs/visual-basic/misc/bc30768.md index 6c2ced2e7f713..06000a8dd5adc 100644 --- a/docs/visual-basic/misc/bc30768.md +++ b/docs/visual-basic/misc/bc30768.md @@ -36,7 +36,7 @@ translation.priority.mt: - "tr-tr" --- # 'Line' statements are no longer supported (Smart Device/Visual Basic Compiler Error) -The `Line` statement is no longer supported. File I/O functionality is normally available as , but the targeted version of the .NET Compact Framework does not support it. +The `Line` statement is no longer supported. File I/O functionality is normally available as , but the targeted version of the .NET Compact Framework does not support it. **Error ID:** BC30768 @@ -44,7 +44,7 @@ The `Line` statement is no longer supported. File I/O functionality is normally - If performing file access, use the functions defined in the namespace. -- If performing graphics, use . +- If performing graphics, use . ## See Also diff --git a/docs/visual-basic/misc/bc30819.md b/docs/visual-basic/misc/bc30819.md index cf4b9243b8f2a..a9cf9964eb74f 100644 --- a/docs/visual-basic/misc/bc30819.md +++ b/docs/visual-basic/misc/bc30819.md @@ -38,13 +38,13 @@ translation.priority.mt: # '<mathfunction1>' is not declared '\' is not declared. Function has moved to the System.Math class and is now called '\'. - Several functions that were intrinsic to [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] in previous versions have been moved to the namespace. This makes their functionality more generally available to all programming languages. + Several functions that were intrinsic to [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] in previous versions have been moved to the namespace. This makes their functionality more generally available to all programming languages. **Error ID:** BC30819 ## To correct this error -- Use the methods declared in . +- Use the methods declared in . ## See Also diff --git a/docs/visual-basic/misc/bc30820.md b/docs/visual-basic/misc/bc30820.md index f082c314506ca..3a08d48569707 100644 --- a/docs/visual-basic/misc/bc30820.md +++ b/docs/visual-basic/misc/bc30820.md @@ -38,7 +38,7 @@ translation.priority.mt: # '<lsetstmt>' is not declared '\' is not declared. LSet statements are no longer supported; use Microsoft.VisualBasic.LSet instead. - Several functions that were intrinsic to [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] in previous versions have been moved to the namespace. This makes their functionality more generally available to all programming languages. + Several functions that were intrinsic to [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] in previous versions have been moved to the namespace. This makes their functionality more generally available to all programming languages. **Error ID:** BC30820 diff --git a/docs/visual-basic/misc/bc30821.md b/docs/visual-basic/misc/bc30821.md index f23a48cba39bd..be96d8ad24daf 100644 --- a/docs/visual-basic/misc/bc30821.md +++ b/docs/visual-basic/misc/bc30821.md @@ -38,7 +38,7 @@ translation.priority.mt: # '<rsetstmt>' is not declared '\' is not declared. RSet statements are no longer supported; use Microsoft.VisualBasic.RSet instead. - Several functions that were intrinsic to [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] in previous versions have been moved to the namespace. This makes their functionality more generally available to all programming languages. + Several functions that were intrinsic to [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] in previous versions have been moved to the namespace. This makes their functionality more generally available to all programming languages. **Error ID:** BC30821 diff --git a/docs/visual-basic/misc/bc31521.md b/docs/visual-basic/misc/bc31521.md index 0741995c9c2b8..82162263f8a97 100644 --- a/docs/visual-basic/misc/bc31521.md +++ b/docs/visual-basic/misc/bc31521.md @@ -48,4 +48,4 @@ The specified attribute can only be applied once to an attribute. ## See Also - + diff --git a/docs/visual-basic/misc/bc32510.md b/docs/visual-basic/misc/bc32510.md index c5641df6cfe7d..5c0f5fbe75c69 100644 --- a/docs/visual-basic/misc/bc32510.md +++ b/docs/visual-basic/misc/bc32510.md @@ -36,7 +36,7 @@ translation.priority.mt: - "tr-tr" --- # Attribute 'System.Runtime.InteropServices.DefaultCharSetAttribute' is not supported in this version -The attribute allows you to specify the character set to be used in marshaled strings. Its value takes a member of the enumeration. +The attribute allows you to specify the character set to be used in marshaled strings. Its value takes a member of the enumeration. The current version of [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] does not support this attribute. Support is possible in future versions. diff --git a/docs/visual-basic/misc/bc36558.md b/docs/visual-basic/misc/bc36558.md index d63a4fcd0389c..eec517e7dfa87 100644 --- a/docs/visual-basic/misc/bc36558.md +++ b/docs/visual-basic/misc/bc36558.md @@ -38,7 +38,7 @@ translation.priority.mt: # The custom-designed version of 'System.Runtime.CompilerServices.ExtensionAttribute' found by the compiler is not valid The custom-designed version of 'System.Runtime.CompilerServices.ExtensionAttribute' found by the compiler is not valid. Its attribute usage flags must be set to allow assemblies, classes, and methods. - The custom-designed version of that the compiler found does not set its attribute usage flags to enable application of the attribute to assemblies, methods, and classes. Application to at least those three program elements is required. + The custom-designed version of that the compiler found does not set its attribute usage flags to enable application of the attribute to assemblies, methods, and classes. Application to at least those three program elements is required. **Error ID:** BC36558 @@ -46,7 +46,7 @@ The custom-designed version of 'System.Runtime.CompilerServices.ExtensionAttribu - Change the attribute definition to enable the attribute to apply at least to assemblies, methods, and classes, as shown in the following examples. -- Use instead of the custom-designed version. +- Use instead of the custom-designed version. ## Example The following example uses the `AttributeUsage` attribute to specify which program elements the new version of `ExtensionAttribute` can apply to. The example specifies three members of the `AttributeTargets` enumeration: `Assembly`, `Class`, and `Method`. The omission of any one of these elements will cause this error. diff --git a/docs/visual-basic/programming-guide/concepts/assemblies-gac/index.md b/docs/visual-basic/programming-guide/concepts/assemblies-gac/index.md index fbc23fe5d3a52..a381fb126ee6f 100644 --- a/docs/visual-basic/programming-guide/concepts/assemblies-gac/index.md +++ b/docs/visual-basic/programming-guide/concepts/assemblies-gac/index.md @@ -46,7 +46,7 @@ Assemblies form the fundamental unit of deployment, version control, reuse, acti - A file table describing all the other files that make up the assembly, for example, any other assemblies you created that your .exe or .dll file relies on, or even bitmap or Readme files. -- An *assembly reference list*, which is a list of all external dependencies—.dlls or other files your application needs that may have been created by someone else. Assembly references contain references to both global and private objects. Global objects reside in the global assembly cache, an area available to other applications, somewhat like the System32 directory. The namespace is an example of an assembly in the global assembly cache. Private objects must be in a directory at either the same level as or below the directory in which your application is installed. +- An *assembly reference list*, which is a list of all external dependencies—.dlls or other files your application needs that may have been created by someone else. Assembly references contain references to both global and private objects. Global objects reside in the global assembly cache, an area available to other applications, somewhat like the System32 directory. The namespace is an example of an assembly in the global assembly cache. Private objects must be in a directory at either the same level as or below the directory in which your application is installed. Because assemblies contain information about content, versioning, and dependencies, the applications you create with Visual Basic do not rely on Windows registry values to function properly. Assemblies reduce .dll conflicts and make your applications more reliable and easier to deploy. In many cases, you can install a .NET-based application simply by copying its files to the target computer. diff --git a/docs/visual-basic/programming-guide/concepts/assemblies-gac/walkthrough-embedding-types-from-managed-assemblies-in-vs.md b/docs/visual-basic/programming-guide/concepts/assemblies-gac/walkthrough-embedding-types-from-managed-assemblies-in-vs.md index 61d1c01adce57..d941a13993507 100644 --- a/docs/visual-basic/programming-guide/concepts/assemblies-gac/walkthrough-embedding-types-from-managed-assemblies-in-vs.md +++ b/docs/visual-basic/programming-guide/concepts/assemblies-gac/walkthrough-embedding-types-from-managed-assemblies-in-vs.md @@ -45,7 +45,7 @@ If you embed type information from a strong-named managed assembly, you can loos - Constants are not embedded. -- The class does not support an embedded type as a key. You can implement your own dictionary type to support an embedded type as a key. +- The class does not support an embedded type as a key. You can implement your own dictionary type to support an embedded type as a key. In this walkthrough, you will do the following: diff --git a/docs/visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md b/docs/visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md index 1a15099594532..e9032c38cc03b 100644 --- a/docs/visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md +++ b/docs/visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md @@ -66,7 +66,7 @@ You can set up a button that you can use to cancel an async application if you d Dim cts As CancellationTokenSource ``` -2. Add the following event handler for the **Cancel** button. The event handler uses the method to notify `cts` when the user requests cancellation. +2. Add the following event handler for the **Cancel** button. The event handler uses the method to notify `cts` when the user requests cancellation. ```vb ' ***Add an event handler for the Cancel button. @@ -87,7 +87,7 @@ You can set up a button that you can use to cancel an async application if you d cts = New CancellationTokenSource() ``` - - In the call to `AccessTheWebAsync`, which downloads the contents of a specified website, send the property of `cts` as an argument. The `Token` property propagates the message if cancellation is requested. Add a catch block that displays a message if the user chooses to cancel the download operation. The following code shows the changes. + - In the call to `AccessTheWebAsync`, which downloads the contents of a specified website, send the property of `cts` as an argument. The `Token` property propagates the message if cancellation is requested. Add a catch block that displays a message if the user chooses to cancel the download operation. The following code shows the changes. ```vb Try @@ -106,7 +106,7 @@ You can set up a button that you can use to cancel an async application if you d End Try ``` -4. In `AccessTheWebAsync`, use the overload of the `GetAsync` method in the type to download the contents of a website. Pass `ct`, the parameter of `AccessTheWebAsync`, as the second argument. The token carries the message if the user chooses the **Cancel** button. +4. In `AccessTheWebAsync`, use the overload of the `GetAsync` method in the type to download the contents of a website. Pass `ct`, the parameter of `AccessTheWebAsync`, as the second argument. The token carries the message if the user chooses the **Cancel** button. The following code shows the changes in `AccessTheWebAsync`. diff --git a/docs/visual-basic/programming-guide/concepts/async/cancel-async-tasks-after-a-period-of-time.md b/docs/visual-basic/programming-guide/concepts/async/cancel-async-tasks-after-a-period-of-time.md index b34df5345dccd..ecd64611e007b 100644 --- a/docs/visual-basic/programming-guide/concepts/async/cancel-async-tasks-after-a-period-of-time.md +++ b/docs/visual-basic/programming-guide/concepts/async/cancel-async-tasks-after-a-period-of-time.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # Cancel Async Tasks after a Period of Time (Visual Basic) -You can cancel an asynchronous operation after a period of time by using the method if you don't want to wait for the operation to finish. This method schedules the cancellation of any associated tasks that aren’t complete within the period of time that’s designated by the `CancelAfter` expression. +You can cancel an asynchronous operation after a period of time by using the method if you don't want to wait for the operation to finish. This method schedules the cancellation of any associated tasks that aren’t complete within the period of time that’s designated by the `CancelAfter` expression. This example adds to the code that’s developed in [Cancel an Async Task or a List of Tasks (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/cancel-an-async-task-or-a-list-of-tasks.md) to download a list of websites and to display the length of the contents of each one. diff --git a/docs/visual-basic/programming-guide/concepts/async/cancel-remaining-async-tasks-after-one-is-complete.md b/docs/visual-basic/programming-guide/concepts/async/cancel-remaining-async-tasks-after-one-is-complete.md index 7e1f10b275ac5..1a5523febe662 100644 --- a/docs/visual-basic/programming-guide/concepts/async/cancel-remaining-async-tasks-after-one-is-complete.md +++ b/docs/visual-basic/programming-guide/concepts/async/cancel-remaining-async-tasks-after-one-is-complete.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # Cancel Remaining Async Tasks after One Is Complete (Visual Basic) -By using the method together with a , you can cancel all remaining tasks when one task is complete. The `WhenAny` method takes an argument that’s a collection of tasks. The method starts all the tasks and returns a single task. The single task is complete when any task in the collection is complete. +By using the method together with a , you can cancel all remaining tasks when one task is complete. The `WhenAny` method takes an argument that’s a collection of tasks. The method starts all the tasks and returns a single task. The single task is complete when any task in the collection is complete. This example demonstrates how to use a cancellation token in conjunction with `WhenAny` to hold onto the first task to finish from the collection of tasks and to cancel the remaining tasks. Each task downloads the contents of a website. The example displays the length of the contents of the first download to complete and cancels the other downloads. @@ -99,7 +99,7 @@ End Function Dim firstFinishedTask As Task(Of Integer) = Await Task.WhenAny(downloadTasks) ``` -5. In this example, you’re interested only in the task that finishes first. Therefore, use to cancel the remaining tasks. +5. In this example, you’re interested only in the task that finishes first. Therefore, use to cancel the remaining tasks. ```vb ' ***Cancel the rest of the downloads. You just want the first one. diff --git a/docs/visual-basic/programming-guide/concepts/async/fine-tuning-your-async-application.md b/docs/visual-basic/programming-guide/concepts/async/fine-tuning-your-async-application.md index ff761db060923..de74a841441ed 100644 --- a/docs/visual-basic/programming-guide/concepts/async/fine-tuning-your-async-application.md +++ b/docs/visual-basic/programming-guide/concepts/async/fine-tuning-your-async-application.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # Fine-Tuning Your Async Application (Visual Basic) -You can add precision and flexibility to your async applications by using the methods and properties that the type makes available. The topics in this section show examples that use and important `Task` methods such as and . +You can add precision and flexibility to your async applications by using the methods and properties that the type makes available. The topics in this section show examples that use and important `Task` methods such as and . By using `WhenAny` and `WhenAll`, you can more easily start multiple tasks and await their completion by monitoring a single task. diff --git a/docs/visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md b/docs/visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md index 43c055c5392b8..cc6ac2ec4661c 100644 --- a/docs/visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md +++ b/docs/visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # How to: Extend the Async Walkthrough by Using Task.WhenAll (Visual Basic) -You can improve the performance of the async solution in [Walkthrough: Accessing the Web by Using Async and Await (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md) by using the method. This method asynchronously awaits multiple asynchronous operations, which are represented as a collection of tasks. +You can improve the performance of the async solution in [Walkthrough: Accessing the Web by Using Async and Await (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md) by using the method. This method asynchronously awaits multiple asynchronous operations, which are represented as a collection of tasks. You might have noticed in the walkthrough that the websites download at different rates. Sometimes one of the websites is very slow, which delays all the remaining downloads. When you run the asynchronous solutions that you build in the walkthrough, you can end the program easily if you don't want to wait, but a better option would be to start all the downloads at the same time and let faster downloads continue without waiting for the one that’s delayed. @@ -433,5 +433,5 @@ End Class ``` ## See Also - + [Walkthrough: Accessing the Web by Using Async and Await (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md) diff --git a/docs/visual-basic/programming-guide/concepts/async/index.md b/docs/visual-basic/programming-guide/concepts/async/index.md index d586282b1754d..bc92f1cfcc065 100644 --- a/docs/visual-basic/programming-guide/concepts/async/index.md +++ b/docs/visual-basic/programming-guide/concepts/async/index.md @@ -158,9 +158,9 @@ Dim urlContents As String = Await client.GetStringAsync() ## Threads Async methods are intended to be non-blocking operations. An `Await` expression in an async method doesn’t block the current thread while the awaited task is running. Instead, the expression signs up the rest of the method as a continuation and returns control to the caller of the async method. - The `Async` and `Await` keywords don't cause additional threads to be created. Async methods don't require multithreading because an async method doesn't run on its own thread. The method runs on the current synchronization context and uses time on the thread only when the method is active. You can use to move CPU-bound work to a background thread, but a background thread doesn't help with a process that's just waiting for results to become available. + The `Async` and `Await` keywords don't cause additional threads to be created. Async methods don't require multithreading because an async method doesn't run on its own thread. The method runs on the current synchronization context and uses time on the thread only when the method is active. You can use to move CPU-bound work to a background thread, but a background thread doesn't help with a process that's just waiting for results to become available. - The async-based approach to asynchronous programming is preferable to existing approaches in almost every case. In particular, this approach is better than for IO-bound operations because the code is simpler and you don't have to guard against race conditions. In combination with , async programming is better than for CPU-bound operations because async programming separates the coordination details of running your code from the work that `Task.Run` transfers to the threadpool. + The async-based approach to asynchronous programming is preferable to existing approaches in almost every case. In particular, this approach is better than for IO-bound operations because the code is simpler and you don't have to guard against race conditions. In combination with , async programming is better than for CPU-bound operations because async programming separates the coordination details of running your code from the work that `Task.Run` transfers to the threadpool. ## Async and Await If you specify that a method is an async method by using an [Async](../../../../visual-basic/language-reference/modifiers/async.md) modifier, you enable the following two capabilities. @@ -250,7 +250,7 @@ Await Task_MethodAsync() |Title|Description|Sample| |-----------|-----------------|------------| |[Walkthrough: Accessing the Web by Using Async and Await (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md)|Shows how to convert a synchronous WPF solution to an asynchronous WPF solution. The application downloads a series of websites.|[Async Sample: Accessing the Web Walkthrough](http://go.microsoft.com/fwlink/p/?LinkID=255191&clcid=0x409)| -|[How to: Extend the Async Walkthrough by Using Task.WhenAll (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md)|Adds to the previous walkthrough. The use of `WhenAll` starts all the downloads at the same time.|| +|[How to: Extend the Async Walkthrough by Using Task.WhenAll (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/how-to-extend-the-async-walkthrough-by-using-task-whenall.md)|Adds to the previous walkthrough. The use of `WhenAll` starts all the downloads at the same time.|| |[How to: Make Multiple Web Requests in Parallel by Using Async and Await (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md)|Demonstrates how to start several tasks at the same time.|[Async Sample: Make Multiple Web Requests in Parallel](http://go.microsoft.com/fwlink/p/?LinkID=254906&clcid=0x409)| |[Async Return Types (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/async-return-types.md)|Illustrates the types that async methods can return and explains when each type is appropriate.|| |[Control Flow in Async Programs (Visual Basic)](../../../../visual-basic/programming-guide/concepts/async/control-flow-in-async-programs.md)|Traces in detail the flow of control through a succession of await expressions in an asynchronous program.|[Async Sample: Control Flow in Async Programs](http://go.microsoft.com/fwlink/p/?LinkID=255285&clcid=0x409)| diff --git a/docs/visual-basic/programming-guide/concepts/async/start-multiple-async-tasks-and-process-them-as-they-complete.md b/docs/visual-basic/programming-guide/concepts/async/start-multiple-async-tasks-and-process-them-as-they-complete.md index a9e7762b93946..557ed9b2f399a 100644 --- a/docs/visual-basic/programming-guide/concepts/async/start-multiple-async-tasks-and-process-them-as-they-complete.md +++ b/docs/visual-basic/programming-guide/concepts/async/start-multiple-async-tasks-and-process-them-as-they-complete.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # Start Multiple Async Tasks and Process Them As They Complete (Visual Basic) -By using , you can start multiple tasks at the same time and process them one by one as they’re completed rather than process them in the order in which they're started. +By using , you can start multiple tasks at the same time and process them one by one as they’re completed rather than process them in the order in which they're started. The following example uses a query to create a collection of tasks. Each task downloads the contents of a specified website. In each iteration of a while loop, an awaited call to `WhenAny` returns the task in the collection of tasks that finishes its download first. That task is removed from the collection and processed. The loop repeats until the collection contains no more tasks. @@ -63,7 +63,7 @@ Dim downloadTasksQuery As IEnumerable(Of Task(Of Integer)) = In the MainWindow.xaml.vb file of the project, make the following changes to the `AccessTheWebAsync` method. -- Execute the query by applying instead of . +- Execute the query by applying instead of . ```vb Dim downloadTasks As List(Of Task(Of Integer)) = downloadTasksQuery.ToList() diff --git a/docs/visual-basic/programming-guide/concepts/attributes/common-attributes.md b/docs/visual-basic/programming-guide/concepts/attributes/common-attributes.md index e7c9f5ab3a2cc..5336b1da1e4d3 100644 --- a/docs/visual-basic/programming-guide/concepts/attributes/common-attributes.md +++ b/docs/visual-basic/programming-guide/concepts/attributes/common-attributes.md @@ -65,7 +65,7 @@ This topic describes the attributes that are most commonly used in Visual Basic ||Specifies whether an assembly supports side-by-side execution on the same computer, in the same process, or in the same application domain.| ### Informational Attributes - You can use informational attributes to provide additional company or product information for an assembly. The following table shows the informational attributes defined in the namespace. + You can use informational attributes to provide additional company or product information for an assembly. The following table shows the informational attributes defined in the namespace. |Attribute|Purpose| |---------------|-------------| @@ -78,7 +78,7 @@ This topic describes the attributes that are most commonly used in Visual Basic ||Indicates whether the assembly is compliant with the Common Language Specification (CLS).| ### Assembly Manifest Attributes - You can use assembly manifest attributes to provide information in the assembly manifest. This includes title, description, default alias, and configuration. The following table shows the assembly manifest attributes defined in the namespace. + You can use assembly manifest attributes to provide information in the assembly manifest. This includes title, description, default alias, and configuration. The following table shows the assembly manifest attributes defined in the namespace. |Attribute|Purpose| |---------------|-------------| @@ -225,7 +225,7 @@ End Class ## Caller Info Attributes By using Caller Info attributes, you can obtain information about the caller to a method. You can obtain the file path of the source code, the line number in the source code, and the member name of the caller. - To obtain member caller information, you use attributes that are applied to optional parameters. Each optional parameter specifies a default value. The following table lists the Caller Info attributes that are defined in the namespace: + To obtain member caller information, you use attributes that are applied to optional parameters. Each optional parameter specifies a default value. The following table lists the Caller Info attributes that are defined in the namespace: |Attribute|Description|Type| |---|---|---| diff --git a/docs/visual-basic/programming-guide/concepts/caller-information.md b/docs/visual-basic/programming-guide/concepts/caller-information.md index 64b742587ca17..44e6845728f06 100644 --- a/docs/visual-basic/programming-guide/concepts/caller-information.md +++ b/docs/visual-basic/programming-guide/concepts/caller-information.md @@ -25,7 +25,7 @@ translation.priority.mt: # Caller Information (Visual Basic) By using Caller Info attributes, you can obtain information about the caller to a method. You can obtain file path of the source code, the line number in the source code, and the member name of the caller. This information is helpful for tracing, debugging, and creating diagnostic tools. - To obtain this information, you use attributes that are applied to optional parameters, each of which has a default value. The following table lists the Caller Info attributes that are defined in the namespace: + To obtain this information, you use attributes that are applied to optional parameters, each of which has a default value. The following table lists the Caller Info attributes that are defined in the namespace: |Attribute|Description|Type| |---|---|---| diff --git a/docs/visual-basic/programming-guide/concepts/collections.md b/docs/visual-basic/programming-guide/concepts/collections.md index af4c6cc9995df..d41a0945a2fc0 100644 --- a/docs/visual-basic/programming-guide/concepts/collections.md +++ b/docs/visual-basic/programming-guide/concepts/collections.md @@ -31,7 +31,7 @@ For many applications, you want to create and manage groups of related objects. A collection is a class, so you must declare an instance of the class before you can add elements to that collection. - If your collection contains elements of only one data type, you can use one of the classes in the namespace. A generic collection enforces type safety so that no other data type can be added to it. When you retrieve an element from a generic collection, you do not have to determine its data type or convert it. + If your collection contains elements of only one data type, you can use one of the classes in the namespace. A generic collection enforces type safety so that no other data type can be added to it. When you retrieve an element from a generic collection, you do not have to determine its data type or convert it. > [!NOTE] > For the examples in this topic, include [Imports](../../../visual-basic/language-reference/statements/imports-statement-net-namespace-and-type.md) statements for the `System.Collections.Generic` and `System.Linq` namespaces. @@ -202,7 +202,7 @@ End Class You can create a generic collection by using one of the classes in the namespace. A generic collection is useful when every item in the collection has the same data type. A generic collection enforces strong typing by allowing only the desired data type to be added. - The following table lists some of the frequently used classes of the namespace: + The following table lists some of the frequently used classes of the namespace: |Class|Description| |---|---| @@ -212,21 +212,21 @@ End Class ||Represents a collection of key/value pairs that are sorted by key based on the associated implementation.| ||Represents a last in, first out (LIFO) collection of objects.| - For additional information, see [Commonly Used Collection Types](../../../standard/collections/commonly-used-collection-types.md), [Selecting a Collection Class](../../../standard/collections/selecting-a-collection-class.md), and . + For additional information, see [Commonly Used Collection Types](../../../standard/collections/commonly-used-collection-types.md), [Selecting a Collection Class](../../../standard/collections/selecting-a-collection-class.md), and . ### System.Collections.Concurrent Classes In the .NET Framework 4 or newer, the collections in the namespace provide efficient thread-safe operations for accessing collection items from multiple threads. - The classes in the namespace should be used instead of the corresponding types in the and namespaces whenever multiple threads are accessing the collection concurrently. For more information, see [Thread-Safe Collections](../../../standard/collections/thread-safe/index.md) and . + The classes in the namespace should be used instead of the corresponding types in the and namespaces whenever multiple threads are accessing the collection concurrently. For more information, see [Thread-Safe Collections](../../../standard/collections/thread-safe/index.md) and . Some classes included in the namespace are , , , and . ### System.Collections Classes - The classes in the namespace do not store elements as specifically typed objects, but as objects of type `Object`. + The classes in the namespace do not store elements as specifically typed objects, but as objects of type `Object`. - Whenever possible, you should use the generic collections in the namespace or the namespace instead of the legacy types in the `System.Collections` namespace. + Whenever possible, you should use the generic collections in the namespace or the namespace instead of the legacy types in the `System.Collections` namespace. The following table lists some of the frequently used classes in the `System.Collections` namespace: @@ -247,7 +247,7 @@ End Class When you use the Visual Basic `Collection` class, the first item in a collection has an index of 1. This differs from the .NET Framework collection classes, for which the starting index is 0. - Whenever possible, you should use the generic collections in the namespace or the namespace instead of the Visual Basic `Collection` class. + Whenever possible, you should use the generic collections in the namespace or the namespace instead of the Visual Basic `Collection` class. For more information, see . diff --git a/docs/visual-basic/programming-guide/concepts/iterators.md b/docs/visual-basic/programming-guide/concepts/iterators.md index bc70de2baa573..fec4555296478 100644 --- a/docs/visual-basic/programming-guide/concepts/iterators.md +++ b/docs/visual-basic/programming-guide/concepts/iterators.md @@ -444,7 +444,7 @@ End Class On each successive iteration of the `For Each…Next` loop (or the direct call to `IEnumerator.MoveNext`), the next iterator code body resumes after the previous `Yield` statement. It then continues to the next `Yield` statement until the end of the iterator body is reached, or until an `Exit Function` or `Return` statement is encountered. - Iterators do not support the method. To re-iterate from the start, you must obtain a new iterator. + Iterators do not support the method. To re-iterate from the start, you must obtain a new iterator. For additional information, see the [Visual Basic Language Specification](../../../visual-basic/reference/language-specification/index.md). diff --git a/docs/visual-basic/programming-guide/concepts/linq/aggregation-operations.md b/docs/visual-basic/programming-guide/concepts/linq/aggregation-operations.md index d0c61c48d5a07..199727b6ba550 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/aggregation-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/aggregation-operations.md @@ -35,13 +35,13 @@ An aggregation operation computes a single value from a collection of values. An |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|Aggregate|Performs a custom aggregation operation on the values of a collection.|Not applicable.|

| -|Average|Calculates the average value of a collection of values.|`Aggregate … In … Into Average()`|

| -|Count|Counts the elements in a collection, optionally only those elements that satisfy a predicate function.|`Aggregate … In … Into Count()`|

| -|LongCount|Counts the elements in a large collection, optionally only those elements that satisfy a predicate function.|`Aggregate … In … Into LongCount()`|

| -|Max|Determines the maximum value in a collection.|`Aggregate … In … Into Max()`|

| -|Min|Determines the minimum value in a collection.|`Aggregate … In … Into Min()`|

| -|Sum|Calculates the sum of the values in a collection.|`Aggregate … In … Into Sum()`|

| +|Aggregate|Performs a custom aggregation operation on the values of a collection.|Not applicable.|

| +|Average|Calculates the average value of a collection of values.|`Aggregate … In … Into Average()`|

| +|Count|Counts the elements in a collection, optionally only those elements that satisfy a predicate function.|`Aggregate … In … Into Count()`|

| +|LongCount|Counts the elements in a large collection, optionally only those elements that satisfy a predicate function.|`Aggregate … In … Into LongCount()`|

| +|Max|Determines the maximum value in a collection.|`Aggregate … In … Into Max()`|

| +|Min|Determines the minimum value in a collection.|`Aggregate … In … Into Min()`|

| +|Sum|Calculates the sum of the values in a collection.|`Aggregate … In … Into Sum()`|

| ## Query Expression Syntax Examples diff --git a/docs/visual-basic/programming-guide/concepts/linq/comparison-of-xpath-and-linq-to-xml.md b/docs/visual-basic/programming-guide/concepts/linq/comparison-of-xpath-and-linq-to-xml.md index 41647224d95f1..97fd23251087b 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/comparison-of-xpath-and-linq-to-xml.md +++ b/docs/visual-basic/programming-guide/concepts/linq/comparison-of-xpath-and-linq-to-xml.md @@ -85,15 +85,15 @@ customers.Element("Customer").Elements("CompanyName") |XPath axis|LINQ to XML axis| |----------------|----------------------| -|child (the default axis)|| -|Parent (..)|| -|attribute axis (@)|

or

| -|ancestor axis|| -|ancestor-or-self axis|| -|descendant axis (//)|

or

| -|descendant-or-self|

or

| -|following-sibling|

or

| -|preceding-sibling|

or

| +|child (the default axis)|| +|Parent (..)|| +|attribute axis (@)|

or

| +|ancestor axis|| +|ancestor-or-self axis|| +|descendant axis (//)|

or

| +|descendant-or-self|

or

| +|following-sibling|

or

| +|preceding-sibling|

or

| |following|No direct equivalent.| |preceding|No direct equivalent.| diff --git a/docs/visual-basic/programming-guide/concepts/linq/concatenation-operations.md b/docs/visual-basic/programming-guide/concepts/linq/concatenation-operations.md index a43fe6886a924..989eaf9185474 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/concatenation-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/concatenation-operations.md @@ -35,7 +35,7 @@ Concatenation refers to the operation of appending one sequence to another. |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|Concat|Concatenates two sequences to form one sequence.|Not applicable.|

| +|Concat|Concatenates two sequences to form one sequence.|Not applicable.|

| ## See Also diff --git a/docs/visual-basic/programming-guide/concepts/linq/converting-data-types.md b/docs/visual-basic/programming-guide/concepts/linq/converting-data-types.md index 124502cbfb1b6..7df5ccd78cb4f 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/converting-data-types.md +++ b/docs/visual-basic/programming-guide/concepts/linq/converting-data-types.md @@ -27,11 +27,11 @@ Conversion methods change the type of input objects. Conversion operations in LINQ queries are useful in a variety of applications. Following are some examples: -- The method can be used to hide a type's custom implementation of a standard query operator. +- The method can be used to hide a type's custom implementation of a standard query operator. -- The method can be used to enable non-parameterized collections for LINQ querying. +- The method can be used to enable non-parameterized collections for LINQ querying. -- The , , , and methods can be used to force immediate query execution instead of deferring it until the query is enumerated. +- The , , , and methods can be used to force immediate query execution instead of deferring it until the query is enumerated. ## Methods The following table lists the standard query operator methods that perform data-type conversions. @@ -40,14 +40,14 @@ Conversion methods change the type of input objects. |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|AsEnumerable|Returns the input typed as .|Not applicable.|| -|AsQueryable|Converts a (generic) to a (generic) .|Not applicable.|| -|Cast|Casts the elements of a collection to a specified type.|`From … As …`|

| -|OfType|Filters values, depending on their ability to be cast to a specified type.|Not applicable.|

| -|ToArray|Converts a collection to an array. This method forces query execution.|Not applicable.|| -|ToDictionary|Puts elements into a based on a key selector function. This method forces query execution.|Not applicable.|| -|ToList|Converts a collection to a . This method forces query execution.|Not applicable.|| -|ToLookup|Puts elements into a (a one-to-many dictionary) based on a key selector function. This method forces query execution.|Not applicable.|| +|AsEnumerable|Returns the input typed as .|Not applicable.|| +|AsQueryable|Converts a (generic) to a (generic) .|Not applicable.|| +|Cast|Casts the elements of a collection to a specified type.|`From … As …`|

| +|OfType|Filters values, depending on their ability to be cast to a specified type.|Not applicable.|

| +|ToArray|Converts a collection to an array. This method forces query execution.|Not applicable.|| +|ToDictionary|Puts elements into a based on a key selector function. This method forces query execution.|Not applicable.|| +|ToList|Converts a collection to a . This method forces query execution.|Not applicable.|| +|ToLookup|Puts elements into a (a one-to-many dictionary) based on a key selector function. This method forces query execution.|Not applicable.|| ## Query Expression Syntax Example The following code example uses the `From As` clause to cast a type to a subtype before accessing a member that is available only on the subtype. diff --git a/docs/visual-basic/programming-guide/concepts/linq/deferred-execution-and-lazy-evaluation-in-linq-to-xml.md b/docs/visual-basic/programming-guide/concepts/linq/deferred-execution-and-lazy-evaluation-in-linq-to-xml.md index 9fa2e6a7d47d7..5e11dcc6a0567 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/deferred-execution-and-lazy-evaluation-in-linq-to-xml.md +++ b/docs/visual-basic/programming-guide/concepts/linq/deferred-execution-and-lazy-evaluation-in-linq-to-xml.md @@ -23,7 +23,7 @@ Query and axis operations are often implemented to use deferred execution. This ## Deferred Execution Deferred execution means that the evaluation of an expression is delayed until its *realized* value is actually required. Deferred execution can greatly improve performance when you have to manipulate large data collections, especially in programs that contain a series of chained queries or manipulations. In the best case, deferred execution enables only a single iteration through the source collection. - The LINQ technologies make extensive use of deferred execution in both the members of core classes and in the extension methods in the various LINQ namespaces, such as . + The LINQ technologies make extensive use of deferred execution in both the members of core classes and in the extension methods in the various LINQ namespaces, such as . ## Eager vs. Lazy Evaluation When you write a method that implements deferred execution, you also have to decide whether to implement the method using lazy evaluation or eager evaluation. diff --git a/docs/visual-basic/programming-guide/concepts/linq/element-operations.md b/docs/visual-basic/programming-guide/concepts/linq/element-operations.md index d5aafb669a49f..c3fbfeac7b90a 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/element-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/element-operations.md @@ -31,14 +31,14 @@ Element operations return a single, specific element from a sequence. |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|ElementAt|Returns the element at a specified index in a collection.|Not applicable.|

| -|ElementAtOrDefault|Returns the element at a specified index in a collection or a default value if the index is out of range.|Not applicable.|

| -|First|Returns the first element of a collection, or the first element that satisfies a condition.|Not applicable.|

| -|FirstOrDefault|Returns the first element of a collection, or the first element that satisfies a condition. Returns a default value if no such element exists.|Not applicable.|



| -|Last|Returns the last element of a collection, or the last element that satisfies a condition.|Not applicable.|

| -|LastOrDefault|Returns the last element of a collection, or the last element that satisfies a condition. Returns a default value if no such element exists.|Not applicable.|

| -|Single|Returns the only element of a collection, or the only element that satisfies a condition.|Not applicable.|

| -|SingleOrDefault|Returns the only element of a collection, or the only element that satisfies a condition. Returns a default value if no such element exists or the collection does not contain exactly one element.|Not applicable.|

| +|ElementAt|Returns the element at a specified index in a collection.|Not applicable.|

| +|ElementAtOrDefault|Returns the element at a specified index in a collection or a default value if the index is out of range.|Not applicable.|

| +|First|Returns the first element of a collection, or the first element that satisfies a condition.|Not applicable.|

| +|FirstOrDefault|Returns the first element of a collection, or the first element that satisfies a condition. Returns a default value if no such element exists.|Not applicable.|



| +|Last|Returns the last element of a collection, or the last element that satisfies a condition.|Not applicable.|

| +|LastOrDefault|Returns the last element of a collection, or the last element that satisfies a condition. Returns a default value if no such element exists.|Not applicable.|

| +|Single|Returns the only element of a collection, or the only element that satisfies a condition.|Not applicable.|

| +|SingleOrDefault|Returns the only element of a collection, or the only element that satisfies a condition. Returns a default value if no such element exists or the collection does not contain exactly one element.|Not applicable.|

| ## See Also diff --git a/docs/visual-basic/programming-guide/concepts/linq/equality-operations.md b/docs/visual-basic/programming-guide/concepts/linq/equality-operations.md index bb525c60d1700..8e7396b3fbb42 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/equality-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/equality-operations.md @@ -29,7 +29,7 @@ Two sequences whose corresponding elements are equal and which have the same num |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|SequenceEqual|Determines whether two sequences are equal by comparing elements in a pair-wise manner.|Not applicable.|

| +|SequenceEqual|Determines whether two sequences are equal by comparing elements in a pair-wise manner.|Not applicable.|

| ## See Also diff --git a/docs/visual-basic/programming-guide/concepts/linq/example-that-outputs-office-open-xml-document-parts.md b/docs/visual-basic/programming-guide/concepts/linq/example-that-outputs-office-open-xml-document-parts.md index f6cbf68616a16..7bf421970376c 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/example-that-outputs-office-open-xml-document-parts.md +++ b/docs/visual-basic/programming-guide/concepts/linq/example-that-outputs-office-open-xml-document-parts.md @@ -23,7 +23,7 @@ This topic shows how to open an Office Open XML document and access parts within ## Example The following example opens an Office Open XML document, and prints the document part and the style part to the console. - This example uses classes from the WindowsBase assembly. It uses types in the namespace. + This example uses classes from the WindowsBase assembly. It uses types in the namespace. ```vb Const fileName As String = "SampleDoc.docx" diff --git a/docs/visual-basic/programming-guide/concepts/linq/filtering-data.md b/docs/visual-basic/programming-guide/concepts/linq/filtering-data.md index 5500905aaae6b..944ec20f77ae0 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/filtering-data.md +++ b/docs/visual-basic/programming-guide/concepts/linq/filtering-data.md @@ -35,8 +35,8 @@ Filtering refers to the operation of restricting the result set to contain only |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|OfType|Selects values, depending on their ability to be cast to a specified type.|Not applicable.|

| -|Where|Selects values that are based on a predicate function.|`Where`|

| +|OfType|Selects values, depending on their ability to be cast to a specified type.|Not applicable.|

| +|Where|Selects values that are based on a predicate function.|`Where`|

| ## Query Expression Syntax Example The following example uses the `Where` to filter from an array those strings that have a specific length. diff --git a/docs/visual-basic/programming-guide/concepts/linq/finding-text-in-word-documents.md b/docs/visual-basic/programming-guide/concepts/linq/finding-text-in-word-documents.md index aeb302be7e9e2..aa1612d837bdd 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/finding-text-in-word-documents.md +++ b/docs/visual-basic/programming-guide/concepts/linq/finding-text-in-word-documents.md @@ -25,7 +25,7 @@ This topic extends the previous queries to do something useful: find all occurre For instructions for creating the source document for this example, see [Creating the Source Office Open XML Document (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/creating-the-source-office-open-xml-document.md). - This example uses classes found in the WindowsBase assembly. It uses types in the namespace. + This example uses classes found in the WindowsBase assembly. It uses types in the namespace. ```vb Imports diff --git a/docs/visual-basic/programming-guide/concepts/linq/finding-the-default-paragraph-style.md b/docs/visual-basic/programming-guide/concepts/linq/finding-the-default-paragraph-style.md index d8844e026d09a..eecd8e906b758 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/finding-the-default-paragraph-style.md +++ b/docs/visual-basic/programming-guide/concepts/linq/finding-the-default-paragraph-style.md @@ -25,9 +25,9 @@ The first task in the Manipulating Information in a WordprocessingML Document tu ### Description The following example opens an Office Open XML WordprocessingML document, finds the document and style parts of the package, and then executes a query that finds the default style name. For information about Office Open XML document packages, and the parts they consist of, see [Details of Office Open XML WordprocessingML Documents (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/details-of-office-open-xml-wordprocessingml-documents.md). - The query finds a node named `w:style` that has an attribute named `w:type` with a value of "paragraph", and also has an attribute named `w:default` with a value of "1". Because there will be only one XML node with these attributes, the query uses the operator to convert a collection to a singleton. It then gets the value of the attribute with the name `w:styleId`. + The query finds a node named `w:style` that has an attribute named `w:type` with a value of "paragraph", and also has an attribute named `w:default` with a value of "1". Because there will be only one XML node with these attributes, the query uses the operator to convert a collection to a singleton. It then gets the value of the attribute with the name `w:styleId`. - This example uses classes from the WindowsBase assembly. It uses types in the namespace. + This example uses classes from the WindowsBase assembly. It uses types in the namespace. ### Code diff --git a/docs/visual-basic/programming-guide/concepts/linq/generation-operations.md b/docs/visual-basic/programming-guide/concepts/linq/generation-operations.md index 6f45952918446..7f802bc43c08e 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/generation-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/generation-operations.md @@ -31,10 +31,10 @@ Generation refers to creating a new sequence of values. |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|DefaultIfEmpty|Replaces an empty collection with a default valued singleton collection.|Not applicable.|

| -|Empty|Returns an empty collection.|Not applicable.|| -|Range|Generates a collection that contains a sequence of numbers.|Not applicable.|| -|Repeat|Generates a collection that contains one repeated value.|Not applicable.|| +|DefaultIfEmpty|Replaces an empty collection with a default valued singleton collection.|Not applicable.|

| +|Empty|Returns an empty collection.|Not applicable.|| +|Range|Generates a collection that contains a sequence of numbers.|Not applicable.|| +|Repeat|Generates a collection that contains one repeated value.|Not applicable.|| ## See Also diff --git a/docs/visual-basic/programming-guide/concepts/linq/grouping-data.md b/docs/visual-basic/programming-guide/concepts/linq/grouping-data.md index 7c178394ddcdf..e168632b2b2d6 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/grouping-data.md +++ b/docs/visual-basic/programming-guide/concepts/linq/grouping-data.md @@ -35,8 +35,8 @@ Grouping refers to the operation of putting data into groups so that the element |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|GroupBy|Groups elements that share a common attribute. Each group is represented by an object.|`Group … By … Into …`|

| -|ToLookup|Inserts elements into a (a one-to-many dictionary) based on a key selector function.|Not applicable.|| +|GroupBy|Groups elements that share a common attribute. Each group is represented by an object.|`Group … By … Into …`|

| +|ToLookup|Inserts elements into a (a one-to-many dictionary) based on a key selector function.|Not applicable.|| ## Query Expression Syntax Example The following code example uses the `Group By` clause to group integers in a list according to whether they are even or odd. diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-catch-parsing-errors.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-catch-parsing-errors.md index 501785aca02c7..115fdf6c2bf4f 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-catch-parsing-errors.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-catch-parsing-errors.md @@ -25,7 +25,7 @@ translation.priority.mt: # How to: Catch Parsing Errors (Visual Basic) This topic shows how to detect badly formed or invalid XML. - [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] is implemented using . If badly formed or invalid XML is passed to [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)], the underlying class will throw an exception. The various methods that parse XML, such as , do not catch the exception; the exception can then be caught by your application. + [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] is implemented using . If badly formed or invalid XML is passed to [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)], the underlying class will throw an exception. The various methods that parse XML, such as , do not catch the exception; the exception can then be caught by your application. Note that you cannot get parse errors if you use XML literals. The Visual Basic compiler will catch errors of badly formed or invalid XML. @@ -52,7 +52,7 @@ End Try The 'Contacts' start tag on line 1 does not match the end tag of 'Contcts'. Line 5, position 13. ``` - For information about the exceptions that you can expect the , , , and methods to throw, see the documentation. + For information about the exceptions that you can expect the , , , and methods to throw, see the documentation. ## See Also [Parsing XML (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/parsing-xml.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-chain-axis-method-calls-linq-to-xml.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-chain-axis-method-calls-linq-to-xml.md index 489dae0ed866e..b4b420625dd34 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-chain-axis-method-calls-linq-to-xml.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-chain-axis-method-calls-linq-to-xml.md @@ -20,10 +20,10 @@ ms.author: dotnetcontent # How to: Chain Axis Method Calls (LINQ to XML) (Visual Basic) A common pattern that you will use in your code is to call an axis method, then call one of the extension method axes. - There are two axes with the name of `Elements` that return a collection of elements: the method and the method. You can combine these two axes to find all elements of a specified name at a given depth in the tree. + There are two axes with the name of `Elements` that return a collection of elements: the method and the method. You can combine these two axes to find all elements of a specified name at a given depth in the tree. ## Example - This example uses and to find all `Name` elements in all `Address` elements in all `PurchaseOrder` elements. + This example uses and to find all `Name` elements in all `Address` elements in all `PurchaseOrder` elements. This example uses the following XML document: [Sample XML File: Multiple Purchase Orders (LINQ to XML)](../../../../visual-basic/programming-guide/concepts/linq/sample-xml-file-multiple-purchase-orders-linq-to-xml.md). @@ -48,7 +48,7 @@ Next Jessica Arnold ``` - This works because one of the implementations of the `Elements` axis is as an extension method on of . derives from , so you can call the method on the results of a call to the method. + This works because one of the implementations of the `Elements` axis is as an extension method on of . derives from , so you can call the method on the results of a call to the method. ## Example Sometimes you want to retrieve all elements at a particular element depth when there might or might not be intervening ancestors. For example, in the following document, you might want to retrieve all the `ConfigParameter` elements that are children of the `Customer` element, but not the `ConfigParameter` that is a child of the `Root` element. @@ -75,7 +75,7 @@ Next ``` - To do this, you can use the axis, as follows: + To do this, you can use the axis, as follows: ```vb Dim root As XElement = XElement.Load("Irregular.xml") diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-change-the-namespace-for-an-entire-xml-tree.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-change-the-namespace-for-an-entire-xml-tree.md index 28cdfd633ffa4..b989f051efa21 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-change-the-namespace-for-an-entire-xml-tree.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-change-the-namespace-for-an-entire-xml-tree.md @@ -18,7 +18,7 @@ ms.author: dotnetcontent --- # How to: Change the Namespace for an Entire XML Tree (Visual Basic) -You sometimes have to programmatically change the namespace for an element or an attribute. LINQ to XML makes this easy. The property can be set. The property cannot be set, but you can easily copy the attributes into a , remove the existing attributes, and then add new attributes that are in the new desired namespace. +You sometimes have to programmatically change the namespace for an element or an attribute. LINQ to XML makes this easy. The property can be set. The property cannot be set, but you can easily copy the attributes into a , remove the existing attributes, and then add new attributes that are in the new desired namespace. For more information, see [Working with XML Namespaces (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/working-with-xml-namespaces.md). diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-filter-on-an-optional-element.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-filter-on-an-optional-element.md index a8ed1239b4af3..51e4cd9d32c26 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-filter-on-an-optional-element.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-filter-on-an-optional-element.md @@ -115,9 +115,9 @@ Child Four Text ``` ## See Also - - - + + + [Basic Queries (LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/basic-queries-linq-to-xml.md) [XML Child Axis Property](../../../../visual-basic/language-reference/xml-axis/xml-child-axis-property.md) [XML Attribute Axis Property](../../../../visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-find-preceding-siblings-xpath-linq-to-xml.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-find-preceding-siblings-xpath-linq-to-xml.md index 6b1b955696e07..7d5ee0c1b21d4 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-find-preceding-siblings-xpath-linq-to-xml.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-find-preceding-siblings-xpath-linq-to-xml.md @@ -18,13 +18,13 @@ ms.author: dotnetcontent --- # How to: Find Preceding Siblings (XPath-LINQ to XML) (Visual Basic) -This topic compares the XPath `preceding-sibling` axis to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] child axis. +This topic compares the XPath `preceding-sibling` axis to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] child axis. The XPath expression is: `preceding-sibling::*` - Note that the results of both and are in document order. + Note that the results of both and are in document order. ## Example The following example finds the `FullAddress` element, and then retrieves the previous elements using the `preceding-sibling` axis. diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-load-xml-from-a-file.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-load-xml-from-a-file.md index 754c1a67c89bd..16ca76dfac0ca 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-load-xml-from-a-file.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-load-xml-from-a-file.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # How to: Load XML from a File (Visual Basic) -This topic shows how to load XML from a URI by using the method. +This topic shows how to load XML from a URI by using the method. ## Example The following example shows how to load an XML document from a file. The following example loads books.xml and outputs the XML tree to the console. diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-modify-an-office-open-xml-document.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-modify-an-office-open-xml-document.md index 34edd4b269e2c..420fcf5059497 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-modify-an-office-open-xml-document.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-modify-an-office-open-xml-document.md @@ -25,7 +25,7 @@ This topic presents an example that opens an Office Open XML document, modifies ## Example This example finds the first paragraph element in the document. It retrieves the text from the paragraph, and then deletes all text runs in the paragraph. It creates a new text run that consists of the first paragraph text that has been converted to upper case. It then serializes the changed XML into the Open XML package and closes it. - This example uses classes found in the WindowsBase assembly. It uses types in the namespace. + This example uses classes found in the WindowsBase assembly. It uses types in the namespace. ```vb Imports diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-linq-to-xml-using-xpath.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-linq-to-xml-using-xpath.md index 681176749acfe..c1138e94e5a1a 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-query-linq-to-xml-using-xpath.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-query-linq-to-xml-using-xpath.md @@ -18,7 +18,7 @@ ms.author: dotnetcontent --- # How to: Query LINQ to XML Using XPath (Visual Basic) -This topic introduces the extension methods that enable you to query an XML tree by using XPath. For detailed information about using these extension methods, see . +This topic introduces the extension methods that enable you to query an XML tree by using XPath. For detailed information about using these extension methods, see . Unless you have a very specific reason for querying using XPath, such as extensive use of legacy code, using XPath with LINQ to XML is not recommended. XPath queries will not perform as well as [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] queries. diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-read-and-write-an-encoded-document.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-read-and-write-an-encoded-document.md index dafec288dbb4a..f33016fff4070 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-read-and-write-an-encoded-document.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-read-and-write-an-encoded-document.md @@ -90,5 +90,5 @@ Encoding of loaded document is:utf-16 ``` ## See Also - + [Advanced LINQ to XML Programming (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/advanced-linq-to-xml-programming.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-paragraphs-from-an-office-open-xml-document.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-paragraphs-from-an-office-open-xml-document.md index e6b721b198061..bfb94eb7cd6cc 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-paragraphs-from-an-office-open-xml-document.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-paragraphs-from-an-office-open-xml-document.md @@ -29,7 +29,7 @@ This topic presents an example that opens an Office Open XML document, and retri For a detailed tutorial that explains how this example works, see [Pure Functional Transformations of XML (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/pure-functional-transformations-of-xml.md). - This example uses classes found in the WindowsBase assembly. It uses types in the namespace. + This example uses classes found in the WindowsBase assembly. It uses types in the namespace. ```vb Imports diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-the-shallow-value-of-an-element.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-the-shallow-value-of-an-element.md index b33d0756682a0..293237352a5a8 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-the-shallow-value-of-an-element.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-the-shallow-value-of-an-element.md @@ -20,7 +20,7 @@ ms.author: dotnetcontent # How to: Retrieve the Shallow Value of an Element (Visual Basic) This topic shows how to get the shallow value of an element. The shallow value is the value of the specific element only, as opposed to the deep value, which includes the values of all descendent elements concatenated into a single string. - When you retrieve an element value by using either casting or the property, you retrieve the deep value. To retrieve the shallow value, you can use the `ShallowValue` extension method, as shown in the follwing example. Retrieving the shallow value is useful when you want to select elements based on their content. + When you retrieve an element value by using either casting or the property, you retrieve the deep value. To retrieve the shallow value, you can use the `ShallowValue` extension method, as shown in the follwing example. Retrieving the shallow value is useful when you want to select elements based on their content. The following example declares an extension method that retrieves the shallow value of an element. It then uses the extension method in a query to list all elements that contain a calculated value. diff --git a/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-the-value-of-an-element-linq-to-xml.md b/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-the-value-of-an-element-linq-to-xml.md index 961c026dc11b6..aa2123a79fc6a 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-the-value-of-an-element-linq-to-xml.md +++ b/docs/visual-basic/programming-guide/concepts/linq/how-to-retrieve-the-value-of-an-element-linq-to-xml.md @@ -18,9 +18,9 @@ ms.author: dotnetcontent --- # How to: Retrieve the Value of an Element (LINQ to XML) (Visual Basic) -This topic shows how to get the value of elements. There are two main ways to do this. One way is to cast an or an to the desired type. The explicit conversion operator then converts the contents of the element or attribute to the specified type and assigns it to your variable. Alternatively, you can use the property or the property. +This topic shows how to get the value of elements. There are two main ways to do this. One way is to cast an or an to the desired type. The explicit conversion operator then converts the contents of the element or attribute to the specified type and assigns it to your variable. Alternatively, you can use the property or the property. - With Visual Basic, the best approach is to use the property. + With Visual Basic, the best approach is to use the property. ## Example To retrieve the value of an element, you just cast the object to your desired type. You can always cast an element to a string, as follows: diff --git a/docs/visual-basic/programming-guide/concepts/linq/join-operations.md b/docs/visual-basic/programming-guide/concepts/linq/join-operations.md index 49e3dd3c716f1..17f8db06a4638 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/join-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/join-operations.md @@ -37,8 +37,8 @@ A *join* of two data sources is the association of objects in one data source wi |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|Join|Joins two sequences based on key selector functions and extracts pairs of values.|`From x In …, y In … Where x.a = y.a`

-or-

`Join … [As …]In … On …`|

| -|GroupJoin|Joins two sequences based on key selector functions and groups the resulting matches for each element.|`Group Join … In … On …`|

| +|Join|Joins two sequences based on key selector functions and extracts pairs of values.|`From x In …, y In … Where x.a = y.a`

-or-

`Join … [As …]In … On …`|

| +|GroupJoin|Joins two sequences based on key selector functions and groups the resulting matches for each element.|`Group Join … In … On …`|

| ## See Also diff --git a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-axes-overview.md b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-axes-overview.md index ea6e47bf5e9c2..0a4d4b5c46704 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-axes-overview.md +++ b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-axes-overview.md @@ -33,34 +33,34 @@ After you have created an XML tree or loaded an XML document into an XML tree, y |Method|Description| |------------|-----------------| -||Returns an of of the ancestors of this element. An overload returns an of of the ancestors that have the specified .| -||Returns an of of the descendants of this element. An overload returns an of of the descendants that have the specified .| -||Returns an of of the child elements of this element. An overload returns an of of the child elements that have the specified .| -||Returns an of of the elements that come after this element. An overload returns an of of the elements after this element that have the specified .| -||Returns an of of the elements that come before this element. An overload returns an of of the elements before this element that have the specified .| -||Returns an of of this element and its ancestors. An overload returns an of of the elements that have the specified .| -||Returns an of of this element and its descendants. An overload returns an of of the elements that have the specified .| +||Returns an of of the ancestors of this element. An overload returns an of of the ancestors that have the specified .| +||Returns an of of the descendants of this element. An overload returns an of of the descendants that have the specified .| +||Returns an of of the child elements of this element. An overload returns an of of the child elements that have the specified .| +||Returns an of of the elements that come after this element. An overload returns an of of the elements after this element that have the specified .| +||Returns an of of the elements that come before this element. An overload returns an of of the elements before this element that have the specified .| +||Returns an of of this element and its ancestors. An overload returns an of of the elements that have the specified .| +||Returns an of of this element and its descendants. An overload returns an of of the elements that have the specified .| ## Method for Retrieving a Single Element The following method retrieves a single child from an object. |Method|Description| |------------|-----------------| -||Returns the first child object that has the specified .| +||Returns the first child object that has the specified .| ## Method for Retrieving a Collection of Attributes The following method retrieves attributes from an object. |Method|Description| |------------|-----------------| -||Returns an of of all of the attributes.| +||Returns an of of all of the attributes.| ## Method for Retrieving a Single Attribute The following method retrieves a single attribute from an object. |Method|Description| |------------|-----------------| -||Returns the that has the specified .| +||Returns the that has the specified .| ## See Also [LINQ to XML Axes (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/linq-to-xml-axes.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md index 072041fae4328..73a1796cc28c7 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md +++ b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-for-xpath-users.md @@ -16,7 +16,7 @@ ms.author: dotnetcontent This set of topics show a number of XPath expressions and their [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] equivalents. - All of the examples use the XPath functionality in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] that is made available by the extension methods in . The examples execute both the XPath expression and the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] expression. Each example then compares the results of both queries, validating that the XPath expression is functionally equivalent to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] query. As both types of queries return nodes from the same XML tree, the query result comparison is made using referential identity. + All of the examples use the XPath functionality in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] that is made available by the extension methods in . The examples execute both the XPath expression and the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] expression. Each example then compares the results of both queries, validating that the XPath expression is functionally equivalent to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] query. As both types of queries return nodes from the same XML tree, the query result comparison is made using referential identity. ## In This Section @@ -30,7 +30,7 @@ This set of topics show a number of XPath expressions and their [!INCLUDE[sqltec |[How to: Filter on an Attribute (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-filter-on-an-attribute-xpath-linq-to-xml.md)|Compares how to get the descendant elements with a specified name, and with an attribute with a specified value with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`".//Address[@Type='Shipping']"`| |[How to: Find Related Elements (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-related-elements-xpath-linq-to-xml.md)|Compares how to get an element selecting on an attribute that is referred to by the value of another element with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`".//Customer[@CustomerID=/Root/Orders/Order[12]/CustomerID]"`| |[How to: Find Elements in a Namespace (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-elements-in-a-namespace.md)|Compares the use of the XPath class with the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] property of the class for working with XML namespaces.

The associated XPath expression is:`"./aw:*"`| -|[How to: Find Preceding Siblings (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-preceding-siblings-xpath-linq-to-xml.md)|Compares the XPath `preceding-sibling` axis to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] child axis.

The associated XPath expression is:`"preceding-sibling::*"`| +|[How to: Find Preceding Siblings (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-preceding-siblings-xpath-linq-to-xml.md)|Compares the XPath `preceding-sibling` axis to the [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] child axis.

The associated XPath expression is:`"preceding-sibling::*"`| |[How to: Find Descendants of a Child Element (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-descendants-of-a-child-element-xpath-linq-to-xml.md)|Compares how to get the descendant elements of a child element with a particular name with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"./Paragraph//Text/text()"`| |[How to: Find a Union of Two Location Paths (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-a-union-of-two-location-paths-xpath.md)|Compares the use of the union operator, |, in XPath with the standard query operator in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:"//Category|//Price"| |[How to: Find Sibling Nodes (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-sibling-nodes-xpath-linq-to-xml.md)|Compares how to find all siblings of a node that have a specific name with XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"../Book"`| @@ -41,6 +41,6 @@ This set of topics show a number of XPath expressions and their [!INCLUDE[sqltec |[How to: Find the Immediate Preceding Sibling (XPath-LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/how-to-find-the-immediate-preceding-sibling-xpath-linq-to-xml.md)|Compares how to find the immediate preceding sibling of a node using XPath and [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)].

The associated XPath expression is:`"preceding-sibling::*[1]"`| ## See Also - + [Querying XML Trees (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/querying-xml-trees.md) [Process XML Data Using the XPath Data Model](../../../../standard/data/xml/process-xml-data-using-the-xpath-data-model.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-security.md b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-security.md index 43bbb9a672fe2..59878bf73902f 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-security.md +++ b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-security.md @@ -35,9 +35,9 @@ This topic describes security issues associated with LINQ to XML. In addition, i XML is intrinsically vulnerable to denial of service attacks because documents are unbounded in size, depth, element name size, and more. Regardless of the component that you use to process XML, you should always be prepared to recycle the application domain if it uses excessive resources. ## Mitigation of XML, XSD, XPath, and XSLT Attacks - LINQ to XML is built upon and . LINQ to XML supports XSD and XPath through extension methods in the and namespaces. Using the , , and classes in conjunction with LINQ to XML, you can invoke XSLT to transform XML trees. + LINQ to XML is built upon and . LINQ to XML supports XSD and XPath through extension methods in the and namespaces. Using the , , and classes in conjunction with LINQ to XML, you can invoke XSLT to transform XML trees. - If you are operating in a less secure environment, there are a number of security issues that are associated with XML and the use of the classes in , , , and . These issues include, but are not limited to, the following: + If you are operating in a less secure environment, there are a number of security issues that are associated with XML and the use of the classes in , , , and . These issues include, but are not limited to, the following: - XSD, XPath, and XSLT are string-based languages in which you can specify operations that consume a lot of time or memory. It is the responsibility of application programmers who take XSD, XPath, or XSLT strings from untrusted sources to validate that the strings are not malicious, or to monitor and mitigate the possibility that evaluating these strings will lead to excessive system resource consumption. @@ -74,9 +74,9 @@ This topic describes security issues associated with LINQ to XML. In addition, i ### Do Not Call CodeAccessPermissions.Assert in an Event Handler An assembly can have lesser or greater permissions. An assembly that has greater permissions has greater control over the computer and its environments. - If code in an assembly with greater permissions calls in an event handler, and then the XML tree is passed to a malicious assembly that has restricted permissions, the malicious assembly can cause an event to be raised. Because the event runs code that is in the assembly with greater permissions, the malicious assembly would then be operating with elevated privileges. + If code in an assembly with greater permissions calls in an event handler, and then the XML tree is passed to a malicious assembly that has restricted permissions, the malicious assembly can cause an event to be raised. Because the event runs code that is in the assembly with greater permissions, the malicious assembly would then be operating with elevated privileges. - Microsoft recommends that you never call in an event handler. + Microsoft recommends that you never call in an event handler. ### DTDs are Not Secure Entities in DTDs are inherently not secure. It is possible for a malicious XML document that contains a DTD to cause the parser to use all memory and CPU time, causing a denial of service attack. Therefore, in LINQ to XML, DTD processing is turned off by default. You should not accept DTDs from untrusted sources. @@ -86,12 +86,12 @@ This topic describes security issues associated with LINQ to XML. In addition, i ### Avoid Excessive Buffer Allocation Application developers should be aware that extremely large data sources can lead to resource exhaustion and denial of service attacks. - If a malicious user submits or uploads a very large XML document, it could cause LINQ to XML to consume excessive system resources. This can constitute a denial of service attack. To prevent this, you can set the property, and create a reader that is then limited in the size of document that it can load. You then use the reader to create the XML tree. + If a malicious user submits or uploads a very large XML document, it could cause LINQ to XML to consume excessive system resources. This can constitute a denial of service attack. To prevent this, you can set the property, and create a reader that is then limited in the size of document that it can load. You then use the reader to create the XML tree. - For example, if you know that the maximum expected size of your XML documents coming from an untrusted source will be less than 50K bytes, set to 100,000. This will not encumber your processing of XML documents, and at the same time it will mitigate denial of service threats where documents might be uploaded that would consume large amounts of memory. + For example, if you know that the maximum expected size of your XML documents coming from an untrusted source will be less than 50K bytes, set to 100,000. This will not encumber your processing of XML documents, and at the same time it will mitigate denial of service threats where documents might be uploaded that would consume large amounts of memory. ### Avoid Excess Entity Expansion - One of the known denial of service attacks when using a DTD is a document that causes excessive entity expansion. To prevent this, you can set the property, and create a reader that is then limited in the number of characters that result from entity expansion. You then use the reader to create the XML tree. + One of the known denial of service attacks when using a DTD is a document that causes excessive entity expansion. To prevent this, you can set the property, and create a reader that is then limited in the number of characters that result from entity expansion. You then use the reader to create the XML tree. ### Limit the Depth of the XML Hierarchy One possible denial of service attack is when a document is submitted that has excessive depth of hierarchy. To prevent this, you can wrap a in your own class that counts the depth of elements. If the depth exceeds a predetermined reasonable level, you can terminate the processing of the malicious document. diff --git a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-vs-dom.md b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-vs-dom.md index 57f2ad633a66e..7231ac65d120d 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-vs-dom.md +++ b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml-vs-dom.md @@ -126,7 +126,7 @@ doc.AppendChild(name) [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] does not provide an equivalent for the `XmlDocumentFragment` class. In many cases, however, the `XmlDocumentFragment` concept can be handled by the result of a query that is typed as of , or of . ## Support for XPathNavigator - [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] provides support for through extension methods in the namespace. For more information, see . + [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] provides support for through extension methods in the namespace. For more information, see . ## Support for White Space and Indentation [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] handles white space more simply than the DOM. @@ -141,7 +141,7 @@ doc.AppendChild(name) [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] elements support an extensible set of annotations. This is useful for tracking miscellaneous information about an element, such as schema information, information about whether the element is bound to a UI, or any other kind of application-specific information. For more information, see [LINQ to XML Annotations](http://msdn.microsoft.com/library/e2f0052d-61e2-48d4-9ea4-356c9cab35d5). ## Support for Schema Information - [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] provides support for XSD validation through extension methods in the namespace. You can validate that an XML tree complies with an XSD. You can populate the XML tree with the post-schema-validation infoset (PSVI). For more information, see [How to: Validate Using XSD](http://msdn.microsoft.com/library/481a97fa-6e96-46f2-8c9a-415555fac33b) and . + [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] provides support for XSD validation through extension methods in the namespace. You can validate that an XML tree complies with an XSD. You can populate the XML tree with the post-schema-validation infoset (PSVI). For more information, see [How to: Validate Using XSD](http://msdn.microsoft.com/library/481a97fa-6e96-46f2-8c9a-415555fac33b) and . ## See Also [Getting Started (LINQ to XML)](../../../../visual-basic/programming-guide/concepts/linq/getting-started-linq-to-xml.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml.md b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml.md index a0c651f581f33..9892a2dd00616 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml.md +++ b/docs/visual-basic/programming-guide/concepts/linq/linq-to-xml.md @@ -29,7 +29,7 @@ LINQ to XML provides an in-memory XML programming interface that leverages the . ## In this Section [Getting Started (LINQ to XML)](../../../../visual-basic/programming-guide/concepts/linq/getting-started-linq-to-xml.md) - Provides introductory information about LINQ to XML, including a conceptual overview and an overview of the classes. + Provides introductory information about LINQ to XML, including a conceptual overview and an overview of the classes. [Programming Guide (LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/programming-guide-linq-to-xml.md) Provides conceptual and how-to information about programming with LINQ to XML. diff --git a/docs/visual-basic/programming-guide/concepts/linq/modifying-elements-attributes-and-nodes-in-an-xml-tree.md b/docs/visual-basic/programming-guide/concepts/linq/modifying-elements-attributes-and-nodes-in-an-xml-tree.md index cef666c97d081..8c781d885d143 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/modifying-elements-attributes-and-nodes-in-an-xml-tree.md +++ b/docs/visual-basic/programming-guide/concepts/linq/modifying-elements-attributes-and-nodes-in-an-xml-tree.md @@ -24,34 +24,34 @@ The following table summarizes the methods and properties that you can use to mo |Method|Description| |------------|-----------------| -||Replaces an element with parsed XML.| -||Removes all content (child nodes and attributes) of an element.| -||Removes the attributes of an element.| -||Replaces all content (child nodes and attributes) of an element.| -||Replaces the attributes of an element.| -||Sets the value of an attribute. Creates the attribute if it doesn't exist. If the value is set to `null`, removes the attribute.| -||Sets the value of a child element. Creates the element if it doesn't exist. If the value is set to `null`, removes the element.| -||Replaces the content (child nodes) of an element with the specified text.| -||Sets the value of an element.| +||Replaces an element with parsed XML.| +||Removes all content (child nodes and attributes) of an element.| +||Removes the attributes of an element.| +||Replaces all content (child nodes and attributes) of an element.| +||Replaces the attributes of an element.| +||Sets the value of an attribute. Creates the attribute if it doesn't exist. If the value is set to `null`, removes the attribute.| +||Sets the value of a child element. Creates the element if it doesn't exist. If the value is set to `null`, removes the element.| +||Replaces the content (child nodes) of an element with the specified text.| +||Sets the value of an element.| The following methods modify an . |Method|Description| |------------|-----------------| -||Sets the value of an attribute.| -||Sets the value of an attribute.| +||Sets the value of an attribute.| +||Sets the value of an attribute.| The following methods modify an (including an or ). |Method|Description| |------------|-----------------| -||Replaces a node with new content.| +||Replaces a node with new content.| The following methods modify an (an or ). |Method|Description| |------------|-----------------| -||Replaces the children nodes with new content.| +||Replaces the children nodes with new content.| ## See Also [Modifying XML Trees (LINQ to XML) (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/modifying-xml-trees-linq-to-xml.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/partitioning-data.md b/docs/visual-basic/programming-guide/concepts/linq/partitioning-data.md index e508163254767..ecd8680468fad 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/partitioning-data.md +++ b/docs/visual-basic/programming-guide/concepts/linq/partitioning-data.md @@ -35,10 +35,10 @@ Partitioning in LINQ refers to the operation of dividing an input sequence into |Operator Name|Description|Visual Basic Query Expression Syntax|More Information| |-------------------|-----------------|------------------------------------------|----------------------| -|Skip|Skips elements up to a specified position in a sequence.|`Skip`|

| -|SkipWhile|Skips elements based on a predicate function until an element does not satisfy the condition.|`Skip While`|

| -|Take|Takes elements up to a specified position in a sequence.|`Take`|

| -|TakeWhile|Takes elements based on a predicate function until an element does not satisfy the condition.|`Take While`|

| +|Skip|Skips elements up to a specified position in a sequence.|`Skip`|

| +|SkipWhile|Skips elements based on a predicate function until an element does not satisfy the condition.|`Skip While`|

| +|Take|Takes elements up to a specified position in a sequence.|`Take`|

| +|TakeWhile|Takes elements based on a predicate function until an element does not satisfy the condition.|`Take While`|

| ## Query Expression Syntax Examples diff --git a/docs/visual-basic/programming-guide/concepts/linq/preserving-white-space-while-loading-or-parsing-xml.md b/docs/visual-basic/programming-guide/concepts/linq/preserving-white-space-while-loading-or-parsing-xml.md index c772ef537ead0..1af79bd00fe29 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/preserving-white-space-while-loading-or-parsing-xml.md +++ b/docs/visual-basic/programming-guide/concepts/linq/preserving-white-space-while-loading-or-parsing-xml.md @@ -34,13 +34,13 @@ This topic describes how to control the white space behavior of [!INCLUDE[sqltec ## Behavior of Methods that Populate XML Trees The following methods in the and classes populate an XML tree. You can populate an XML tree from a file, a , an , or a string: -- +- -- +- -- +- -- +- If the method does not take as an argument, the method will not preserve insignificant white space. diff --git a/docs/visual-basic/programming-guide/concepts/linq/preserving-white-space-while-serializing.md b/docs/visual-basic/programming-guide/concepts/linq/preserving-white-space-while-serializing.md index c40f090793f8c..84a6e99964158 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/preserving-white-space-while-serializing.md +++ b/docs/visual-basic/programming-guide/concepts/linq/preserving-white-space-while-serializing.md @@ -32,13 +32,13 @@ This topic describes how to control white space when serializing an XML tree. ## White Space Behavior of Methods that Serialize XML Trees The following methods in the and classes serialize an XML tree. You can serialize an XML tree to a file, a , or an . The `ToString` method serializes to a string. -- +- -- +- -- +- -- +- If the method does not take as an argument, then the method will format (indent) the serialized XML. In this case, all insignificant white space in the XML tree is discarded. diff --git a/docs/visual-basic/programming-guide/concepts/linq/projecting-xml-in-a-different-shape.md b/docs/visual-basic/programming-guide/concepts/linq/projecting-xml-in-a-different-shape.md index 32a4d4670e72b..3f956bd2a18d4 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/projecting-xml-in-a-different-shape.md +++ b/docs/visual-basic/programming-guide/concepts/linq/projecting-xml-in-a-different-shape.md @@ -27,7 +27,7 @@ This topic shows an example of projecting XML that is in a different shape than For instructions for creating the source document for this example, see [Creating the Source Office Open XML Document (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/creating-the-source-office-open-xml-document.md). - This example uses classes from the WindowsBase assembly. It uses types in the namespace. + This example uses classes from the WindowsBase assembly. It uses types in the namespace. ```vb Imports diff --git a/docs/visual-basic/programming-guide/concepts/linq/projection-operations.md b/docs/visual-basic/programming-guide/concepts/linq/projection-operations.md index 6fae80302cbee..26384ce2242d7 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/projection-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/projection-operations.md @@ -31,8 +31,8 @@ Projection refers to the operation of transforming an object into a new form tha |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|Select|Projects values that are based on a transform function.|`Select`|

| -|SelectMany|Projects sequences of values that are based on a transform function and then flattens them into one sequence.|Use multiple `From` clauses|

| +|Select|Projects values that are based on a transform function.|`Select`|

| +|SelectMany|Projects sequences of values that are based on a transform function and then flattens them into one sequence.|Use multiple `From` clauses|

| ## Query Expression Syntax Examples diff --git a/docs/visual-basic/programming-guide/concepts/linq/quantifier-operations.md b/docs/visual-basic/programming-guide/concepts/linq/quantifier-operations.md index bdba2f1a18c57..f28e877a48e32 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/quantifier-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/quantifier-operations.md @@ -35,9 +35,9 @@ Quantifier operations return a value that indicates whethe |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|All|Determines whether all the elements in a sequence satisfy a condition.|`Aggregate … In … Into All(…)`|

| -|Any|Determines whether any elements in a sequence satisfy a condition.|`Aggregate … In … Into Any()`|

| -|Contains|Determines whether a sequence contains a specified element.|Not applicable.|

| +|All|Determines whether all the elements in a sequence satisfy a condition.|`Aggregate … In … Into All(…)`|

| +|Any|Determines whether any elements in a sequence satisfy a condition.|`Aggregate … In … Into Any()`|

| +|Contains|Determines whether a sequence contains a specified element.|Not applicable.|

| ## Query Expression Syntax Examples These examples use the `Aggregate` clause in Visual Basic as part of the filtering condition in a LINQ query. diff --git a/docs/visual-basic/programming-guide/concepts/linq/querying-an-xdocument-vs-querying-an-xelement.md b/docs/visual-basic/programming-guide/concepts/linq/querying-an-xdocument-vs-querying-an-xelement.md index 752a8f544067a..b30948c1608e5 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/querying-an-xdocument-vs-querying-an-xelement.md +++ b/docs/visual-basic/programming-guide/concepts/linq/querying-an-xdocument-vs-querying-an-xelement.md @@ -18,10 +18,10 @@ ms.author: dotnetcontent --- # Querying an XDocument vs. Querying an XElement (Visual Basic) -When you load a document via , you will notice that you have to write queries slightly differently than when you load via . +When you load a document via , you will notice that you have to write queries slightly differently than when you load via . ## Comparison of XDocument.Load and XElement.Load - When you load an XML document into an via , the at the root of the XML tree contains the root element of the loaded document. However, when you load the same XML document into an via , the root of the tree is an node, and the root element of the loaded document is the one allowed child node of the . The [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] axes operate relative to the root node. + When you load an XML document into an via , the at the root of the XML tree contains the root element of the loaded document. However, when you load the same XML document into an via , the root of the tree is an node, and the root element of the loaded document is the one allowed child node of the . The [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] axes operate relative to the root node. This first example loads an XML tree using . It then queries for the child elements of the root of the tree. diff --git a/docs/visual-basic/programming-guide/concepts/linq/refactoring-using-a-pure-function.md b/docs/visual-basic/programming-guide/concepts/linq/refactoring-using-a-pure-function.md index cb8e1fb5d3c92..4307058fd9962 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/refactoring-using-a-pure-function.md +++ b/docs/visual-basic/programming-guide/concepts/linq/refactoring-using-a-pure-function.md @@ -25,7 +25,7 @@ The following example refactors the previous example, [Refactoring Using an Exte For instructions for creating the source document for this example, see [Creating the Source Office Open XML Document (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/creating-the-source-office-open-xml-document.md). - This example uses classes from the WindowsBase assembly. It uses types in the namespace. + This example uses classes from the WindowsBase assembly. It uses types in the namespace. ```vb Imports diff --git a/docs/visual-basic/programming-guide/concepts/linq/refactoring-using-an-extension-method.md b/docs/visual-basic/programming-guide/concepts/linq/refactoring-using-an-extension-method.md index 36b2ef8265a33..96b136e19aa80 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/refactoring-using-an-extension-method.md +++ b/docs/visual-basic/programming-guide/concepts/linq/refactoring-using-an-extension-method.md @@ -29,7 +29,7 @@ This example builds on the previous example, [Retrieving the Text of the Paragra You can find instructions for creating the source document for this example in [Creating the Source Office Open XML Document (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/creating-the-source-office-open-xml-document.md). - This example uses classes from the WindowsBase assembly. It uses types in the namespace. + This example uses classes from the WindowsBase assembly. It uses types in the namespace. ```vb _ diff --git a/docs/visual-basic/programming-guide/concepts/linq/reference-linq-to-xml.md b/docs/visual-basic/programming-guide/concepts/linq/reference-linq-to-xml.md index 8da8845921418..98366bc2a4de0 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/reference-linq-to-xml.md +++ b/docs/visual-basic/programming-guide/concepts/linq/reference-linq-to-xml.md @@ -28,9 +28,9 @@ This topic contains links to the LINQ to XML reference topics. ## In This Section For reference documentation for the LINQ to XML classes, see . - For reference documentation for the extension methods that help you validate XML trees against an XSD file, see . + For reference documentation for the extension methods that help you validate XML trees against an XSD file, see . - For reference documentation for the extension methods that enable you to evaluate XPath queries on an XML tree, see . + For reference documentation for the extension methods that enable you to evaluate XPath queries on an XML tree, see . ## See Also [LINQ to XML (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/linq-to-xml.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/removing-elements-attributes-and-nodes-from-an-xml-tree.md b/docs/visual-basic/programming-guide/concepts/linq/removing-elements-attributes-and-nodes-from-an-xml-tree.md index 8304316a8088c..be3a08a7788e3 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/removing-elements-attributes-and-nodes-from-an-xml-tree.md +++ b/docs/visual-basic/programming-guide/concepts/linq/removing-elements-attributes-and-nodes-from-an-xml-tree.md @@ -25,19 +25,19 @@ You can modify an XML tree, removing elements, attributes, and other types of no |Method|Description| |------------|-----------------| -||Removes an from its parent.| -||Removes the child nodes from an .| -||Removes content and attributes from an .| -||Removes the attributes of an .| -||If you pass `null` for value, then removes the attribute.| -||If you pass `null` for value, then removes the child element.| -||Removes an from its parent.| -||Removes every attribute or element in the source collection from its parent element.| +||Removes an from its parent.| +||Removes the child nodes from an .| +||Removes content and attributes from an .| +||Removes the attributes of an .| +||If you pass `null` for value, then removes the attribute.| +||If you pass `null` for value, then removes the child element.| +||Removes an from its parent.| +||Removes every attribute or element in the source collection from its parent element.| ## Example ### Description - This example demonstrates three approaches to removing elements. First, it removes a single element. Second, it retrieves a collection of elements, materializes them using the operator, and removes the collection. Finally, it retrieves a collection of elements and removes them using the extension method. + This example demonstrates three approaches to removing elements. First, it removes a single element. Second, it retrieves a collection of elements, materializes them using the operator, and removes the collection. Finally, it retrieves a collection of elements and removes them using the extension method. For more information on the operator, see [Converting Data Types (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/converting-data-types.md). diff --git a/docs/visual-basic/programming-guide/concepts/linq/retrieving-the-paragraphs-and-their-styles.md b/docs/visual-basic/programming-guide/concepts/linq/retrieving-the-paragraphs-and-their-styles.md index 36c39ee1a6cc9..d8ed29595829c 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/retrieving-the-paragraphs-and-their-styles.md +++ b/docs/visual-basic/programming-guide/concepts/linq/retrieving-the-paragraphs-and-their-styles.md @@ -49,7 +49,7 @@ Let styleNode As XElement = para...FirstOrDefault() You can find instructions for creating the source document for this example in [Creating the Source Office Open XML Document (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/creating-the-source-office-open-xml-document.md). - This example uses classes found in the WindowsBase assembly. It uses types in the namespace. + This example uses classes found in the WindowsBase assembly. It uses types in the namespace. ```vb Imports diff --git a/docs/visual-basic/programming-guide/concepts/linq/retrieving-the-text-of-the-paragraphs.md b/docs/visual-basic/programming-guide/concepts/linq/retrieving-the-text-of-the-paragraphs.md index 1faff7373cd17..3548e77e30a63 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/retrieving-the-text-of-the-paragraphs.md +++ b/docs/visual-basic/programming-guide/concepts/linq/retrieving-the-text-of-the-paragraphs.md @@ -33,7 +33,7 @@ This example builds on the previous example, [Retrieving the Paragraphs and Thei For instructions for creating the source document for this example, see [Creating the Source Office Open XML Document (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/creating-the-source-office-open-xml-document.md). - This example uses classes from the WindowsBase assembly. It uses types in the namespace. + This example uses classes from the WindowsBase assembly. It uses types in the namespace. ```vb Imports diff --git a/docs/visual-basic/programming-guide/concepts/linq/serializing-to-an-xmlreader-invoking-xslt.md b/docs/visual-basic/programming-guide/concepts/linq/serializing-to-an-xmlreader-invoking-xslt.md index 5aec25d760b80..e219560e6bc40 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/serializing-to-an-xmlreader-invoking-xslt.md +++ b/docs/visual-basic/programming-guide/concepts/linq/serializing-to-an-xmlreader-invoking-xslt.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # Serializing to an XmlReader (Invoking XSLT) (Visual Basic) -When you use the interoperability capabilities of [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)], you can use to create an . The module that reads from this reads the nodes from the XML tree and processes them accordingly. +When you use the interoperability capabilities of [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)], you can use to create an . The module that reads from this reads the nodes from the XML tree and processes them accordingly. ## Invoking an XSLT Transformation One possible use for this method is when invoking an XSLT transformation. You can create an XML tree, create an from the XML tree, create a new document, and then create an to write into the new document. Then, you can invoke the XSLT transformation, passing in and . After the transformation successfully completes, the new XML tree is populated with the results of the transformation. diff --git a/docs/visual-basic/programming-guide/concepts/linq/serializing-to-files-textwriters-and-xmlwriters.md b/docs/visual-basic/programming-guide/concepts/linq/serializing-to-files-textwriters-and-xmlwriters.md index f18f4d7e18ef0..6f76baa51107f 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/serializing-to-files-textwriters-and-xmlwriters.md +++ b/docs/visual-basic/programming-guide/concepts/linq/serializing-to-files-textwriters-and-xmlwriters.md @@ -27,19 +27,19 @@ You can serialize XML trees to a , a and , to a string by using the `ToString` method. - If you want to suppress formatting when serializing to a string, you can use the method. + If you want to suppress formatting when serializing to a string, you can use the method. Thedefault behavior when serializing to a file is to format (indent) the resulting XML document. When you indent, the insignificant white space in the XML tree is not preserved. To serialize with formatting, use one of the overloads of the following methods that do not take as an argument: -- +- -- +- If you want the option not to indent and to preserve the insignificant white space in the XML tree, use one of the overloads of the following methods that takes as an argument: -- +- -- +- For examples, see the appropriate reference topic. diff --git a/docs/visual-basic/programming-guide/concepts/linq/serializing-with-an-xml-declaration.md b/docs/visual-basic/programming-guide/concepts/linq/serializing-with-an-xml-declaration.md index a18a354ed06c5..9ddbc1d82d72f 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/serializing-with-an-xml-declaration.md +++ b/docs/visual-basic/programming-guide/concepts/linq/serializing-with-an-xml-declaration.md @@ -26,7 +26,7 @@ translation.priority.mt: This topic describes how to control whether serialization generates an XML declaration. ## XML Declaration Generation - Serializing to a or a using the method or the method generates an XML declaration. When you serialize to an , the writer settings (specified in an object) determine whether an XML declaration is generated or not. + Serializing to a or a using the method or the method generates an XML declaration. When you serialize to an , the writer settings (specified in an object) determine whether an XML declaration is generated or not. If you are serializing to a string using the `ToString` method, the resulting XML will not include an XML declaration. diff --git a/docs/visual-basic/programming-guide/concepts/linq/set-operations.md b/docs/visual-basic/programming-guide/concepts/linq/set-operations.md index 8c9cc3a9c23a2..2fa7c461e7269 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/set-operations.md +++ b/docs/visual-basic/programming-guide/concepts/linq/set-operations.md @@ -31,25 +31,25 @@ Set operations in LINQ refer to query operations that produce a result set that |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|Distinct|Removes duplicate values from a collection.|`Distinct`|

| -|Except|Returns the set difference, which means the elements of one collection that do not appear in a second collection.|Not applicable.|

| -|Intersect|Returns the set intersection, which means elements that appear in each of two collections.|Not applicable.|

| -|Union|Returns the set union, which means unique elements that appear in either of two collections.|Not applicable.|

| +|Distinct|Removes duplicate values from a collection.|`Distinct`|

| +|Except|Returns the set difference, which means the elements of one collection that do not appear in a second collection.|Not applicable.|

| +|Intersect|Returns the set intersection, which means elements that appear in each of two collections.|Not applicable.|

| +|Union|Returns the set union, which means unique elements that appear in either of two collections.|Not applicable.|

| ## Comparison of Set Operations ### Distinct - The following illustration depicts the behavior of the method on a sequence of characters. The returned sequence contains the unique elements from the input sequence. + The following illustration depicts the behavior of the method on a sequence of characters. The returned sequence contains the unique elements from the input sequence. ![Graphic showing the behavior of Distinct().](../../../../csharp/programming-guide/concepts/linq/media/distinct.png "Distinct") ### Except - The following illustration depicts the behavior of . The returned sequence contains only the elements from the first input sequence that are not in the second input sequence. + The following illustration depicts the behavior of . The returned sequence contains only the elements from the first input sequence that are not in the second input sequence. ![Graphic showing the action of Except().](../../../../csharp/programming-guide/concepts/linq/media/except.png "Except") ### Intersect - The following illustration depicts the behavior of . The returned sequence contains the elements that are common to both of the input sequences. + The following illustration depicts the behavior of . The returned sequence contains the elements that are common to both of the input sequences. ![Graphic showing the intersection of two sequences.](../../../../csharp/programming-guide/concepts/linq/media/intersect.png "Intersect") diff --git a/docs/visual-basic/programming-guide/concepts/linq/shape-of-wordprocessingml-documents.md b/docs/visual-basic/programming-guide/concepts/linq/shape-of-wordprocessingml-documents.md index 4c9efdef12620..88da1fa107b33 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/shape-of-wordprocessingml-documents.md +++ b/docs/visual-basic/programming-guide/concepts/linq/shape-of-wordprocessingml-documents.md @@ -63,7 +63,7 @@ xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml"> The easiest way to see the contents of a WordprocessingML document in XML form is to create one using Microsoft Word, save it, and then run the following program that prints the XML to the console. - This example uses classes found in the WindowsBase assembly. It uses types in the namespace. + This example uses classes found in the WindowsBase assembly. It uses types in the namespace. ```vb Imports diff --git a/docs/visual-basic/programming-guide/concepts/linq/sorting-data.md b/docs/visual-basic/programming-guide/concepts/linq/sorting-data.md index daeb5cdfeb1f6..421be8add6264 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/sorting-data.md +++ b/docs/visual-basic/programming-guide/concepts/linq/sorting-data.md @@ -35,11 +35,11 @@ A sorting operation orders the elements of a sequence based on one or more attri |Method Name|Description|Visual Basic Query Expression Syntax|More Information| |-----------------|-----------------|------------------------------------------|----------------------| -|OrderBy|Sorts values in ascending order.|`Order By`|

| -|OrderByDescending|Sorts values in descending order.|`Order By … Descending`|

| -|ThenBy|Performs a secondary sort in ascending order.|`Order By …, …`|

| -|ThenByDescending|Performs a secondary sort in descending order.|`Order By …, … Descending`|

| -|Reverse|Reverses the order of the elements in a collection.|Not applicable.|

| +|OrderBy|Sorts values in ascending order.|`Order By`|

| +|OrderByDescending|Sorts values in descending order.|`Order By … Descending`|

| +|ThenBy|Performs a secondary sort in ascending order.|`Order By …, …`|

| +|ThenByDescending|Performs a secondary sort in descending order.|`Order By …, … Descending`|

| +|Reverse|Reverses the order of the elements in a collection.|Not applicable.|

| ## Query Expression Syntax Examples diff --git a/docs/visual-basic/programming-guide/concepts/linq/using-xslt-to-transform-an-xml-tree.md b/docs/visual-basic/programming-guide/concepts/linq/using-xslt-to-transform-an-xml-tree.md index 494341e7e5c73..c663a5db00644 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/using-xslt-to-transform-an-xml-tree.md +++ b/docs/visual-basic/programming-guide/concepts/linq/using-xslt-to-transform-an-xml-tree.md @@ -74,6 +74,6 @@ Console.WriteLine(newTree) ``` ## See Also - - + + [Advanced LINQ to XML Programming (Visual Basic)](../../../../visual-basic/programming-guide/concepts/linq/advanced-linq-to-xml-programming.md) diff --git a/docs/visual-basic/programming-guide/concepts/linq/walkthrough-writing-queries.md b/docs/visual-basic/programming-guide/concepts/linq/walkthrough-writing-queries.md index 6af5848958c42..420e77b327268 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/walkthrough-writing-queries.md +++ b/docs/visual-basic/programming-guide/concepts/linq/walkthrough-writing-queries.md @@ -54,7 +54,7 @@ This walkthrough demonstrates how you can use Visual Basic language features to 4. In the list of project types, click **Console Application**. In the **Name** box, type a name for the project, and then click **OK**. - A project is created. By default, it contains a reference to System.Core.dll. Also, the **Imported namespaces** list on the [References Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/references-page-project-designer-visual-basic) includes the namespace. + A project is created. By default, it contains a reference to System.Core.dll. Also, the **Imported namespaces** list on the [References Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/references-page-project-designer-visual-basic) includes the namespace. 5. On the [Compile Page, Project Designer (Visual Basic)](/visualstudio/ide/reference/compile-page-project-designer-visual-basic), ensure that **Option infer** is set to **On**. diff --git a/docs/visual-basic/programming-guide/concepts/linq/xelement-class-overview.md b/docs/visual-basic/programming-guide/concepts/linq/xelement-class-overview.md index 13d3c6256c0c0..0e0cc42edbb10 100644 --- a/docs/visual-basic/programming-guide/concepts/linq/xelement-class-overview.md +++ b/docs/visual-basic/programming-guide/concepts/linq/xelement-class-overview.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # XElement Class Overview (Visual Basic) -The class is one of the fundamental classes in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)]. It represents an XML element. You can use this class to create elements; change the content of the element; add, change, or delete child elements; add attributes to an element; or serialize the contents of an element in text form. You can also interoperate with other classes in , such as , , and . +The class is one of the fundamental classes in [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)]. It represents an XML element. You can use this class to create elements; change the content of the element; add, change, or delete child elements; add attributes to an element; or serialize the contents of an element in text form. You can also interoperate with other classes in , such as , , and . ## XElement Functionality This topic describes the functionality provided by the class. diff --git a/docs/visual-basic/programming-guide/concepts/threading/index.md b/docs/visual-basic/programming-guide/concepts/threading/index.md index 47e08a25b9ae3..f3b2f6f1e0795 100644 --- a/docs/visual-basic/programming-guide/concepts/threading/index.md +++ b/docs/visual-basic/programming-guide/concepts/threading/index.md @@ -44,7 +44,7 @@ Threading enables your Visual Basic program to perform concurrent processing so You can use some or all these classes to synchronize the activities of multiple threads, but some support for threading is supported by the Visual Basic language. For example, the [SyncLock Statement](../../../../visual-basic/language-reference/statements/synclock-statement.md) provides synchronization features through implicit use of . > [!NOTE] -> Beginning with the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], multithreaded programming is greatly simplified with the and classes, [Parallel LINQ (PLINQ)](https://msdn.microsoft.com/library/dd460688), new concurrent collection classes in the namespace, and a new programming model that is based on the concept of tasks rather than threads. For more information, see [Parallel Programming](https://msdn.microsoft.com/library/dd460693). +> Beginning with the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], multithreaded programming is greatly simplified with the and classes, [Parallel LINQ (PLINQ)](https://msdn.microsoft.com/library/dd460688), new concurrent collection classes in the namespace, and a new programming model that is based on the concept of tasks rather than threads. For more information, see [Parallel Programming](https://msdn.microsoft.com/library/dd460693). ## Related Topics diff --git a/docs/visual-basic/programming-guide/concepts/threading/thread-pooling.md b/docs/visual-basic/programming-guide/concepts/threading/thread-pooling.md index cb57710ac4553..fde02fa943d43 100644 --- a/docs/visual-basic/programming-guide/concepts/threading/thread-pooling.md +++ b/docs/visual-basic/programming-guide/concepts/threading/thread-pooling.md @@ -33,7 +33,7 @@ A *thread pool* is a collection of threads that can be used to perform several t You can implement your own thread pool, but it is easier to use the thread pool provided by the .NET Framework through the class. - With thread pooling, you call the method with a delegate for the procedure you want to run, and Visual Basic creates the thread and runs your procedure. + With thread pooling, you call the method with a delegate for the procedure you want to run, and Visual Basic creates the thread and runs your procedure. ## Thread Pooling Example The following example shows how you can use thread pooling to start several tasks. diff --git a/docs/visual-basic/programming-guide/concepts/threading/thread-synchronization.md b/docs/visual-basic/programming-guide/concepts/threading/thread-synchronization.md index 253d336e76780..aba54494913b2 100644 --- a/docs/visual-basic/programming-guide/concepts/threading/thread-synchronization.md +++ b/docs/visual-basic/programming-guide/concepts/threading/thread-synchronization.md @@ -94,7 +94,7 @@ End Try There are two kinds of synchronization events: , and . They differ only in that changes from signaled to unsignaled automatically any time it activates a thread. Conversely, a allows any number of threads to be activated by its signaled state, and will only revert to an unsignaled state when its method is called. - Threads can be made to wait on events by calling one of the wait methods, such as , , or . causes the thread to wait until a single event becomes signaled, blocks a thread until one or more indicated events become signaled, and blocks the thread until all of the indicated events become signaled. An event becomes signaled when its method is called. + Threads can be made to wait on events by calling one of the wait methods, such as , , or . causes the thread to wait until a single event becomes signaled, blocks a thread until one or more indicated events become signaled, and blocks the thread until all of the indicated events become signaled. An event becomes signaled when its method is called. In the following example, a thread is created and started by the `Main` function. The new thread waits on an event using the method. The thread is suspended until the event becomes signaled by the primary thread that is executing the `Main` function. Once the event becomes signaled, the auxiliary thread returns. In this case, because the event is only used for one thread activation, either the or classes could be used. diff --git a/docs/visual-basic/programming-guide/concepts/threading/thread-timers.md b/docs/visual-basic/programming-guide/concepts/threading/thread-timers.md index 42cb738bfd37b..7afc4db0822a6 100644 --- a/docs/visual-basic/programming-guide/concepts/threading/thread-timers.md +++ b/docs/visual-basic/programming-guide/concepts/threading/thread-timers.md @@ -23,7 +23,7 @@ translation.priority.mt: - "tr-tr" --- # Thread Timers (Visual Basic) -The class is useful for periodically running a task on a separate thread. For example, you could use a thread timer to check the status and integrity of a database or to back up critical files. +The class is useful for periodically running a task on a separate thread. For example, you could use a thread timer to check the status and integrity of a database or to back up critical files. ## Thread Timer Example The following example starts a task every two seconds and uses a flag to initiate the method that stops the timer. This example posts status to the output window. @@ -72,7 +72,7 @@ Private Sub TimerTask(ByVal StateObj As Object) End Sub ``` - Thread timers are particularly useful when the object is unavailable, such as when you are developing console applications. + Thread timers are particularly useful when the object is unavailable, such as when you are developing console applications. ## See Also diff --git a/docs/visual-basic/programming-guide/language-features/arrays/how-to-sort-an-array.md b/docs/visual-basic/programming-guide/language-features/arrays/how-to-sort-an-array.md index 896f07b55c7ce..43003e5fe3eee 100644 --- a/docs/visual-basic/programming-guide/language-features/arrays/how-to-sort-an-array.md +++ b/docs/visual-basic/programming-guide/language-features/arrays/how-to-sort-an-array.md @@ -66,7 +66,7 @@ End Sub - One or more elements of the array do not implement the interface ( class) ## See Also - + [Arrays](../../../../visual-basic/programming-guide/language-features/arrays/index.md) [Troubleshooting Arrays](../../../../visual-basic/programming-guide/language-features/arrays/troubleshooting-arrays.md) [Collections](http://msdn.microsoft.com/library/e76533a9-5033-4a0b-b003-9c2be60d185b) diff --git a/docs/visual-basic/programming-guide/language-features/arrays/index.md b/docs/visual-basic/programming-guide/language-features/arrays/index.md index 38d1520d29f7a..ba0617bd41e0a 100644 --- a/docs/visual-basic/programming-guide/language-features/arrays/index.md +++ b/docs/visual-basic/programming-guide/language-features/arrays/index.md @@ -253,11 +253,11 @@ Dim prices(3, 4, 5) As Long ## Array Types and Other Types Every array has a data type, but it differs from the data type of its elements. There is no single data type for all arrays. Instead, the data type of an array is determined by the number of dimensions, or *rank*, of the array, and the data type of the elements in the array. Two array variables are considered to be of the same data type only when they have the same rank and their elements have the same data type. The lengths of the dimensions in an array do not influence the array data type. - Every array inherits from the class, and you can declare a variable to be of type `Array`, but you cannot create an array of type `Array`. Also, the [ReDim Statement](../../../../visual-basic/language-reference/statements/redim-statement.md) cannot operate on a variable declared as type `Array`. For these reasons, and for type safety, it is advisable to declare every array as a specific type, such as `Integer` in the preceding example. + Every array inherits from the class, and you can declare a variable to be of type `Array`, but you cannot create an array of type `Array`. Also, the [ReDim Statement](../../../../visual-basic/language-reference/statements/redim-statement.md) cannot operate on a variable declared as type `Array`. For these reasons, and for type safety, it is advisable to declare every array as a specific type, such as `Integer` in the preceding example. You can find out the data type of either an array or its elements in several ways. -- You can call the method on the variable to receive a object for the run-time type of the variable. The object holds extensive information in its properties and methods. +- You can call the method on the variable to receive a object for the run-time type of the variable. The object holds extensive information in its properties and methods. - You can pass the variable to the function to receive a `String` containing the name of run-time type. @@ -274,12 +274,12 @@ Dim prices(3, 4, 5) As Long For some collections, you can assign a key to any object that you put into the collection so that you can quickly retrieve the object by using the key. - If your collection contains elements of only one data type, you can use one of the classes in the namespace. A generic collection enforces type safety so that no other data type can be added to it. When you retrieve an element from a generic collection, you do not have to determine its data type or convert it. + If your collection contains elements of only one data type, you can use one of the classes in the namespace. A generic collection enforces type safety so that no other data type can be added to it. When you retrieve an element from a generic collection, you do not have to determine its data type or convert it. For more information about collections, see [Collections](http://msdn.microsoft.com/library/e76533a9-5033-4a0b-b003-9c2be60d185b). ### Example - The following example uses the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] generic class to create a list collection of `Customer` objects. + The following example uses the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] generic class to create a list collection of `Customer` objects. [!code-vb[VbVbalrArrays#1](../../../../../samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrArrays/VB/Class1.vb#1)] diff --git a/docs/visual-basic/programming-guide/language-features/data-types/array-conversions.md b/docs/visual-basic/programming-guide/language-features/data-types/array-conversions.md index 2f491746dc3f7..e860a8cc0f4f0 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/array-conversions.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/array-conversions.md @@ -48,7 +48,7 @@ You can convert an array type to a different array type provided you meet the fo - **Element Data Type.** The data types of the elements of both arrays must be reference types. You cannot convert an `Integer` array to a `Long` array, or even to an `Object` array, because at least one value type is involved. For more information, see [Value Types and Reference Types](../../../../visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md). -- **Convertibility.** A conversion, either widening or narrowing, must be possible between the element types of the two arrays. An example that fails this requirement is an attempted conversion between a `String` array and an array of a class derived from . These two types have nothing in common, and no conversion of any kind exists between them. +- **Convertibility.** A conversion, either widening or narrowing, must be possible between the element types of the two arrays. An example that fails this requirement is an attempted conversion between a `String` array and an array of a class derived from . These two types have nothing in common, and no conversion of any kind exists between them. A conversion of one array type to another is widening or narrowing depending on whether the conversion of the respective elements is widening or narrowing. For more information, see [Widening and Narrowing Conversions](../../../../visual-basic/programming-guide/language-features/data-types/widening-and-narrowing-conversions.md). diff --git a/docs/visual-basic/programming-guide/language-features/data-types/elementary-data-types.md b/docs/visual-basic/programming-guide/language-features/data-types/elementary-data-types.md index 0163e509c42be..18cae286271ab 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/elementary-data-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/elementary-data-types.md @@ -38,7 +38,7 @@ translation.priority.ht: [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] supplies a set of predefined data types, which you can use for many of your programming elements. This section describes these types and how to use them. > [!NOTE] -> Every elementary data type in Visual Basic is supported by a structure or a class that is in the namespace. The compiler uses each data type keyword as an alias for the underlying structure or class. For example, declaring a variable by using the reserved word `Byte` is the same as declaring it by using the fully qualified structure name . +> Every elementary data type in Visual Basic is supported by a structure or a class that is in the namespace. The compiler uses each data type keyword as an alias for the underlying structure or class. For example, declaring a variable by using the reserved word `Byte` is the same as declaring it by using the fully qualified structure name . ## In This Section [Numeric Data Types](../../../../visual-basic/programming-guide/language-features/data-types/numeric-data-types.md) diff --git a/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md b/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md index 0d100acde6c74..a94e3b68ac1e2 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/generic-types.md @@ -71,7 +71,7 @@ Screwdriver set as a generic tool When you define a generic type, you parameterize it with one or more data types. This allows the using code to tailor the data types to its requirements. Your code can declare several different programming elements from the generic element, each one acting on a different set of data types. But the declared elements all perform the identical logic, no matter what data types they are using. - For example, you might want to create and use a queue class that operates on a specific data type such as `String`. You can declare such a class from , as the following example shows. + For example, you might want to create and use a queue class that operates on a specific data type such as `String`. You can declare such a class from , as the following example shows. [!code-vb[VbVbalrDataTypes#1](../../../../visual-basic/language-reference/data-types/codesnippet/VisualBasic/generic-types_1.vb)] @@ -95,7 +95,7 @@ Screwdriver set as a generic tool For a more complete example, see [How to: Define a Class That Can Provide Identical Functionality on Different Data Types](../../../../visual-basic/programming-guide/language-features/data-types/how-to-define-a-class-that-can-provide-identical-functionality.md). ## Eligible Programming Elements - You can define and use generic classes, structures, interfaces, procedures, and delegates. Note that the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] defines several generic classes, structures, and interfaces that represent commonly used generic elements. The namespace provides dictionaries, lists, queues, and stacks. Before defining your own generic element, see if it is already available in . + You can define and use generic classes, structures, interfaces, procedures, and delegates. Note that the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] defines several generic classes, structures, and interfaces that represent commonly used generic elements. The namespace provides dictionaries, lists, queues, and stacks. Before defining your own generic element, see if it is already available in . Procedures are not types, but you can define and use generic procedures. See [Generic Procedures in Visual Basic](../../../../visual-basic/programming-guide/language-features/data-types/generic-procedures.md). diff --git a/docs/visual-basic/programming-guide/language-features/data-types/how-to-convert-an-object-to-another-type.md b/docs/visual-basic/programming-guide/language-features/data-types/how-to-convert-an-object-to-another-type.md index 0a10181b3d1c9..b1e02ef5fddca 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/how-to-convert-an-object-to-another-type.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/how-to-convert-an-object-to-another-type.md @@ -53,7 +53,7 @@ End Sub ## Compiling the Code This example requires: -- A reference to the namespace. +- A reference to the namespace. ## See Also diff --git a/docs/visual-basic/programming-guide/language-features/data-types/how-to-use-a-generic-class.md b/docs/visual-basic/programming-guide/language-features/data-types/how-to-use-a-generic-class.md index 79585283c2b37..af8285f0f3d5f 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/how-to-use-a-generic-class.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/how-to-use-a-generic-class.md @@ -60,11 +60,11 @@ A class that takes *type parameters* is called a *generic class*. If you are usi ### To use a class that takes a type parameter -1. At the beginning of your source file, include an [Imports Statement (.NET Namespace and Type)](../../../../visual-basic/language-reference/statements/imports-statement-net-namespace-and-type.md) to import the namespace. This allows you to refer to the class without having to fully qualify it to differentiate it from other queue classes such as . +1. At the beginning of your source file, include an [Imports Statement (.NET Namespace and Type)](../../../../visual-basic/language-reference/statements/imports-statement-net-namespace-and-type.md) to import the namespace. This allows you to refer to the class without having to fully qualify it to differentiate it from other queue classes such as . 2. Create the object in the normal way, but add `(Of` `type``)` immediately after the class name. - The following example uses the same class () to create two queue objects that hold items of different data types. It adds items to the end of each queue and then removes and displays items from the front of each queue. + The following example uses the same class () to create two queue objects that hold items of different data types. It adds items to the end of each queue and then removes and displays items from the front of each queue. [!code-vb[VbVbalrDataTypes#9](../../../../visual-basic/language-reference/data-types/codesnippet/VisualBasic/how-to-use-a-generic-class_1.vb)] diff --git a/docs/visual-basic/programming-guide/language-features/data-types/structures-and-classes.md b/docs/visual-basic/programming-guide/language-features/data-types/structures-and-classes.md index bcf7754cbb953..1631f57112882 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/structures-and-classes.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/structures-and-classes.md @@ -79,7 +79,7 @@ translation.priority.ht: - Structure variable declarations cannot specify initializers or initial sizes for arrays; class variable declarations can. -- Structures implicitly inherit from the class and cannot inherit from any other type; classes can inherit from any class or classes other than . +- Structures implicitly inherit from the class and cannot inherit from any other type; classes can inherit from any class or classes other than . - Structures are not inheritable; classes are. diff --git a/docs/visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md b/docs/visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md index ef0e0c6cd2e35..2b19c6e3b6d99 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/troubleshooting-data-types.md @@ -129,7 +129,7 @@ This page lists some common problems that can occur when you perform operations If you must convert from `String` to another data type, the safest procedure is to enclose the attempted conversion in the [Try...Catch...Finally Statement](../../../../visual-basic/language-reference/statements/try-catch-finally-statement.md). This lets you deal with a run-time failure. ### Character Arrays - A single `Char` and an array of `Char` elements both widen to `String`. However, `String` does not widen to `Char()`. To convert a `String` value to a `Char` array, you can use the method of the class. + A single `Char` and an array of `Char` elements both widen to `String`. However, `String` does not widen to `Char()`. To convert a `String` value to a `Char` array, you can use the method of the class. ### Meaningless Values In general, `String` values are not meaningful in other data types, and conversion is highly artificial and dangerous. Whenever possible, you should restrict usage of `String` variables to the character sequences for which they are designed. You should never write code that relies on equivalent values in other types. diff --git a/docs/visual-basic/programming-guide/language-features/data-types/tuples.md b/docs/visual-basic/programming-guide/language-features/data-types/tuples.md index be07ac21d36fa..95189d977431e 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/tuples.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/tuples.md @@ -131,11 +131,11 @@ A method can return only a single value. Frequently, though, you'd like a method - You can use a tuple, which provides a lightweight solution to retrieving multiple return values. -For example, the **TryParse** methods in .NET return a `Boolean` value that indicates whether the parsing operation succeeded. The result of the parsing operation is returned in a variable passed by reference to the method. Normally, a call to the a parsing method such as looks like the following: +For example, the **TryParse** methods in .NET return a `Boolean` value that indicates whether the parsing operation succeeded. The result of the parsing operation is returned in a variable passed by reference to the method. Normally, a call to the a parsing method such as looks like the following: [!code-vb[Return](../../../../../samples/snippets/visualbasic/programming-guide/language-features/data-types/tuple-returns.vb#1)] -We can return a tuple from the parsing operation if we wrap the call to the method in our own method. In the following example, `NumericLibrary.ParseInteger` calls the method and returns a named tuple with two elements. +We can return a tuple from the parsing operation if we wrap the call to the method in our own method. In the following example, `NumericLibrary.ParseInteger` calls the method and returns a named tuple with two elements. [!code-vb[Return](../../../../../samples/snippets/visualbasic/programming-guide/language-features/data-types/tuple-returns.vb#2)] diff --git a/docs/visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md b/docs/visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md index c9c4f03db509f..a3da708918bac 100644 --- a/docs/visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md +++ b/docs/visual-basic/programming-guide/language-features/data-types/value-types-and-reference-types.md @@ -92,7 +92,7 @@ Dim totals() As Single = New Single(8) {} ## Working with the Object Data Type You can assign either a reference type or a value type to a variable of the `Object` data type. An `Object` variable always holds a pointer to the data, never the data itself. However, if you assign a value type to an `Object` variable, it behaves as if it holds its own data. For more information, see [Object Data Type](../../../../visual-basic/language-reference/data-types/object-data-type.md). - You can find out whether an `Object` variable is acting as a reference type or a value type by passing it to the method in the class of the namespace. returns `True` if the content of the `Object` variable represents a reference type. + You can find out whether an `Object` variable is acting as a reference type or a value type by passing it to the method in the class of the namespace. returns `True` if the content of the `Object` variable represents a reference type. ## See Also [Nullable Value Types](../../../../visual-basic/programming-guide/language-features/data-types/nullable-value-types.md) diff --git a/docs/visual-basic/programming-guide/language-features/declared-elements/references-to-declared-elements.md b/docs/visual-basic/programming-guide/language-features/declared-elements/references-to-declared-elements.md index c5d219de0f671..406a22822a1fb 100644 --- a/docs/visual-basic/programming-guide/language-features/declared-elements/references-to-declared-elements.md +++ b/docs/visual-basic/programming-guide/language-features/declared-elements/references-to-declared-elements.md @@ -117,7 +117,7 @@ End Module 6. The compiler uses the qualification string to find a clear, unambiguous declaration to which it can match the target element reference. - You might also have to qualify a name reference if your application has access to more than one programming element that has the same name. For example, the and namespaces both contain a `Label` class ( and ). If your application uses both, or if it defines its own `Label` class, you must distinguish the different `Label` objects. Include the namespace or import alias in the variable declaration. The following example uses the import alias. + You might also have to qualify a name reference if your application has access to more than one programming element that has the same name. For example, the and namespaces both contain a `Label` class ( and ). If your application uses both, or if it defines its own `Label` class, you must distinguish the different `Label` objects. Include the namespace or import alias in the variable declaration. The following example uses the import alias. ```vb ' The following statement must precede all your declarations. diff --git a/docs/visual-basic/programming-guide/language-features/delegates/index.md b/docs/visual-basic/programming-guide/language-features/delegates/index.md index 0f35cc5818cbe..3d7e332262d7d 100644 --- a/docs/visual-basic/programming-guide/language-features/delegates/index.md +++ b/docs/visual-basic/programming-guide/language-features/delegates/index.md @@ -35,7 +35,7 @@ translation.priority.ht: - "zh-tw" --- # Delegates (Visual Basic) -Delegates are objects that refer to methods. They are sometimes described as *type-safe function pointers* because they are similar to function pointers used in other programming languages. But unlike function pointers, [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] delegates are a reference type based on the class . Delegates can reference both shared methods — methods that can be called without a specific instance of a class — and instance methods. +Delegates are objects that refer to methods. They are sometimes described as *type-safe function pointers* because they are similar to function pointers used in other programming languages. But unlike function pointers, [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] delegates are a reference type based on the class . Delegates can reference both shared methods — methods that can be called without a specific instance of a class — and instance methods. ## Delegates and Events Delegates are useful in situations where you need an intermediary between a calling procedure and the procedure being called. For example, you might want an object that raises events to be able to call different event handlers under different circumstances. Unfortunately, the object raising the events cannot know ahead of time which event handler is handling a specific event. [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] lets you dynamically associate event handlers with events by creating a delegate for you when you use the `AddHandler` statement. At run time, the delegate forwards calls to the appropriate event handler. diff --git a/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md b/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md index cbbfc351b8cd3..a2681b3d343a2 100644 --- a/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md +++ b/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md @@ -98,7 +98,7 @@ End Class Explicitly named properties of an anonymous type cannot conflict with these generated methods. That is, you cannot use `.Equals`, `.GetHashCode`, or `.ToString` to name a property. - Anonymous type definitions that include at least one key property also implement the interface, where `T` is the type of the anonymous type. + Anonymous type definitions that include at least one key property also implement the interface, where `T` is the type of the anonymous type. > [!NOTE] > Anonymous type declarations create the same anonymous type only if they occur in the same assembly, their properties have the same names and the same inferred types, the properties are declared in the same order, and the same properties are marked as key properties. diff --git a/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-types.md b/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-types.md index 075eff82f89ac..2ee1ce4bd39e6 100644 --- a/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-types.md +++ b/docs/visual-basic/programming-guide/language-features/objects-and-classes/anonymous-types.md @@ -144,7 +144,7 @@ Visual Basic supports anonymous types, which enable you to create objects withou If the anonymous type contains at least one key property, the definition overrides three members inherited from : , , and . The code produced for testing equality and determining the hash code value considers only the key properties. If the anonymous type contains no key properties, only is overridden. Explicitly named properties of an anonymous type cannot conflict with these generated methods. That is, you cannot use `.Equals`, `.GetHashCode`, or `.ToString` to name a property. - Anonymous type definitions that have at least one key property also implement the interface, where `T` is the type of the anonymous type. + Anonymous type definitions that have at least one key property also implement the interface, where `T` is the type of the anonymous type. For more information about the code created by the compiler and the functionality of the overridden methods, see [Anonymous Type Definition](../../../../visual-basic/programming-guide/language-features/objects-and-classes/anonymous-type-definition.md). diff --git a/docs/visual-basic/programming-guide/language-features/procedures/extension-methods.md b/docs/visual-basic/programming-guide/language-features/procedures/extension-methods.md index 1ea7fa7d5d0d4..2d0e5b7fd3c2d 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/extension-methods.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/extension-methods.md @@ -41,7 +41,7 @@ translation.priority.mt: Extension methods enable developers to add custom functionality to data types that are already defined without creating a new derived type. Extension methods make it possible to write a method that can be called as if it were an instance method of the existing type. ## Remarks - An extension method can be only a `Sub` procedure or a `Function` procedure. You cannot define an extension property, field, or event. All extension methods must be marked with the extension attribute `` from the namespace. + An extension method can be only a `Sub` procedure or a `Function` procedure. You cannot define an extension property, field, or event. All extension methods must be marked with the extension attribute `` from the namespace. The first parameter in an extension method definition specifies which data type the method extends. When the method is run, the first parameter is bound to the instance of the data type that invokes the method. diff --git a/docs/visual-basic/programming-guide/language-features/procedures/ref-return-values.md b/docs/visual-basic/programming-guide/language-features/procedures/ref-return-values.md index 6f02b37daa158..6d72e473c1856 100644 --- a/docs/visual-basic/programming-guide/language-features/procedures/ref-return-values.md +++ b/docs/visual-basic/programming-guide/language-features/procedures/ref-return-values.md @@ -59,7 +59,7 @@ The following C# example illustrates this scenario. It defines a `Sentence` clas [!code-cs[Ref-Return](../../../../../samples/snippets/visualbasic/getting-started/ref-returns.cs)] -Directly modifying the reference return value in this case is not reliable, since the method call may fail to find a match and return the first word in the sentence. In that case, the caller will inadvertently modify the first word of the sentence. This could be prevented by the caller returning a `null` (or `Nothing` in Visual Basic). But in that case, attempting to modify a string whose value is `Nothing` throws a . If could also be prevented by the caller returning , but this requires that the caller define a string variable whose value is . While the caller can modify that string, the modification itself serves no purpose, since the modified string has no relationship to the words in the sentence stored by the `Sentence` class. +Directly modifying the reference return value in this case is not reliable, since the method call may fail to find a match and return the first word in the sentence. In that case, the caller will inadvertently modify the first word of the sentence. This could be prevented by the caller returning a `null` (or `Nothing` in Visual Basic). But in that case, attempting to modify a string whose value is `Nothing` throws a . If could also be prevented by the caller returning , but this requires that the caller define a string variable whose value is . While the caller can modify that string, the modification itself serves no purpose, since the modified string has no relationship to the words in the sentence stored by the `Sentence` class. The best way to handle this scenario is to pass the reference return value by reference to a helper method. The helper method then contains the logic to determine whether the method call succeeded and, if it did, to modify the reference return value. The following example provides a possible implementation. diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md b/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md index de1daf2d298d0..cb07531a83edf 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md @@ -62,7 +62,7 @@ This Help page discusses how [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] uses cu When you need to perform a string conversion in a specific culture format, you should use the `CultureInfo` class that is built into the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)]. You can create a new `CultureInfo` object for a specific culture by passing the culture's name to the constructor. The supported culture names are listed in the class Help page. - Alternatively, you can get an instance of the *invariant culture* from the property. The invariant culture is based on the English culture, but there are some differences. For example, the invariant culture specifies a 24-hour clock instead of a 12-hour clock. + Alternatively, you can get an instance of the *invariant culture* from the property. The invariant culture is based on the English culture, but there are some differences. For example, the invariant culture specifies a 24-hour clock instead of a 12-hour clock. To convert a date to the culture's string, pass the object to the date object's method. For example, the following code displays "07/04/2005 00:00:00", regardless of the application's culture settings. @@ -84,11 +84,11 @@ This Help page discusses how [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] uses cu [!code-vb[VbVbalrStrings#22](../../../../visual-basic/language-reference/functions/codesnippet/VisualBasic/how-culture-affects-strings_2.vb)] - You can also use the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] partner of the `StrComp` function, the method. This is a static, overloaded method of the base string class. The following example illustrates how this method is used: + You can also use the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] partner of the `StrComp` function, the method. This is a static, overloaded method of the base string class. The following example illustrates how this method is used: [!code-vb[VbVbalrStrings#48](../../../../visual-basic/language-reference/functions/codesnippet/VisualBasic/how-culture-affects-strings_3.vb)] - For finer control over how the comparisons are performed, you can use additional overloads of the method. With the method, you can use the `comparisonType` argument to specify which type of comparison to use. + For finer control over how the comparisons are performed, you can use additional overloads of the method. With the method, you can use the `comparisonType` argument to specify which type of comparison to use. |Value for `comparisonType` argument|Type of comparison|When to use| |---|---|---| @@ -98,7 +98,7 @@ This Help page discusses how [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] uses cu |`InvariantCulture` or `InvariantCultureIgnoreCase`|Comparison based on the strings' interpretation in the invariant culture.

This is different than the `Ordinal` and `OrdinalIgnoreCase`, because the invariant culture treats characters outside its accepted range as equivalent invariant characters.|Use these values only when comparing persisting data or displaying linguistically-relevant data that requires a fixed sort order.| ### Security Considerations - If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass `Ordinal` or `OrdinalIgnoreCase` for the `comparisonType` argument. + If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass `Ordinal` or `OrdinalIgnoreCase` for the `comparisonType` argument. ## See Also diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-a-string-to-an-array-of-characters.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-a-string-to-an-array-of-characters.md index 289bbdd7e9080..763b29c0dc7c9 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-a-string-to-an-array-of-characters.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-a-string-to-an-array-of-characters.md @@ -52,7 +52,7 @@ Sometimes it is useful to have data about the characters in your string and the ## See Also - + [How to: Access Characters in Strings](../../../../visual-basic/programming-guide/language-features/strings/how-to-access-characters-in-strings.md) [Converting Between Strings and Other Data Types in Visual Basic](../../../../visual-basic/programming-guide/language-features/strings/converting-between-strings-and-other-data-types.md) [Strings](../../../../visual-basic/programming-guide/language-features/strings/index.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md index 51b262a59d9a1..624c5def057f2 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md @@ -40,27 +40,27 @@ translation.priority.ht: This topic shows how to convert the bytes from a byte array into a string. ## Example - This example uses the method of the encoding class to convert all the bytes from a byte array into a string. + This example uses the method of the encoding class to convert all the bytes from a byte array into a string. [!code-vb[VbVbalrStrings#72](../../../../visual-basic/language-reference/functions/codesnippet/VisualBasic/how-to-convert-an-array-of-bytes-into-a-string_1.vb)] You can choose from several encoding options to convert a byte array into a string: -- : Gets an encoding for the ASCII (7-bit) character set. +- : Gets an encoding for the ASCII (7-bit) character set. -- : Gets an encoding for the UTF-16 format using the big-endian byte order. +- : Gets an encoding for the UTF-16 format using the big-endian byte order. -- : Gets an encoding for the system's current ANSI code page. +- : Gets an encoding for the system's current ANSI code page. -- : Gets an encoding for the UTF-16 format using the little-endian byte order. +- : Gets an encoding for the UTF-16 format using the little-endian byte order. -- : Gets an encoding for the UTF-32 format using the little-endian byte order. +- : Gets an encoding for the UTF-32 format using the little-endian byte order. -- : Gets an encoding for the UTF-7 format. +- : Gets an encoding for the UTF-7 format. -- : Gets an encoding for the UTF-8 format. +- : Gets an encoding for the UTF-8 format. ## See Also - + [How to: Convert Strings into an Array of Bytes in Visual Basic](../../../../visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md index 8c5e1c18f96a6..efa50a848e809 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md +++ b/docs/visual-basic/programming-guide/language-features/strings/how-to-convert-strings-into-an-array-of-bytes.md @@ -41,27 +41,27 @@ translation.priority.ht: This topic shows how to convert a string into an array of bytes. ## Example - This example uses the method of the encoding class to convert a string into an array of bytes. + This example uses the method of the encoding class to convert a string into an array of bytes. [!code-vb[VbVbalrStrings#74](../../../../visual-basic/language-reference/functions/codesnippet/VisualBasic/how-to-convert-strings-into-an-array-of-bytes_1.vb)] You can choose from several encoding options to convert a string into a byte array: -- : Gets an encoding for the ASCII (7-bit) character set. +- : Gets an encoding for the ASCII (7-bit) character set. -- : Gets an encoding for the UTF-16 format using the big-endian byte order. +- : Gets an encoding for the UTF-16 format using the big-endian byte order. -- : Gets an encoding for the system's current ANSI code page. +- : Gets an encoding for the system's current ANSI code page. -- : Gets an encoding for the UTF-16 format using the little-endian byte order. +- : Gets an encoding for the UTF-16 format using the little-endian byte order. -- : Gets an encoding for the UTF-32 format using the little-endian byte order. +- : Gets an encoding for the UTF-32 format using the little-endian byte order. -- : Gets an encoding for the UTF-7 format. +- : Gets an encoding for the UTF-7 format. -- : Gets an encoding for the UTF-8 format. +- : Gets an encoding for the UTF-8 format. ## See Also - + [How to: Convert an Array of Bytes into a String in Visual Basic](../../../../visual-basic/programming-guide/language-features/strings/how-to-convert-an-array-of-bytes-into-a-string.md) diff --git a/docs/visual-basic/programming-guide/language-features/strings/types-of-string-manipulation-methods.md b/docs/visual-basic/programming-guide/language-features/strings/types-of-string-manipulation-methods.md index 5610b3f4e8c50..e715158789145 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/types-of-string-manipulation-methods.md +++ b/docs/visual-basic/programming-guide/language-features/strings/types-of-string-manipulation-methods.md @@ -54,14 +54,14 @@ There are several different ways to analyze and manipulate your strings. Some of [!code-vb[VbVbalrStrings#45](../../../../visual-basic/language-reference/functions/codesnippet/VisualBasic/types-of-string-manipulation-methods_2.vb)] - In the preceding example, the method is a static method, which acts upon an expression it is given and assigns the resulting value to `bString`. + In the preceding example, the method is a static method, which acts upon an expression it is given and assigns the resulting value to `bString`. #### Instance Methods Instance methods, by contrast, stem from a particular instance of `String` and must be qualified with the instance name. For example: [!code-vb[VbVbalrStrings#46](../../../../visual-basic/language-reference/functions/codesnippet/VisualBasic/types-of-string-manipulation-methods_3.vb)] - In this example, the method is a method of the instance of `String` (that is, `aString`). It performs an operation on `aString` and assigns that value to `bString`. + In this example, the method is a method of the instance of `String` (that is, `aString`). It performs an operation on `aString` and assigns that value to `bString`. For more information, see the documentation for the class. diff --git a/docs/visual-basic/programming-guide/language-features/strings/zero-based-vs-one-based-string-access.md b/docs/visual-basic/programming-guide/language-features/strings/zero-based-vs-one-based-string-access.md index 794f56891f24b..f179e5ddda4c5 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/zero-based-vs-one-based-string-access.md +++ b/docs/visual-basic/programming-guide/language-features/strings/zero-based-vs-one-based-string-access.md @@ -37,10 +37,10 @@ translation.priority.ht: This topic compares how [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] and the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] provide access to the characters in a string. The [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] always provides zero-based access to the characters in a string, whereas [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] provides zero-based and one-based access, depending on the function. ## One-Based - For an example of a one-based [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] function, consider the `Mid` function. It takes an argument that indicates the character position at which the substring will start, starting with position 1. The [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] method takes an index of the character in the string at which the substring is to start, starting with position 0. Thus, if you have a string "ABCDE", the individual characters are numbered 1,2,3,4,5 for use with the `Mid` function, but 0,1,2,3,4 for use with the method. + For an example of a one-based [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] function, consider the `Mid` function. It takes an argument that indicates the character position at which the substring will start, starting with position 1. The [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] method takes an index of the character in the string at which the substring is to start, starting with position 0. Thus, if you have a string "ABCDE", the individual characters are numbered 1,2,3,4,5 for use with the `Mid` function, but 0,1,2,3,4 for use with the method. ## Zero-Based - For an example of a zero-based [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] function, consider the `Split` function. It splits a string and returns an array containing the substrings. The [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] method also splits a string and returns an array containing the substrings. Because the `Split` function and method return [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] arrays, they must be zero-based. + For an example of a zero-based [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] function, consider the `Split` function. It splits a string and returns an array containing the substrings. The [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] method also splits a string and returns an array containing the substrings. Because the `Split` function and method return [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] arrays, they must be zero-based. ## See Also diff --git a/docs/visual-basic/programming-guide/language-features/variables/how-to-access-members-of-an-object.md b/docs/visual-basic/programming-guide/language-features/variables/how-to-access-members-of-an-object.md index 5ad249c8e6952..578f404092fab 100644 --- a/docs/visual-basic/programming-guide/language-features/variables/how-to-access-members-of-an-object.md +++ b/docs/visual-basic/programming-guide/language-features/variables/how-to-access-members-of-an-object.md @@ -76,7 +76,7 @@ When you have an object variable that refers to an object, you often want to wor #### To access members of an object for which you do not know the type at compile time -1. Declare the object variable to be of the [Object Data Type](../../../../visual-basic/language-reference/data-types/object-data-type.md). (Declaring a variable as `Object` is the same as declaring it as .) +1. Declare the object variable to be of the [Object Data Type](../../../../visual-basic/language-reference/data-types/object-data-type.md). (Declaring a variable as `Object` is the same as declaring it as .) ``` Dim someControl As Object diff --git a/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-what-type-an-object-variable-refers-to.md b/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-what-type-an-object-variable-refers-to.md index 61e750cb3e872..e7607fd47f066 100644 --- a/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-what-type-an-object-variable-refers-to.md +++ b/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-what-type-an-object-variable-refers-to.md @@ -40,14 +40,14 @@ An object variable contains a pointer to data that is stored elsewhere. The type ### To determine the exact type an object variable currently refers to -1. On the object variable, call the method to retrieve a object. +1. On the object variable, call the method to retrieve a object. ``` Dim myObject As Object myObject.GetType() ``` -2. On the class, call the shared method to retrieve the enumeration value for the object's type. +2. On the class, call the shared method to retrieve the enumeration value for the object's type. ``` Dim myObject As Object @@ -76,7 +76,7 @@ An object variable contains a pointer to data that is stored elsewhere. The type ## See Also - + [Object Variables](../../../../visual-basic/programming-guide/language-features/variables/object-variables.md) diff --git a/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-whether-two-objects-are-related.md b/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-whether-two-objects-are-related.md index 344877b786072..29c3726fee96e 100644 --- a/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-whether-two-objects-are-related.md +++ b/docs/visual-basic/programming-guide/language-features/variables/how-to-determine-whether-two-objects-are-related.md @@ -36,17 +36,17 @@ translation.priority.ht: - "zh-tw" --- # How to: Determine Whether Two Objects Are Related (Visual Basic) -You can compare two objects to determine the relationship, if any, between the classes from which they are created. The method of the class returns `True` if the specified class inherits from the current class, or if the current type is an interface supported by the specified class. +You can compare two objects to determine the relationship, if any, between the classes from which they are created. The method of the class returns `True` if the specified class inherits from the current class, or if the current type is an interface supported by the specified class. ### To determine if one object inherits from another object's class or interface 1. On the object you think might be of the base type, invoke the method. -2. On the object returned by , invoke the method. +2. On the object returned by , invoke the method. 3. In the argument list for , specify the object you think might be of the derived type. - returns `True` if its argument type inherits from the object type. + returns `True` if its argument type inherits from the object type. ## Example The following example determines whether one object represents a class derived from another object's class. @@ -67,11 +67,11 @@ Public Class testTheseClasses End Class ``` - Note the unexpected placement of the two object variables in the call to . The supposed base type is used to generate the class, and the supposed derived type is passed as an argument to the method. + Note the unexpected placement of the two object variables in the call to . The supposed base type is used to generate the class, and the supposed derived type is passed as an argument to the method. ## See Also - + [Object Data Type](../../../../visual-basic/language-reference/data-types/object-data-type.md) [Object Variables](../../../../visual-basic/programming-guide/language-features/variables/object-variables.md) diff --git a/docs/visual-basic/programming-guide/language-features/variables/object-variable-declaration.md b/docs/visual-basic/programming-guide/language-features/variables/object-variable-declaration.md index b187d967380a1..b1dad8522b2dd 100644 --- a/docs/visual-basic/programming-guide/language-features/variables/object-variable-declaration.md +++ b/docs/visual-basic/programming-guide/language-features/variables/object-variable-declaration.md @@ -44,7 +44,7 @@ translation.priority.ht: # Object Variable Declaration (Visual Basic) You use a normal declaration statement to declare an object variable. For the data type, you specify either `Object` (that is, the [Object Data Type](../../../../visual-basic/language-reference/data-types/object-data-type.md)) or a more specific class from which the object is to be created. - Declaring a variable as `Object` is the same as declaring it as . + Declaring a variable as `Object` is the same as declaring it as . When you declare a variable with a specific object class, it can access all the methods and properties exposed by that class and the classes from which it inherits. If you declare the variable with , it can access only the members of the class, unless you turn `Option Strict Off` to allow late binding. @@ -66,7 +66,7 @@ Dim objC As System.OperatingSystem ## Late Binding and Early Binding Sometimes the specific class is unknown until your code runs. In this case, you must declare the object variable with the `Object` data type. This creates a general reference to any type of object, and the specific class is assigned at run time. This is called *late binding*. Late binding requires additional execution time. It also limits your code to the methods and properties of the class you have most recently assigned to it. This can cause run-time errors if your code attempts to access members of a different class. - When you know the specific class at compile time, you should declare the object variable to be of that class. This is called *early binding*. Early binding improves performance and guarantees your code access to all the methods and properties of the specific class. In the preceding example declarations, if variable `objA` uses only objects of class , you should specify `As System.Windows.Forms.Label` in its declaration. + When you know the specific class at compile time, you should declare the object variable to be of that class. This is called *early binding*. Early binding improves performance and guarantees your code access to all the methods and properties of the specific class. In the preceding example declarations, if variable `objA` uses only objects of class , you should specify `As System.Windows.Forms.Label` in its declaration. ### Advantages of Early Binding Declaring an object variable as a specific class gives you several advantages: @@ -109,7 +109,7 @@ End Sub In this example, `p` can use only the members of the class itself, which do not include the `Left` property. On the other hand, `q` was declared to be of type , so it can use all the methods and properties of the class in the namespace. ## Flexibility of Object Variables - When working with objects in an inheritance hierarchy, you have a choice of which class to use for declaring your object variables. In making this choice, you must balance flexibility of object assignment against access to members of a class. For example, consider the inheritance hierarchy that leads to the class: + When working with objects in an inheritance hierarchy, you have a choice of which class to use for declaring your object variables. In making this choice, you must balance flexibility of object assignment against access to members of a class. For example, consider the inheritance hierarchy that leads to the class: diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-attributes.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-attributes.md index a08d97f3dfc1b..4266680c9a58b 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-attributes.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-attributes.md @@ -43,7 +43,7 @@ This example shows how to use an attribute axis property to access XML attribute [!code-vb[VbXMLSamples#11](../../../../visual-basic/language-reference/operators/codesnippet/VisualBasic/how-to-access-xml-attributes_1.vb)] ## See Also - + [XML Attribute Axis Property](../../../../visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md) [Accessing XML in Visual Basic](../../../../visual-basic/programming-guide/language-features/xml/accessing-xml.md) [XML](../../../../visual-basic/programming-guide/language-features/xml/index.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-child-elements.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-child-elements.md index 42e0e0ed884db..9d5db9a4967a9 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-child-elements.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-child-elements.md @@ -48,7 +48,7 @@ This example shows how to use a child axis property to access all XML child elem - A reference to the namespace. ## See Also - + [XML Child Axis Property](../../../../visual-basic/language-reference/xml-axis/xml-child-axis-property.md) [XML Value Property](../../../../visual-basic/language-reference/xml-axis/xml-value-property.md) [Accessing XML in Visual Basic](../../../../visual-basic/programming-guide/language-features/xml/accessing-xml.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-descendant-elements.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-descendant-elements.md index e81ef39ef8104..6cfc269a0e2a7 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-descendant-elements.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-access-xml-descendant-elements.md @@ -48,7 +48,7 @@ This example shows how to use a descendant axis property to access all XML eleme - A reference to the namespace. ## See Also - + [XML Descendant Axis Property](../../../../visual-basic/language-reference/xml-axis/xml-descendant-axis-property.md) [XML Value Property](../../../../visual-basic/language-reference/xml-axis/xml-value-property.md) [Accessing XML in Visual Basic](../../../../visual-basic/programming-guide/language-features/xml/accessing-xml.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-declare-and-use-xml-namespace-prefixes.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-declare-and-use-xml-namespace-prefixes.md index a773f59727f70..520461c9e3375 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-declare-and-use-xml-namespace-prefixes.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-declare-and-use-xml-namespace-prefixes.md @@ -46,7 +46,7 @@ This example shows how to import the XML namespace prefix `ns` and use it in an - A reference to the namespace. ## See Also - + [Imports Statement (XML Namespace)](../../../../visual-basic/language-reference/statements/imports-statement-xml-namespace.md) [XML Attribute Axis Property](../../../../visual-basic/language-reference/xml-axis/xml-attribute-axis-property.md) [XML Value Property](../../../../visual-basic/language-reference/xml-axis/xml-value-property.md) diff --git a/docs/visual-basic/programming-guide/language-features/xml/how-to-load-xml-from-a-file-string-or-stream.md b/docs/visual-basic/programming-guide/language-features/xml/how-to-load-xml-from-a-file-string-or-stream.md index 1eefc43459bbe..32bbb773ba842 100644 --- a/docs/visual-basic/programming-guide/language-features/xml/how-to-load-xml-from-a-file-string-or-stream.md +++ b/docs/visual-basic/programming-guide/language-features/xml/how-to-load-xml-from-a-file-string-or-stream.md @@ -51,24 +51,24 @@ You can create [XML Literals](../../../../visual-basic/language-reference/xml-li - To populate an XML literal such as an or object from a string, you can use the `Parse` method. - The following code example shows the use of the method to populate an object with XML from a string. + The following code example shows the use of the method to populate an object with XML from a string. [!code-vb[VbXMLSamples#47](../../../../visual-basic/language-reference/operators/codesnippet/VisualBasic/how-to-load-xml-from-a-file-string-or-stream_2.vb)] ### To load XML from a stream -- To populate an XML literal such as an or object from a stream, you can use the `Load` method or the method. +- To populate an XML literal such as an or object from a stream, you can use the `Load` method or the method. The following code example shows the use of the method to populate an object with XML from an XML stream. [!code-vb[VbXMLSamples#46](../../../../visual-basic/language-reference/operators/codesnippet/VisualBasic/how-to-load-xml-from-a-file-string-or-stream_3.vb)] ## See Also - - - - - + + + + + [XML Literals](../../../../visual-basic/language-reference/xml-literals/index.md) [XML](../../../../visual-basic/programming-guide/language-features/xml/index.md) [Manipulating XML in Visual Basic](../../../../visual-basic/programming-guide/language-features/xml/manipulating-xml.md) diff --git a/docs/visual-basic/programming-guide/program-structure/namespaces.md b/docs/visual-basic/programming-guide/program-structure/namespaces.md index 01a99cdd7efe0..83c18f81b3fa9 100644 --- a/docs/visual-basic/programming-guide/program-structure/namespaces.md +++ b/docs/visual-basic/programming-guide/program-structure/namespaces.md @@ -49,7 +49,7 @@ translation.priority.mt: # Namespaces in Visual Basic Namespaces organize the objects defined in an assembly. Assemblies can contain multiple namespaces, which can in turn contain other namespaces. Namespaces prevent ambiguity and simplify references when using large groups of objects such as class libraries. - For example, the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] defines the class in the namespace. The following code fragment shows how to declare a variable using the fully qualified name for this class: + For example, the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] defines the class in the namespace. The following code fragment shows how to declare a variable using the fully qualified name for this class: [!code-vb[VbVbalrApplication#6](../../../visual-basic/programming-guide/program-structure/codesnippet/VisualBasic/namespaces_1.vb)] @@ -89,7 +89,7 @@ Namespaces organize the objects defined in an assembly. Assemblies can contain m Within a namespace, you can define items such as modules, interfaces, classes, delegates, enumerations, structures, and other namespaces. You cannot define items such as properties, procedures, variables and events at the namespace level. These items must be declared within containers such as modules, structures, or classes. ## Global Keyword in Fully Qualified Names - If you have defined a nested hierarchy of namespaces, code inside that hierarchy might be blocked from accessing the namespace of the .NET Framework. The following example illustrates a hierarchy in which the `SpecialSpace.System` namespace blocks access to . + If you have defined a nested hierarchy of namespaces, code inside that hierarchy might be blocked from accessing the namespace of the .NET Framework. The following example illustrates a hierarchy in which the `SpecialSpace.System` namespace blocks access to . ```vb Namespace SpecialSpace @@ -104,7 +104,7 @@ Namespace SpecialSpace End Namespace ``` - As a result, the Visual Basic compiler cannot successfully resolve the reference to , because `SpecialSpace.System` does not define `Int32`. You can use the `Global` keyword to start the qualification chain at the outermost level of the .NET Framework class library. This allows you to specify the namespace or any other namespace in the class library. The following example illustrates this. + As a result, the Visual Basic compiler cannot successfully resolve the reference to , because `SpecialSpace.System` does not define `Int32`. You can use the `Global` keyword to start the qualification chain at the outermost level of the .NET Framework class library. This allows you to specify the namespace or any other namespace in the class library. The following example illustrates this. ```vb Namespace SpecialSpace @@ -119,7 +119,7 @@ Namespace SpecialSpace End Namespace ``` - You can use `Global` to access other root-level namespaces, such as , and any namespace associated with your project. + You can use `Global` to access other root-level namespaces, such as , and any namespace associated with your project. ## Global Keyword in Namespace Statements You can also use the `Global` keyword in a [Namespace Statement](../../../visual-basic/language-reference/statements/namespace-statement.md). This lets you define a namespace out of the root namespace of your project. @@ -144,7 +144,7 @@ End Namespace ## See Also - + [Assemblies and the Global Assembly Cache](../../../visual-basic/programming-guide/concepts/assemblies-gac/index.md) [How to: Create and Use Assemblies Using the Command Line](http://msdn.microsoft.com/library/70f65026-3687-4e9c-ab79-c18b97dd8be4) [References and the Imports Statement](../../../visual-basic/programming-guide/program-structure/references-and-the-imports-statement.md) diff --git a/docs/visual-basic/programming-guide/program-structure/naming-conventions.md b/docs/visual-basic/programming-guide/program-structure/naming-conventions.md index 871352b5a2193..c8764a9c9cf76 100644 --- a/docs/visual-basic/programming-guide/program-structure/naming-conventions.md +++ b/docs/visual-basic/programming-guide/program-structure/naming-conventions.md @@ -60,7 +60,7 @@ When you name an element in your Visual Basic application, the first character o - For long or frequently used terms, use abbreviations to keep name lengths reasonable, for example, "HTML", instead of "Hypertext Markup Language". In general, variable names greater than 32 characters are difficult to read on a monitor set to a low resolution. Also, make sure your abbreviations are consistent throughout the entire application. Randomly switching in a project between "HTML" and "Hypertext Markup Language" can lead to confusion. -- Avoid using names in an inner scope that are the same as names in an outer scope. Errors can result if the wrong variable is accessed. If a conflict occurs between a variable and the keyword of the same name, you must identify the keyword by preceding it with the appropriate type library. For example, if you have a variable called `Date`, you can use the intrinsic `Date` function only by calling . +- Avoid using names in an inner scope that are the same as names in an outer scope. Errors can result if the wrong variable is accessed. If a conflict occurs between a variable and the keyword of the same name, you must identify the keyword by preceding it with the appropriate type library. For example, if you have a variable called `Date`, you can use the intrinsic `Date` function only by calling . ## See Also [Keywords as Element Names in Code](../../../visual-basic/programming-guide/program-structure/keywords-as-element-names-in-code.md) diff --git a/docs/visual-basic/programming-guide/program-structure/references-and-the-imports-statement.md b/docs/visual-basic/programming-guide/program-structure/references-and-the-imports-statement.md index f8b89ab22b07d..65a84879a6060 100644 --- a/docs/visual-basic/programming-guide/program-structure/references-and-the-imports-statement.md +++ b/docs/visual-basic/programming-guide/program-structure/references-and-the-imports-statement.md @@ -56,11 +56,11 @@ You can make external objects available to your project by choosing the **Add Re > Do not confuse project references with the `Imports` statement or the `Declare` statement. Project references make external objects, such as objects in assemblies, available to [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] projects. The `Imports` statement is used to simplify access to project references, but does not provide access to these objects. The `Declare` statement is used to declare a reference to an external procedure in a dynamic-link library (DLL). ## Using Aliases with the Imports Statement - The `Imports` statement makes it easier to access methods of classes by eliminating the need to explicitly type the fully qualified names of references. Aliases let you assign a friendlier name to just one part of a namespace. For example, the carriage return/line feed sequence that causes a single piece of text to be displayed on multiple lines is part of the module in the namespace. To use this constant in a program without an alias, you would need to type the following code: + The `Imports` statement makes it easier to access methods of classes by eliminating the need to explicitly type the fully qualified names of references. Aliases let you assign a friendlier name to just one part of a namespace. For example, the carriage return/line feed sequence that causes a single piece of text to be displayed on multiple lines is part of the module in the namespace. To use this constant in a program without an alias, you would need to type the following code: [!code-vb[VbVbalrApplication#3](../../../visual-basic/programming-guide/program-structure/codesnippet/VisualBasic/references-and-the-imports-statement_1.vb)] - `Imports` statements must always be the first lines immediately following any `Option` statements in a module. The following code fragment shows how to import and assign an alias to the module: + `Imports` statements must always be the first lines immediately following any `Option` statements in a module. The following code fragment shows how to import and assign an alias to the module: [!code-vb[VbVbalrApplication#4](../../../visual-basic/programming-guide/program-structure/codesnippet/VisualBasic/references-and-the-imports-statement_2.vb)] diff --git a/docs/visual-basic/reference/index.md b/docs/visual-basic/reference/index.md index 40e338d5d4e8d..a19dc6984db89 100644 --- a/docs/visual-basic/reference/index.md +++ b/docs/visual-basic/reference/index.md @@ -51,10 +51,10 @@ This section provides links to reference information about various aspects of [! Provides links to the complete [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] language specification, which contains detailed information on all aspects of the language. ## Reference - + This namespace contains classes for the Visual Basic Power Packs controls. Visual Basic Power Packs controls are additional Windows Forms controls. - + This namespace provides a component that enables you to print a facsimile of the form as it appears on screen. ## Related Sections diff --git a/includes/migration-guide/retargeting/adonet/dbparameterprecision-dbparameterscale-are-now-public-virtual-members.md b/includes/migration-guide/retargeting/adonet/dbparameterprecision-dbparameterscale-are-now-public-virtual-members.md index d7eb41365606b..fabae44e416a1 100644 --- a/includes/migration-guide/retargeting/adonet/dbparameterprecision-dbparameterscale-are-now-public-virtual-members.md +++ b/includes/migration-guide/retargeting/adonet/dbparameterprecision-dbparameterscale-are-now-public-virtual-members.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5.1| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0068
| diff --git a/includes/migration-guide/retargeting/asp/htmltextwriter-does-not-render-br-element-correctly.md b/includes/migration-guide/retargeting/asp/htmltextwriter-does-not-render-br-element-correctly.md index 62c407eec862c..6fcd3af3e2a66 100644 --- a/includes/migration-guide/retargeting/asp/htmltextwriter-does-not-render-br-element-correctly.md +++ b/includes/migration-guide/retargeting/asp/htmltextwriter-does-not-render-br-element-correctly.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.6| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0101
| diff --git a/includes/migration-guide/retargeting/asp/httpruntimeappdomainapppath-throws-nullreferenceexception.md b/includes/migration-guide/retargeting/asp/httpruntimeappdomainapppath-throws-nullreferenceexception.md index dff58c67aa6bd..f96af2ff1e01d 100644 --- a/includes/migration-guide/retargeting/asp/httpruntimeappdomainapppath-throws-nullreferenceexception.md +++ b/includes/migration-guide/retargeting/asp/httpruntimeappdomainapppath-throws-nullreferenceexception.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/asp/machinekeyencode-machinekeydecode-methods-are-now-obsolete.md b/includes/migration-guide/retargeting/asp/machinekeyencode-machinekeydecode-methods-are-now-obsolete.md index 72e2fd479cd83..5bdeaf6cefbc9 100644 --- a/includes/migration-guide/retargeting/asp/machinekeyencode-machinekeydecode-methods-are-now-obsolete.md +++ b/includes/migration-guide/retargeting/asp/machinekeyencode-machinekeydecode-methods-are-now-obsolete.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0028
| diff --git a/includes/migration-guide/retargeting/asp/webutilityhtmlencode-webutilityhtmldecode-round-trip-bmp-correctly.md b/includes/migration-guide/retargeting/asp/webutilityhtmlencode-webutilityhtmldecode-round-trip-bmp-correctly.md index 0401e27462b4e..c9bb508b9f1b2 100644 --- a/includes/migration-guide/retargeting/asp/webutilityhtmlencode-webutilityhtmldecode-round-trip-bmp-correctly.md +++ b/includes/migration-guide/retargeting/asp/webutilityhtmlencode-webutilityhtmldecode-round-trip-bmp-correctly.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/core/aescryptoserviceprovider-decryptor-provides-reusable-transform.md b/includes/migration-guide/retargeting/core/aescryptoserviceprovider-decryptor-provides-reusable-transform.md index c0e4edd7b57c1..4869fcd803642 100644 --- a/includes/migration-guide/retargeting/core/aescryptoserviceprovider-decryptor-provides-reusable-transform.md +++ b/includes/migration-guide/retargeting/core/aescryptoserviceprovider-decryptor-provides-reusable-transform.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/core/calls-claimsidentity-constructors.md b/includes/migration-guide/retargeting/core/calls-claimsidentity-constructors.md index 2402ca1bbf3f9..9356d969d7a93 100644 --- a/includes/migration-guide/retargeting/core/calls-claimsidentity-constructors.md +++ b/includes/migration-guide/retargeting/core/calls-claimsidentity-constructors.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/core/currentculture-currentuiculture-flow-across-tasks.md b/includes/migration-guide/retargeting/core/currentculture-currentuiculture-flow-across-tasks.md index 704ff0e2f136c..9562990e7712c 100644 --- a/includes/migration-guide/retargeting/core/currentculture-currentuiculture-flow-across-tasks.md +++ b/includes/migration-guide/retargeting/core/currentculture-currentuiculture-flow-across-tasks.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/core/iasyncresultcompletedsynchronously-property-must-be-correct-for-resulting.md b/includes/migration-guide/retargeting/core/iasyncresultcompletedsynchronously-property-must-be-correct-for-resulting.md index 291faf10cdb60..5f5ac73123f02 100644 --- a/includes/migration-guide/retargeting/core/iasyncresultcompletedsynchronously-property-must-be-correct-for-resulting.md +++ b/includes/migration-guide/retargeting/core/iasyncresultcompletedsynchronously-property-must-be-correct-for-resulting.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0058
| diff --git a/includes/migration-guide/retargeting/core/listlttgtforeach-can-throw-exception-when-modifying-list-item.md b/includes/migration-guide/retargeting/core/listlttgtforeach-can-throw-exception-when-modifying-list-item.md index 2ca2e3ddf5bff..5e9262c344fe0 100644 --- a/includes/migration-guide/retargeting/core/listlttgtforeach-can-throw-exception-when-modifying-list-item.md +++ b/includes/migration-guide/retargeting/core/listlttgtforeach-can-throw-exception-when-modifying-list-item.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0005
| diff --git a/includes/migration-guide/retargeting/core/path-colon-checks-are-stricter.md b/includes/migration-guide/retargeting/core/path-colon-checks-are-stricter.md index 26bbe53b89f8e..a122e589d7740 100644 --- a/includes/migration-guide/retargeting/core/path-colon-checks-are-stricter.md +++ b/includes/migration-guide/retargeting/core/path-colon-checks-are-stricter.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/core/systemuri-parsing-adheres-rfc-3987.md b/includes/migration-guide/retargeting/core/systemuri-parsing-adheres-rfc-3987.md index 00e7ebfdd60c5..ab0dfcc5b9cc1 100644 --- a/includes/migration-guide/retargeting/core/systemuri-parsing-adheres-rfc-3987.md +++ b/includes/migration-guide/retargeting/core/systemuri-parsing-adheres-rfc-3987.md @@ -7,6 +7,6 @@ |Scope|Major| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0006D
  • CD0006C
  • CD0006F
  • CD0006E
  • CD0006A
  • CD0006G
  • CD0006B
| diff --git a/includes/migration-guide/retargeting/core/systemuriiswellformeduristring-method-returns-false-for-relative-uris-with.md b/includes/migration-guide/retargeting/core/systemuriiswellformeduristring-method-returns-false-for-relative-uris-with.md index c6f18e93ceb29..214925a9187b4 100644 --- a/includes/migration-guide/retargeting/core/systemuriiswellformeduristring-method-returns-false-for-relative-uris-with.md +++ b/includes/migration-guide/retargeting/core/systemuriiswellformeduristring-method-returns-false-for-relative-uris-with.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/networking/default-value-servicepointmanagersecurityprotocol.md b/includes/migration-guide/retargeting/networking/default-value-servicepointmanagersecurityprotocol.md index 8c9394e18c40d..869ac36ca10b7 100644 --- a/includes/migration-guide/retargeting/networking/default-value-servicepointmanagersecurityprotocol.md +++ b/includes/migration-guide/retargeting/networking/default-value-servicepointmanagersecurityprotocol.md @@ -2,10 +2,10 @@ | | | |---|---| -|Details|Starting with apps that target the .NET Framework 4.7, the default value of the property is . This change allows .NET Framework networking APIs based on SslStream (such as FTP, HTTPS, and SMTP) to inherit the default security protocols from the operating system instead of using hard-coded values defined by the .NET Framework. The default varies by operating system and any custom configuration performed by the system administrator. For information on the default SChannel protocol in each version of the Windows operating system, see [Protocols in TLS/SSL (Schannel SSP)](https://msdn.microsoft.com/library/windows/desktop/mt808159.aspx).For applications that target an earlier version of the .NET Framework, the default value of the property depends on the version of the .NET Framework targeted. See [Retargeting Changes in the .NET Framework 4.6](~/docs/framework/migration-guide/retargeting/index.md) for more information.| -|Suggestion|This change affects applications that target the .NET Framework 4.7 or later versions.If you prefer to use a defined protocol rather than relying on the system default, you can explicitly set the value of the property.| +|Details|Starting with apps that target the .NET Framework 4.7, the default value of the property is . This change allows .NET Framework networking APIs based on SslStream (such as FTP, HTTPS, and SMTP) to inherit the default security protocols from the operating system instead of using hard-coded values defined by the .NET Framework. The default varies by operating system and any custom configuration performed by the system administrator. For information on the default SChannel protocol in each version of the Windows operating system, see [Protocols in TLS/SSL (Schannel SSP)](https://msdn.microsoft.com/library/windows/desktop/mt808159.aspx).For applications that target an earlier version of the .NET Framework, the default value of the property depends on the version of the .NET Framework targeted. See [Retargeting Changes in the .NET Framework 4.6](~/docs/framework/migration-guide/retargeting/index.md) for more information.| +|Suggestion|This change affects applications that target the .NET Framework 4.7 or later versions.If you prefer to use a defined protocol rather than relying on the system default, you can explicitly set the value of the property.| |Scope|Minor| |Version|4.7| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/networking/only-tls-10-11-12-protocols-supported-systemnetservicepointmanager.md b/includes/migration-guide/retargeting/networking/only-tls-10-11-12-protocols-supported-systemnetservicepointmanager.md index ee5fe34ed5eb2..c414d72c2be4a 100644 --- a/includes/migration-guide/retargeting/networking/only-tls-10-11-12-protocols-supported-systemnetservicepointmanager.md +++ b/includes/migration-guide/retargeting/networking/only-tls-10-11-12-protocols-supported-systemnetservicepointmanager.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/networking/sslstream-supports-tls-alerts.md b/includes/migration-guide/retargeting/networking/sslstream-supports-tls-alerts.md index d54f73c046063..ccf2919fd1a69 100644 --- a/includes/migration-guide/retargeting/networking/sslstream-supports-tls-alerts.md +++ b/includes/migration-guide/retargeting/networking/sslstream-supports-tls-alerts.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.7| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/security/cspparametersparentwindowhandle-now-expects-hwnd-value.md b/includes/migration-guide/retargeting/security/cspparametersparentwindowhandle-now-expects-hwnd-value.md index eed2d97acfa1c..0e4e9ac77a0bb 100644 --- a/includes/migration-guide/retargeting/security/cspparametersparentwindowhandle-now-expects-hwnd-value.md +++ b/includes/migration-guide/retargeting/security/cspparametersparentwindowhandle-now-expects-hwnd-value.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.7| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/security/rsacng-now-correctly-loads-rsa-keys-non-standard-key-size.md b/includes/migration-guide/retargeting/security/rsacng-now-correctly-loads-rsa-keys-non-standard-key-size.md index e84c2a33e942a..aa9481840e806 100644 --- a/includes/migration-guide/retargeting/security/rsacng-now-correctly-loads-rsa-keys-non-standard-key-size.md +++ b/includes/migration-guide/retargeting/security/rsacng-now-correctly-loads-rsa-keys-non-standard-key-size.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/wcf/calling-createdefaultauthorizationcontext-with-null-argument-has-changed.md b/includes/migration-guide/retargeting/wcf/calling-createdefaultauthorizationcontext-with-null-argument-has-changed.md index 13e7035ce0ec3..33a2dec0aca5f 100644 --- a/includes/migration-guide/retargeting/wcf/calling-createdefaultauthorizationcontext-with-null-argument-has-changed.md +++ b/includes/migration-guide/retargeting/wcf/calling-createdefaultauthorizationcontext-with-null-argument-has-changed.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.6| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0138
| diff --git a/includes/migration-guide/retargeting/wcf/deadlock-may-result-when-using-reentrant-services.md b/includes/migration-guide/retargeting/wcf/deadlock-may-result-when-using-reentrant-services.md index 1f3832a194a26..6564147a5d61a 100644 --- a/includes/migration-guide/retargeting/wcf/deadlock-may-result-when-using-reentrant-services.md +++ b/includes/migration-guide/retargeting/wcf/deadlock-may-result-when-using-reentrant-services.md @@ -3,9 +3,9 @@ | | | |---|---| |Details|A deadlock may result in a Reentrant service, which restricts instances of the service to one thread of execution at a time. Services prone to encounter this problem will have the following in their code:
[ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Reentrant)]
| -|Suggestion|To address this issue, you can do the following:
  • Set the service's concurrency mode to or <System.ServiceModel.ConcurrencyMode.Multiple?displayProperty=fullName>. For example:
[ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Single)]
  • Install the latest update to the .NET Framework 4.6.2, or upgrade to a later version of the .NET Framework. This disables the flow of the in . This behavior is configurable; it is equivalent to adding the following app setting to your configuration file:
<appSettings>
<add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="true" />
</appSettings>

The value of `Switch.System.ServiceModel.DisableOperationContextAsyncFlow` should never be set to `false` for Rentrant services.
| +|Suggestion|To address this issue, you can do the following:
  • Set the service's concurrency mode to or <System.ServiceModel.ConcurrencyMode.Multiple?displayProperty=nameWithType>. For example:
[ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Single)]
  • Install the latest update to the .NET Framework 4.6.2, or upgrade to a later version of the .NET Framework. This disables the flow of the in . This behavior is configurable; it is equivalent to adding the following app setting to your configuration file:
<appSettings>
<add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="true" />
</appSettings>

The value of `Switch.System.ServiceModel.DisableOperationContextAsyncFlow` should never be set to `false` for Rentrant services.
| |Scope|Minor| |Version|4.6.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/wcf/operationcontextcurrent-may-return-null-when-called-using-clause.md b/includes/migration-guide/retargeting/wcf/operationcontextcurrent-may-return-null-when-called-using-clause.md index 0ddb369d2105c..c1963a87a385f 100644 --- a/includes/migration-guide/retargeting/wcf/operationcontextcurrent-may-return-null-when-called-using-clause.md +++ b/includes/migration-guide/retargeting/wcf/operationcontextcurrent-may-return-null-when-called-using-clause.md @@ -2,10 +2,10 @@ | | | |---|---| -|Details| may return null and a may result if all of the following conditions are true:
  • You retrieve the value of the property in a method that returns a or .
  • You instantiate the object in a using clause.
  • You retrieve the value of the property within the using statement. For example:
using (new OperationContextScope(OperationContext.Current))
{
OperationContext context = OperationContext.Current;      // OperationContext.Current is null.
// ...
}
| -|Suggestion|To address this issue, you can do the following:
  • Modify your code as follows to instantiate a new non-null object:
OperationContext ocx = OperationContext.Current;
using (new OperationContextScope(OperationContext.Current))
{
OperationContext.Current = new OperationContext(ocx.Channel);
// ...
}
  • Install the latest update to the .NET Framework 4.6.2, or upgrade to a later version of the .NET Framework. This disables the flow of the in and restores the behavior of WCF applications in the .NET Framework 4.6.1 and earlier versions. This behavior is configurable; it is equivalent to adding the following app setting to your configuration file:
<appSettings>
<add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="true" />
</appSettings>
If this change is undesirable and your application depends on execution context flowing between operation contexts, you can enable its flow as follows:
<appSettings>
<add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="false" />
</appSettings>
| +|Details| may return null and a may result if all of the following conditions are true:
  • You retrieve the value of the property in a method that returns a or .
  • You instantiate the object in a using clause.
  • You retrieve the value of the property within the using statement. For example:
using (new OperationContextScope(OperationContext.Current))
{
OperationContext context = OperationContext.Current;      // OperationContext.Current is null.
// ...
}
| +|Suggestion|To address this issue, you can do the following:
  • Modify your code as follows to instantiate a new non-null object:
OperationContext ocx = OperationContext.Current;
using (new OperationContextScope(OperationContext.Current))
{
OperationContext.Current = new OperationContext(ocx.Channel);
// ...
}
  • Install the latest update to the .NET Framework 4.6.2, or upgrade to a later version of the .NET Framework. This disables the flow of the in and restores the behavior of WCF applications in the .NET Framework 4.6.1 and earlier versions. This behavior is configurable; it is equivalent to adding the following app setting to your configuration file:
<appSettings>
<add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="true" />
</appSettings>
If this change is undesirable and your application depends on execution context flowing between operation contexts, you can enable its flow as follows:
<appSettings>
<add key="Switch.System.ServiceModel.DisableOperationContextAsyncFlow" value="false" />
</appSettings>
| |Scope|Edge| |Version|4.6.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/wcf/serialization-control-characters-with-datacontractjsonserializer-now.md b/includes/migration-guide/retargeting/wcf/serialization-control-characters-with-datacontractjsonserializer-now.md index 5c6c655a2a962..b3cc0c66ea276 100644 --- a/includes/migration-guide/retargeting/wcf/serialization-control-characters-with-datacontractjsonserializer-now.md +++ b/includes/migration-guide/retargeting/wcf/serialization-control-characters-with-datacontractjsonserializer-now.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.7| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/wcf/x509certificateclaimsetfindclaims-considers-all-claimtypes.md b/includes/migration-guide/retargeting/wcf/x509certificateclaimsetfindclaims-considers-all-claimtypes.md index ddd9145aa8fee..2ef52ed9d3352 100644 --- a/includes/migration-guide/retargeting/wcf/x509certificateclaimsetfindclaims-considers-all-claimtypes.md +++ b/includes/migration-guide/retargeting/wcf/x509certificateclaimsetfindclaims-considers-all-claimtypes.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.6.1| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0143
| diff --git a/includes/migration-guide/retargeting/wf/new-ambiguous-dispatcherinvoke-overloads-could-result-different-behavior.md b/includes/migration-guide/retargeting/wf/new-ambiguous-dispatcherinvoke-overloads-could-result-different-behavior.md index cdaee78b53388..f02a0cb5c919f 100644 --- a/includes/migration-guide/retargeting/wf/new-ambiguous-dispatcherinvoke-overloads-could-result-different-behavior.md +++ b/includes/migration-guide/retargeting/wf/new-ambiguous-dispatcherinvoke-overloads-could-result-different-behavior.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0023
| diff --git a/includes/migration-guide/retargeting/wf/some-workflow-drag-and-drop-apis-are-obsolete.md b/includes/migration-guide/retargeting/wf/some-workflow-drag-and-drop-apis-are-obsolete.md index 06c8c3aa4ddf6..e42414056d5b2 100644 --- a/includes/migration-guide/retargeting/wf/some-workflow-drag-and-drop-apis-are-obsolete.md +++ b/includes/migration-guide/retargeting/wf/some-workflow-drag-and-drop-apis-are-obsolete.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0022
| diff --git a/includes/migration-guide/retargeting/wf/workflowdesignerload-doesnt-remove-symbol-property.md b/includes/migration-guide/retargeting/wf/workflowdesignerload-doesnt-remove-symbol-property.md index 4cb2e40eafe0d..0a141d2913053 100644 --- a/includes/migration-guide/retargeting/wf/workflowdesignerload-doesnt-remove-symbol-property.md +++ b/includes/migration-guide/retargeting/wf/workflowdesignerload-doesnt-remove-symbol-property.md @@ -7,6 +7,6 @@ |Scope|Major| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0082
| diff --git a/includes/migration-guide/retargeting/winforms/applicationfiltermessage-no-longer-throws-for-re-entrant-implementations.md b/includes/migration-guide/retargeting/winforms/applicationfiltermessage-no-longer-throws-for-re-entrant-implementations.md index 718f28973cdb8..087acb38944fe 100644 --- a/includes/migration-guide/retargeting/winforms/applicationfiltermessage-no-longer-throws-for-re-entrant-implementations.md +++ b/includes/migration-guide/retargeting/winforms/applicationfiltermessage-no-longer-throws-for-re-entrant-implementations.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.6.1| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0144
| diff --git a/includes/migration-guide/retargeting/winforms/dataobjectgetdata-now-retrieves-data-utf-8.md b/includes/migration-guide/retargeting/winforms/dataobjectgetdata-now-retrieves-data-utf-8.md index 4a7a211995fa9..df577b60c35f6 100644 --- a/includes/migration-guide/retargeting/winforms/dataobjectgetdata-now-retrieves-data-utf-8.md +++ b/includes/migration-guide/retargeting/winforms/dataobjectgetdata-now-retrieves-data-utf-8.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0073
| diff --git a/includes/migration-guide/retargeting/winforms/encoderparameter-ctor-obsolete.md b/includes/migration-guide/retargeting/winforms/encoderparameter-ctor-obsolete.md index dfb09f1fb6d37..dfa030748ad11 100644 --- a/includes/migration-guide/retargeting/winforms/encoderparameter-ctor-obsolete.md +++ b/includes/migration-guide/retargeting/winforms/encoderparameter-ctor-obsolete.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0024
| diff --git a/includes/migration-guide/retargeting/winforms/incorrect-implementation-memberdescriptorequals.md b/includes/migration-guide/retargeting/winforms/incorrect-implementation-memberdescriptorequals.md index 9ff0dfc95a8b9..ad1701546c350 100644 --- a/includes/migration-guide/retargeting/winforms/incorrect-implementation-memberdescriptorequals.md +++ b/includes/migration-guide/retargeting/winforms/incorrect-implementation-memberdescriptorequals.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6.2| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/wpf/nullreferenceexception-exception-handling-code-from.md b/includes/migration-guide/retargeting/wpf/nullreferenceexception-exception-handling-code-from.md index a50808fa5fd72..0ac7f635421a8 100644 --- a/includes/migration-guide/retargeting/wpf/nullreferenceexception-exception-handling-code-from.md +++ b/includes/migration-guide/retargeting/wpf/nullreferenceexception-exception-handling-code-from.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.7| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/wpf/two-way-data-binding-property-with-non-public-setter-not-supported.md b/includes/migration-guide/retargeting/wpf/two-way-data-binding-property-with-non-public-setter-not-supported.md index b188db228a983..2f48cde53c21d 100644 --- a/includes/migration-guide/retargeting/wpf/two-way-data-binding-property-with-non-public-setter-not-supported.md +++ b/includes/migration-guide/retargeting/wpf/two-way-data-binding-property-with-non-public-setter-not-supported.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5.1| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0129
| diff --git a/includes/migration-guide/retargeting/wpf/wpf-textboxtext-can-be-out-of-sync-with-databinding.md b/includes/migration-guide/retargeting/wpf/wpf-textboxtext-can-be-out-of-sync-with-databinding.md index 9d683dede9c11..e7ef4c6dac8f4 100644 --- a/includes/migration-guide/retargeting/wpf/wpf-textboxtext-can-be-out-of-sync-with-databinding.md +++ b/includes/migration-guide/retargeting/wpf/wpf-textboxtext-can-be-out-of-sync-with-databinding.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/retargeting/xml/xmlwriter-throws-on-invalid-surrogate-pairs.md b/includes/migration-guide/retargeting/xml/xmlwriter-throws-on-invalid-surrogate-pairs.md index d424070b99cbc..1a869ae6809a6 100644 --- a/includes/migration-guide/retargeting/xml/xmlwriter-throws-on-invalid-surrogate-pairs.md +++ b/includes/migration-guide/retargeting/xml/xmlwriter-throws-on-invalid-surrogate-pairs.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6| |Type|Retargeting| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/adonet/adonet-now-attempts-automatically-reconnect-broken-sql-connections.md b/includes/migration-guide/runtime/adonet/adonet-now-attempts-automatically-reconnect-broken-sql-connections.md index d53292fb39ba0..94e0abf6c54b8 100644 --- a/includes/migration-guide/runtime/adonet/adonet-now-attempts-automatically-reconnect-broken-sql-connections.md +++ b/includes/migration-guide/runtime/adonet/adonet-now-attempts-automatically-reconnect-broken-sql-connections.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5.1| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/asp/gridviews-with-allowcustompaging-set-true-may-fire-pageindexchanging-event.md b/includes/migration-guide/runtime/asp/gridviews-with-allowcustompaging-set-true-may-fire-pageindexchanging-event.md index 58329c89717ea..c33eea4d79465 100644 --- a/includes/migration-guide/runtime/asp/gridviews-with-allowcustompaging-set-true-may-fire-pageindexchanging-event.md +++ b/includes/migration-guide/runtime/asp/gridviews-with-allowcustompaging-set-true-may-fire-pageindexchanging-event.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/asp/httprequestcontentencoding-property-prohibits-utf7.md b/includes/migration-guide/runtime/asp/httprequestcontentencoding-property-prohibits-utf7.md index 3c34dfd6c5e2e..affecf708e6c1 100644 --- a/includes/migration-guide/runtime/asp/httprequestcontentencoding-property-prohibits-utf7.md +++ b/includes/migration-guide/runtime/asp/httprequestcontentencoding-property-prohibits-utf7.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0043
| diff --git a/includes/migration-guide/runtime/asp/httputilityjavascriptstringencode-escapes-ampersand.md b/includes/migration-guide/runtime/asp/httputilityjavascriptstringencode-escapes-ampersand.md index d037ab2d4c631..c9f0b1cd87374 100644 --- a/includes/migration-guide/runtime/asp/httputilityjavascriptstringencode-escapes-ampersand.md +++ b/includes/migration-guide/runtime/asp/httputilityjavascriptstringencode-escapes-ampersand.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0044A
  • CD0044B
| diff --git a/includes/migration-guide/runtime/asp/sharing-session-state-with-aspnet-stateserver-requires-all-servers-web-farm.md b/includes/migration-guide/runtime/asp/sharing-session-state-with-aspnet-stateserver-requires-all-servers-web-farm.md index 4195c2be031c6..d048625c89ebe 100644 --- a/includes/migration-guide/runtime/asp/sharing-session-state-with-aspnet-stateserver-requires-all-servers-web-farm.md +++ b/includes/migration-guide/runtime/asp/sharing-session-state-with-aspnet-stateserver-requires-all-servers-web-farm.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/asp/webutilityhtmldecode-no-longer-decodes-invalid-input-sequences.md b/includes/migration-guide/runtime/asp/webutilityhtmldecode-no-longer-decodes-invalid-input-sequences.md index a077076651a39..bfb17761c23d3 100644 --- a/includes/migration-guide/runtime/asp/webutilityhtmldecode-no-longer-decodes-invalid-input-sequences.md +++ b/includes/migration-guide/runtime/asp/webutilityhtmldecode-no-longer-decodes-invalid-input-sequences.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0061
| diff --git a/includes/migration-guide/runtime/core/appdomainsetupdynamicbase-no-longer-randomized-by.md b/includes/migration-guide/runtime/core/appdomainsetupdynamicbase-no-longer-randomized-by.md index e7ab0cdfce7b7..49dabd3b482d4 100644 --- a/includes/migration-guide/runtime/core/appdomainsetupdynamicbase-no-longer-randomized-by.md +++ b/includes/migration-guide/runtime/core/appdomainsetupdynamicbase-no-longer-randomized-by.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/core/assemblies-compiled-with-regexcompiletoassembly-breaks-between-40-45.md b/includes/migration-guide/runtime/core/assemblies-compiled-with-regexcompiletoassembly-breaks-between-40-45.md index e969449c0c27f..19ffe6afb4bc1 100644 --- a/includes/migration-guide/runtime/core/assemblies-compiled-with-regexcompiletoassembly-breaks-between-40-45.md +++ b/includes/migration-guide/runtime/core/assemblies-compiled-with-regexcompiletoassembly-breaks-between-40-45.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/core/blockingcollectionlttgttrytakefromany-does-not-throw-anymore.md b/includes/migration-guide/runtime/core/blockingcollectionlttgttrytakefromany-does-not-throw-anymore.md index 4fa4c81d540e6..3a0c42427eea0 100644 --- a/includes/migration-guide/runtime/core/blockingcollectionlttgttrytakefromany-does-not-throw-anymore.md +++ b/includes/migration-guide/runtime/core/blockingcollectionlttgttrytakefromany-does-not-throw-anymore.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0018A
  • CD0018B
| diff --git a/includes/migration-guide/runtime/core/calling-attributegetcustomattributes-on-an-indexer-property-no-longer-throws.md b/includes/migration-guide/runtime/core/calling-attributegetcustomattributes-on-an-indexer-property-no-longer-throws.md index bfa3f6e1623ae..22242097c95e5 100644 --- a/includes/migration-guide/runtime/core/calling-attributegetcustomattributes-on-an-indexer-property-no-longer-throws.md +++ b/includes/migration-guide/runtime/core/calling-attributegetcustomattributes-on-an-indexer-property-no-longer-throws.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.6| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0112
| diff --git a/includes/migration-guide/runtime/core/change-behavior-for-taskwaitall-methods-with-time-out-arguments.md b/includes/migration-guide/runtime/core/change-behavior-for-taskwaitall-methods-with-time-out-arguments.md index ad9fb7664e289..6376bc8032005 100644 --- a/includes/migration-guide/runtime/core/change-behavior-for-taskwaitall-methods-with-time-out-arguments.md +++ b/includes/migration-guide/runtime/core/change-behavior-for-taskwaitall-methods-with-time-out-arguments.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0026
| diff --git a/includes/migration-guide/runtime/core/concurrentqueuelttgttrypeek-can-return-an-erroneous-null-via-its-out.md b/includes/migration-guide/runtime/core/concurrentqueuelttgttrypeek-can-return-an-erroneous-null-via-its-out.md index 9669dfc717743..20b2286d4df94 100644 --- a/includes/migration-guide/runtime/core/concurrentqueuelttgttrypeek-can-return-an-erroneous-null-via-its-out.md +++ b/includes/migration-guide/runtime/core/concurrentqueuelttgttrypeek-can-return-an-erroneous-null-via-its-out.md @@ -7,6 +7,6 @@ |Scope|Major| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0095
| diff --git a/includes/migration-guide/runtime/core/etw-eventlisteners-do-not-capture-events-from-providers-with-explicit.md b/includes/migration-guide/runtime/core/etw-eventlisteners-do-not-capture-events-from-providers-with-explicit.md index 070bbde383c77..45a40f53a447b 100644 --- a/includes/migration-guide/runtime/core/etw-eventlisteners-do-not-capture-events-from-providers-with-explicit.md +++ b/includes/migration-guide/runtime/core/etw-eventlisteners-do-not-capture-events-from-providers-with-explicit.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0105
| diff --git a/includes/migration-guide/runtime/core/eventlistener-truncates-strings-with-embedded-nulls.md b/includes/migration-guide/runtime/core/eventlistener-truncates-strings-with-embedded-nulls.md index f7611b0c28019..c60adf96d358d 100644 --- a/includes/migration-guide/runtime/core/eventlistener-truncates-strings-with-embedded-nulls.md +++ b/includes/migration-guide/runtime/core/eventlistener-truncates-strings-with-embedded-nulls.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5.1| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0046
| diff --git a/includes/migration-guide/runtime/core/exceptions-during-unobserved-processing-systemthreadingtaskstask-no-longer.md b/includes/migration-guide/runtime/core/exceptions-during-unobserved-processing-systemthreadingtaskstask-no-longer.md index e30936eba6106..bbc7b3d9d3a5b 100644 --- a/includes/migration-guide/runtime/core/exceptions-during-unobserved-processing-systemthreadingtaskstask-no-longer.md +++ b/includes/migration-guide/runtime/core/exceptions-during-unobserved-processing-systemthreadingtaskstask-no-longer.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0055
| diff --git a/includes/migration-guide/runtime/core/listsort-algorithm-changed.md b/includes/migration-guide/runtime/core/listsort-algorithm-changed.md index 8b8d812bf666f..609864e49cdef 100644 --- a/includes/migration-guide/runtime/core/listsort-algorithm-changed.md +++ b/includes/migration-guide/runtime/core/listsort-algorithm-changed.md @@ -7,5 +7,5 @@ |Scope|Transparent| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/core/persian-calendar-now-uses-hijri-solar-algorithm.md b/includes/migration-guide/runtime/core/persian-calendar-now-uses-hijri-solar-algorithm.md index 199e2391a21bf..c4cb6817387c6 100644 --- a/includes/migration-guide/runtime/core/persian-calendar-now-uses-hijri-solar-algorithm.md +++ b/includes/migration-guide/runtime/core/persian-calendar-now-uses-hijri-solar-algorithm.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.6| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0134
| diff --git a/includes/migration-guide/runtime/core/some-net-apis-cause-first-chance-handled-entrypointnotfoundexceptions.md b/includes/migration-guide/runtime/core/some-net-apis-cause-first-chance-handled-entrypointnotfoundexceptions.md index b905a4368aac2..1d88ee0f39e73 100644 --- a/includes/migration-guide/runtime/core/some-net-apis-cause-first-chance-handled-entrypointnotfoundexceptions.md +++ b/includes/migration-guide/runtime/core/some-net-apis-cause-first-chance-handled-entrypointnotfoundexceptions.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0085
| diff --git a/includes/migration-guide/runtime/core/systemuri-escaping-now-supports-rfc-3986.md b/includes/migration-guide/runtime/core/systemuri-escaping-now-supports-rfc-3986.md index 779e6dde26c62..d5ae1d36a6c89 100644 --- a/includes/migration-guide/runtime/core/systemuri-escaping-now-supports-rfc-3986.md +++ b/includes/migration-guide/runtime/core/systemuri-escaping-now-supports-rfc-3986.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0010A
  • CD0010B
  • CD0010C
| diff --git a/includes/migration-guide/runtime/core/targetframeworkname-for-default-app-domain-no-longer-defaults-null-if-not.md b/includes/migration-guide/runtime/core/targetframeworkname-for-default-app-domain-no-longer-defaults-null-if-not.md index a787d8b3c0602..5c2918763f21b 100644 --- a/includes/migration-guide/runtime/core/targetframeworkname-for-default-app-domain-no-longer-defaults-null-if-not.md +++ b/includes/migration-guide/runtime/core/targetframeworkname-for-default-app-domain-no-longer-defaults-null-if-not.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.6| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0075B
  • CD0075A
| diff --git a/includes/migration-guide/runtime/core/typeisassignablefrom-returns-wrong-result-for-generic-variables-with.md b/includes/migration-guide/runtime/core/typeisassignablefrom-returns-wrong-result-for-generic-variables-with.md index 60038eff93892..a05ddde0988a6 100644 --- a/includes/migration-guide/runtime/core/typeisassignablefrom-returns-wrong-result-for-generic-variables-with.md +++ b/includes/migration-guide/runtime/core/typeisassignablefrom-returns-wrong-result-for-generic-variables-with.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0089
  • CD0089
| diff --git a/includes/migration-guide/runtime/core/x509certificate2tostringbool-does-not-throw-now-when-net-cannot-handle.md b/includes/migration-guide/runtime/core/x509certificate2tostringbool-does-not-throw-now-when-net-cannot-handle.md index 5d4ad3cbbd3d3..56065c836fded 100644 --- a/includes/migration-guide/runtime/core/x509certificate2tostringbool-does-not-throw-now-when-net-cannot-handle.md +++ b/includes/migration-guide/runtime/core/x509certificate2tostringbool-does-not-throw-now-when-net-cannot-handle.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.6| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0076
| diff --git a/includes/migration-guide/runtime/data/connection-pool-blocking-period-for-azure-sql-databases-removed.md b/includes/migration-guide/runtime/data/connection-pool-blocking-period-for-azure-sql-databases-removed.md index 40a21fed874eb..7cbd6c0caeba9 100644 --- a/includes/migration-guide/runtime/data/connection-pool-blocking-period-for-azure-sql-databases-removed.md +++ b/includes/migration-guide/runtime/data/connection-pool-blocking-period-for-azure-sql-databases-removed.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6.2| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/data/non-pooled-sql-connections-will-leak-memory-if-not-explicitly-disposed.md b/includes/migration-guide/runtime/data/non-pooled-sql-connections-will-leak-memory-if-not-explicitly-disposed.md index 1f2f013feaba3..4f89cd1cfd52a 100644 --- a/includes/migration-guide/runtime/data/non-pooled-sql-connections-will-leak-memory-if-not-explicitly-disposed.md +++ b/includes/migration-guide/runtime/data/non-pooled-sql-connections-will-leak-memory-if-not-explicitly-disposed.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/data/sqlbulkcopy-uses-destination-column-encoding-for-strings.md b/includes/migration-guide/runtime/data/sqlbulkcopy-uses-destination-column-encoding-for-strings.md index b5293807cfc42..aa8fb06fbbbbc 100644 --- a/includes/migration-guide/runtime/data/sqlbulkcopy-uses-destination-column-encoding-for-strings.md +++ b/includes/migration-guide/runtime/data/sqlbulkcopy-uses-destination-column-encoding-for-strings.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/data/sqlconnection-can-no-longer-connect-sql-server-1997-databases-using-via.md b/includes/migration-guide/runtime/data/sqlconnection-can-no-longer-connect-sql-server-1997-databases-using-via.md index 3c03f005f0b37..824d82217d828 100644 --- a/includes/migration-guide/runtime/data/sqlconnection-can-no-longer-connect-sql-server-1997-databases-using-via.md +++ b/includes/migration-guide/runtime/data/sqlconnection-can-no-longer-connect-sql-server-1997-databases-using-via.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/data/sqlconnectionopen-fails-on-windows-7-with-non-ifs-winsock-bsp-lsp-present.md b/includes/migration-guide/runtime/data/sqlconnectionopen-fails-on-windows-7-with-non-ifs-winsock-bsp-lsp-present.md index c1e2931d39641..e18b3c50b0233 100644 --- a/includes/migration-guide/runtime/data/sqlconnectionopen-fails-on-windows-7-with-non-ifs-winsock-bsp-lsp-present.md +++ b/includes/migration-guide/runtime/data/sqlconnectionopen-fails-on-windows-7-with-non-ifs-winsock-bsp-lsp-present.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0083
| diff --git a/includes/migration-guide/runtime/ef/different-exception-handling-for-objectcontextcreatedatabase.md b/includes/migration-guide/runtime/ef/different-exception-handling-for-objectcontextcreatedatabase.md index c9e84dbfd1446..db4ccc5e9e3bc 100644 --- a/includes/migration-guide/runtime/ef/different-exception-handling-for-objectcontextcreatedatabase.md +++ b/includes/migration-guide/runtime/ef/different-exception-handling-for-objectcontextcreatedatabase.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0040
| diff --git a/includes/migration-guide/runtime/ef/log-file-name-created-by-objectcontextcreatedatabase-method-has-changed.md b/includes/migration-guide/runtime/ef/log-file-name-created-by-objectcontextcreatedatabase-method-has-changed.md index 78af5d891803c..9f87e40bcf479 100644 --- a/includes/migration-guide/runtime/ef/log-file-name-created-by-objectcontextcreatedatabase-method-has-changed.md +++ b/includes/migration-guide/runtime/ef/log-file-name-created-by-objectcontextcreatedatabase-method-has-changed.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0059
| diff --git a/includes/migration-guide/runtime/ef/objectcontexttranslate-objectcontextexecutestorequery-now-support-enum-type.md b/includes/migration-guide/runtime/ef/objectcontexttranslate-objectcontextexecutestorequery-now-support-enum-type.md index edba7f981d19f..ba846830a5fc5 100644 --- a/includes/migration-guide/runtime/ef/objectcontexttranslate-objectcontextexecutestorequery-now-support-enum-type.md +++ b/includes/migration-guide/runtime/ef/objectcontexttranslate-objectcontextexecutestorequery-now-support-enum-type.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0041
| diff --git a/includes/migration-guide/runtime/globalization/unicode-standard-version-80-categories-now-supported.md b/includes/migration-guide/runtime/globalization/unicode-standard-version-80-categories-now-supported.md index 4821b1d05997c..7a21bb17cc4af 100644 --- a/includes/migration-guide/runtime/globalization/unicode-standard-version-80-categories-now-supported.md +++ b/includes/migration-guide/runtime/globalization/unicode-standard-version-80-categories-now-supported.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6.2| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/linq/enumerableemptylttresultgt-always-returns-cached-instance.md b/includes/migration-guide/runtime/linq/enumerableemptylttresultgt-always-returns-cached-instance.md index c3b4c0640c90f..08d2abe6a9b40 100644 --- a/includes/migration-guide/runtime/linq/enumerableemptylttresultgt-always-returns-cached-instance.md +++ b/includes/migration-guide/runtime/linq/enumerableemptylttresultgt-always-returns-cached-instance.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0042
| diff --git a/includes/migration-guide/runtime/linq/linq-ef-join-throws-argumentoutofrangeexception.md b/includes/migration-guide/runtime/linq/linq-ef-join-throws-argumentoutofrangeexception.md index 38129b0bc5dd8..794c100fd4ff8 100644 --- a/includes/migration-guide/runtime/linq/linq-ef-join-throws-argumentoutofrangeexception.md +++ b/includes/migration-guide/runtime/linq/linq-ef-join-throws-argumentoutofrangeexception.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/networking/contentdisposition-datetimes-returns-slightly-different-string.md b/includes/migration-guide/runtime/networking/contentdisposition-datetimes-returns-slightly-different-string.md index d16bc489c37bd..51d138c81916d 100644 --- a/includes/migration-guide/runtime/networking/contentdisposition-datetimes-returns-slightly-different-string.md +++ b/includes/migration-guide/runtime/networking/contentdisposition-datetimes-returns-slightly-different-string.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.6| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0078
| diff --git a/includes/migration-guide/runtime/networking/systemnetpeertopeercollaboration-unavailable-on-windows-8.md b/includes/migration-guide/runtime/networking/systemnetpeertopeercollaboration-unavailable-on-windows-8.md index 1f6ec7d263b9b..24a35add1fbe8 100644 --- a/includes/migration-guide/runtime/networking/systemnetpeertopeercollaboration-unavailable-on-windows-8.md +++ b/includes/migration-guide/runtime/networking/systemnetpeertopeercollaboration-unavailable-on-windows-8.md @@ -7,6 +7,6 @@ |Scope|Major| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0011
| diff --git a/includes/migration-guide/runtime/security/rsacngverifyhash-now-returns-false-for-any-verification-failure.md b/includes/migration-guide/runtime/security/rsacngverifyhash-now-returns-false-for-any-verification-failure.md index 7087da2e7bb17..1c861a7be73cf 100644 --- a/includes/migration-guide/runtime/security/rsacngverifyhash-now-returns-false-for-any-verification-failure.md +++ b/includes/migration-guide/runtime/security/rsacngverifyhash-now-returns-false-for-any-verification-failure.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6.2| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/security/signedxml-encryptedxml-breaking-changes.md b/includes/migration-guide/runtime/security/signedxml-encryptedxml-breaking-changes.md index 70367ac94b644..2147be7639519 100644 --- a/includes/migration-guide/runtime/security/signedxml-encryptedxml-breaking-changes.md +++ b/includes/migration-guide/runtime/security/signedxml-encryptedxml-breaking-changes.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6.2| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/serialization/binaryformatter-can-fail-find-type-from-loadfrom-context.md b/includes/migration-guide/runtime/serialization/binaryformatter-can-fail-find-type-from-loadfrom-context.md index 5f75c86a0c9d1..96389af5ec222 100644 --- a/includes/migration-guide/runtime/serialization/binaryformatter-can-fail-find-type-from-loadfrom-context.md +++ b/includes/migration-guide/runtime/serialization/binaryformatter-can-fail-find-type-from-loadfrom-context.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/serialization/exception-message-has-changed-for-failed-datacontract-serialization-case-an.md b/includes/migration-guide/runtime/serialization/exception-message-has-changed-for-failed-datacontract-serialization-case-an.md index 38eee4d6f0d21..4929653f872f5 100644 --- a/includes/migration-guide/runtime/serialization/exception-message-has-changed-for-failed-datacontract-serialization-case-an.md +++ b/includes/migration-guide/runtime/serialization/exception-message-has-changed-for-failed-datacontract-serialization-case-an.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/serialization/netdatacontractserializer-fails-deserialize-concurrentdictionary-serialized.md b/includes/migration-guide/runtime/serialization/netdatacontractserializer-fails-deserialize-concurrentdictionary-serialized.md index f428bc969ce5e..66fbc42eb00b1 100644 --- a/includes/migration-guide/runtime/serialization/netdatacontractserializer-fails-deserialize-concurrentdictionary-serialized.md +++ b/includes/migration-guide/runtime/serialization/netdatacontractserializer-fails-deserialize-concurrentdictionary-serialized.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5.1| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/serialization/soapformatter-cannot-deserialize-hashtable-similar-ordered-collection.md b/includes/migration-guide/runtime/serialization/soapformatter-cannot-deserialize-hashtable-similar-ordered-collection.md index 3e08c5546f83c..e51f71533342b 100644 --- a/includes/migration-guide/runtime/serialization/soapformatter-cannot-deserialize-hashtable-similar-ordered-collection.md +++ b/includes/migration-guide/runtime/serialization/soapformatter-cannot-deserialize-hashtable-similar-ordered-collection.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0001B
  • CD0001A
| diff --git a/includes/migration-guide/runtime/serialization/xmlserializer-fails-while-serializing-type-that-hides-an-accessible-member.md b/includes/migration-guide/runtime/serialization/xmlserializer-fails-while-serializing-type-that-hides-an-accessible-member.md index 1acb40a8097f2..d16ad44185f53 100644 --- a/includes/migration-guide/runtime/serialization/xmlserializer-fails-while-serializing-type-that-hides-an-accessible-member.md +++ b/includes/migration-guide/runtime/serialization/xmlserializer-fails-while-serializing-type-that-hides-an-accessible-member.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wcf/remove-ssl3-from-wcf-transportdefaults.md b/includes/migration-guide/runtime/wcf/remove-ssl3-from-wcf-transportdefaults.md index f01e2f3757f30..fc3a209db3e0f 100644 --- a/includes/migration-guide/runtime/wcf/remove-ssl3-from-wcf-transportdefaults.md +++ b/includes/migration-guide/runtime/wcf/remove-ssl3-from-wcf-transportdefaults.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6.2| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wcf/replace-method-odata-urls-disabled-by-default.md b/includes/migration-guide/runtime/wcf/replace-method-odata-urls-disabled-by-default.md index fa3af4ab23836..fd59bf4f930b0 100644 --- a/includes/migration-guide/runtime/wcf/replace-method-odata-urls-disabled-by-default.md +++ b/includes/migration-guide/runtime/wcf/replace-method-odata-urls-disabled-by-default.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0029
| diff --git a/includes/migration-guide/runtime/wcf/systemservicemodelwebwebservicehost-object-no-longer-adds-default-endpoint.md b/includes/migration-guide/runtime/wcf/systemservicemodelwebwebservicehost-object-no-longer-adds-default-endpoint.md index 0fb774b5d7a40..153d80ad37ac5 100644 --- a/includes/migration-guide/runtime/wcf/systemservicemodelwebwebservicehost-object-no-longer-adds-default-endpoint.md +++ b/includes/migration-guide/runtime/wcf/systemservicemodelwebwebservicehost-object-no-longer-adds-default-endpoint.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0030A
  • CD0030B
| diff --git a/includes/migration-guide/runtime/wcf/wcf-binding-with-transportwithmessagecredential-security-mode.md b/includes/migration-guide/runtime/wcf/wcf-binding-with-transportwithmessagecredential-security-mode.md index f2a3398708dbd..336577e45bf55 100644 --- a/includes/migration-guide/runtime/wcf/wcf-binding-with-transportwithmessagecredential-security-mode.md +++ b/includes/migration-guide/runtime/wcf/wcf-binding-with-transportwithmessagecredential-security-mode.md @@ -7,5 +7,5 @@ |Scope|Transparent| |Version|4.6.1| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wf/unexpected-invalidcastexception-from-invokemethod-activity-wf4.md b/includes/migration-guide/runtime/wf/unexpected-invalidcastexception-from-invokemethod-activity-wf4.md index 641f6035ced5d..b0cbabcbac358 100644 --- a/includes/migration-guide/runtime/wf/unexpected-invalidcastexception-from-invokemethod-activity-wf4.md +++ b/includes/migration-guide/runtime/wf/unexpected-invalidcastexception-from-invokemethod-activity-wf4.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wf/workflow-now-throws-original-exception-instead-nullreferenceexception-some.md b/includes/migration-guide/runtime/wf/workflow-now-throws-original-exception-instead-nullreferenceexception-some.md index 7c1da9116ae84..e2344712884c6 100644 --- a/includes/migration-guide/runtime/wf/workflow-now-throws-original-exception-instead-nullreferenceexception-some.md +++ b/includes/migration-guide/runtime/wf/workflow-now-throws-original-exception-instead-nullreferenceexception-some.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.7| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/winforms/multiple-items-single-tablelayoutpanel-cell-may-be-rearranged.md b/includes/migration-guide/runtime/winforms/multiple-items-single-tablelayoutpanel-cell-may-be-rearranged.md index d62514b4f5482..a52ee23c98833 100644 --- a/includes/migration-guide/runtime/winforms/multiple-items-single-tablelayoutpanel-cell-may-be-rearranged.md +++ b/includes/migration-guide/runtime/winforms/multiple-items-single-tablelayoutpanel-cell-may-be-rearranged.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0098
| diff --git a/includes/migration-guide/runtime/winforms/previewlostkeyboardfocus-called-repeatedly-if-its-handler-shows-windows.md b/includes/migration-guide/runtime/winforms/previewlostkeyboardfocus-called-repeatedly-if-its-handler-shows-windows.md index 4afcadcbd0488..440071f3ec395 100644 --- a/includes/migration-guide/runtime/winforms/previewlostkeyboardfocus-called-repeatedly-if-its-handler-shows-windows.md +++ b/includes/migration-guide/runtime/winforms/previewlostkeyboardfocus-called-repeatedly-if-its-handler-shows-windows.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0131
| diff --git a/includes/migration-guide/runtime/wpf/accessing-wpf-datagrids-selected-items-from-handler-unloadingrow-event-can.md b/includes/migration-guide/runtime/wpf/accessing-wpf-datagrids-selected-items-from-handler-unloadingrow-event-can.md index e0ca02acd4b58..5833d9fe17a77 100644 --- a/includes/migration-guide/runtime/wpf/accessing-wpf-datagrids-selected-items-from-handler-unloadingrow-event-can.md +++ b/includes/migration-guide/runtime/wpf/accessing-wpf-datagrids-selected-items-from-handler-unloadingrow-event-can.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/calling-datagridcommitedit-from-celleditending-handler-drops-focus.md b/includes/migration-guide/runtime/wpf/calling-datagridcommitedit-from-celleditending-handler-drops-focus.md index 279f1e1397e14..cd3dc6155239c 100644 --- a/includes/migration-guide/runtime/wpf/calling-datagridcommitedit-from-celleditending-handler-drops-focus.md +++ b/includes/migration-guide/runtime/wpf/calling-datagridcommitedit-from-celleditending-handler-drops-focus.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0124
| diff --git a/includes/migration-guide/runtime/wpf/calling-itemsrefresh-on-wpf-listbox-listview-datagrid-with-items-selected.md b/includes/migration-guide/runtime/wpf/calling-itemsrefresh-on-wpf-listbox-listview-datagrid-with-items-selected.md index b02160de2761c..a1c38a3200b8b 100644 --- a/includes/migration-guide/runtime/wpf/calling-itemsrefresh-on-wpf-listbox-listview-datagrid-with-items-selected.md +++ b/includes/migration-guide/runtime/wpf/calling-itemsrefresh-on-wpf-listbox-listview-datagrid-with-items-selected.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0104
| diff --git a/includes/migration-guide/runtime/wpf/changing-isenabled-property-parent-textblock-control-affects-any-child.md b/includes/migration-guide/runtime/wpf/changing-isenabled-property-parent-textblock-control-affects-any-child.md index acf66ac737f05..d473abf78ad18 100644 --- a/includes/migration-guide/runtime/wpf/changing-isenabled-property-parent-textblock-control-affects-any-child.md +++ b/includes/migration-guide/runtime/wpf/changing-isenabled-property-parent-textblock-control-affects-any-child.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6.2| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/coerceisselectionboxhighlighted.md b/includes/migration-guide/runtime/wpf/coerceisselectionboxhighlighted.md index 535a9426d3035..ff1be9457fd08 100644 --- a/includes/migration-guide/runtime/wpf/coerceisselectionboxhighlighted.md +++ b/includes/migration-guide/runtime/wpf/coerceisselectionboxhighlighted.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/datagridcellspanelbringindexintoview-throws-argumentoutofrangeexception.md b/includes/migration-guide/runtime/wpf/datagridcellspanelbringindexintoview-throws-argumentoutofrangeexception.md index ed31482a53765..da98118ade57f 100644 --- a/includes/migration-guide/runtime/wpf/datagridcellspanelbringindexintoview-throws-argumentoutofrangeexception.md +++ b/includes/migration-guide/runtime/wpf/datagridcellspanelbringindexintoview-throws-argumentoutofrangeexception.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.6.2| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/flowdocument-may-show-an-extra-line-text.md b/includes/migration-guide/runtime/wpf/flowdocument-may-show-an-extra-line-text.md index c69cc43ed1fda..c56cc7e3e25f5 100644 --- a/includes/migration-guide/runtime/wpf/flowdocument-may-show-an-extra-line-text.md +++ b/includes/migration-guide/runtime/wpf/flowdocument-may-show-an-extra-line-text.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/glyphruncomputeinkboundingbox-formattedtextextent-return-different-values.md b/includes/migration-guide/runtime/wpf/glyphruncomputeinkboundingbox-formattedtextextent-return-different-values.md index 395e8e2871fc8..8923c87de3192 100644 --- a/includes/migration-guide/runtime/wpf/glyphruncomputeinkboundingbox-formattedtextextent-return-different-values.md +++ b/includes/migration-guide/runtime/wpf/glyphruncomputeinkboundingbox-formattedtextextent-return-different-values.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0114
| diff --git a/includes/migration-guide/runtime/wpf/horizontal-scrolling-virtualization.md b/includes/migration-guide/runtime/wpf/horizontal-scrolling-virtualization.md index 266d568561feb..9ca6a4d050c9a 100644 --- a/includes/migration-guide/runtime/wpf/horizontal-scrolling-virtualization.md +++ b/includes/migration-guide/runtime/wpf/horizontal-scrolling-virtualization.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6.2| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/icommandcanexecutechanged-event-behaviour-changed-net-45.md b/includes/migration-guide/runtime/wpf/icommandcanexecutechanged-event-behaviour-changed-net-45.md index 56e9dfa802fa1..d47b76c243e79 100644 --- a/includes/migration-guide/runtime/wpf/icommandcanexecutechanged-event-behaviour-changed-net-45.md +++ b/includes/migration-guide/runtime/wpf/icommandcanexecutechanged-event-behaviour-changed-net-45.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0084
| diff --git a/includes/migration-guide/runtime/wpf/item-scrolling-flat-list-with-items-different-pixel-height.md b/includes/migration-guide/runtime/wpf/item-scrolling-flat-list-with-items-different-pixel-height.md index 4b8a75e5262ea..98f38bd451c28 100644 --- a/includes/migration-guide/runtime/wpf/item-scrolling-flat-list-with-items-different-pixel-height.md +++ b/includes/migration-guide/runtime/wpf/item-scrolling-flat-list-with-items-different-pixel-height.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.6.1| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/itemsclear-does-not-remove-duplicates-from-selecteditems.md b/includes/migration-guide/runtime/wpf/itemsclear-does-not-remove-duplicates-from-selecteditems.md index e3b7d0e6605b5..78ee829ed5bbf 100644 --- a/includes/migration-guide/runtime/wpf/itemsclear-does-not-remove-duplicates-from-selecteditems.md +++ b/includes/migration-guide/runtime/wpf/itemsclear-does-not-remove-duplicates-from-selecteditems.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/listboxitem-isselected-binding-issue-with-observablecollectionlttgtmove.md b/includes/migration-guide/runtime/wpf/listboxitem-isselected-binding-issue-with-observablecollectionlttgtmove.md index 2d554912e21c3..c30fa92721ef0 100644 --- a/includes/migration-guide/runtime/wpf/listboxitem-isselected-binding-issue-with-observablecollectionlttgtmove.md +++ b/includes/migration-guide/runtime/wpf/listboxitem-isselected-binding-issue-with-observablecollectionlttgtmove.md @@ -7,5 +7,5 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/new-enum-values-wpfs-pagerangeselection.md b/includes/migration-guide/runtime/wpf/new-enum-values-wpfs-pagerangeselection.md index 6cf9eefb7b14d..fe1b78b41b57a 100644 --- a/includes/migration-guide/runtime/wpf/new-enum-values-wpfs-pagerangeselection.md +++ b/includes/migration-guide/runtime/wpf/new-enum-values-wpfs-pagerangeselection.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0037
| diff --git a/includes/migration-guide/runtime/wpf/right-clicking-on-wpf-datagrid-row-header-changes-selection.md b/includes/migration-guide/runtime/wpf/right-clicking-on-wpf-datagrid-row-header-changes-selection.md index 7c940d6905121..e05e4437e92e7 100644 --- a/includes/migration-guide/runtime/wpf/right-clicking-on-wpf-datagrid-row-header-changes-selection.md +++ b/includes/migration-guide/runtime/wpf/right-clicking-on-wpf-datagrid-row-header-changes-selection.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/wpf-aero2-aerolite-themes-toggle-button-doesnt-show-any-state.md b/includes/migration-guide/runtime/wpf/wpf-aero2-aerolite-themes-toggle-button-doesnt-show-any-state.md index 26f112b8d1826..ee5642f7473fa 100644 --- a/includes/migration-guide/runtime/wpf/wpf-aero2-aerolite-themes-toggle-button-doesnt-show-any-state.md +++ b/includes/migration-guide/runtime/wpf/wpf-aero2-aerolite-themes-toggle-button-doesnt-show-any-state.md @@ -7,5 +7,5 @@ |Scope|Major| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/wpf/wpf-datatemplate-elements-are-now-visible-uia.md b/includes/migration-guide/runtime/wpf/wpf-datatemplate-elements-are-now-visible-uia.md index 2df2702f964d9..f00aba828151f 100644 --- a/includes/migration-guide/runtime/wpf/wpf-datatemplate-elements-are-now-visible-uia.md +++ b/includes/migration-guide/runtime/wpf/wpf-datatemplate-elements-are-now-visible-uia.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0003
| diff --git a/includes/migration-guide/runtime/wpf/wpf-dispatchersynchronizationcontextcreatecopy-now-returns-new-copy-instead.md b/includes/migration-guide/runtime/wpf/wpf-dispatchersynchronizationcontextcreatecopy-now-returns-new-copy-instead.md index 35e4e55db04de..b9a01a8e25b35 100644 --- a/includes/migration-guide/runtime/wpf/wpf-dispatchersynchronizationcontextcreatecopy-now-returns-new-copy-instead.md +++ b/includes/migration-guide/runtime/wpf/wpf-dispatchersynchronizationcontextcreatecopy-now-returns-new-copy-instead.md @@ -7,6 +7,6 @@ |Scope|Minor| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0038
| diff --git a/includes/migration-guide/runtime/wpf/wpf-textbox-defaults-undo-limit-100.md b/includes/migration-guide/runtime/wpf/wpf-textbox-defaults-undo-limit-100.md index d5b77c49a46b9..9c3079500ca3b 100644 --- a/includes/migration-guide/runtime/wpf/wpf-textbox-defaults-undo-limit-100.md +++ b/includes/migration-guide/runtime/wpf/wpf-textbox-defaults-undo-limit-100.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0051
| diff --git a/includes/migration-guide/runtime/wpf/wpf-textbox-selected-text-appears-different-color-when-box-inactive.md b/includes/migration-guide/runtime/wpf/wpf-textbox-selected-text-appears-different-color-when-box-inactive.md index 758233df8eee9..03a828e3415fa 100644 --- a/includes/migration-guide/runtime/wpf/wpf-textbox-selected-text-appears-different-color-when-box-inactive.md +++ b/includes/migration-guide/runtime/wpf/wpf-textbox-selected-text-appears-different-color-when-box-inactive.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0004
| diff --git a/includes/migration-guide/runtime/xml/xmlschemaexception-now-sets-line-positions-properly.md b/includes/migration-guide/runtime/xml/xmlschemaexception-now-sets-line-positions-properly.md index 5f59aea9f4c3a..9a627bec2d61d 100644 --- a/includes/migration-guide/runtime/xml/xmlschemaexception-now-sets-line-positions-properly.md +++ b/includes/migration-guide/runtime/xml/xmlschemaexception-now-sets-line-positions-properly.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0019
| diff --git a/includes/migration-guide/runtime/xml/xmlserializer-serializes-fields-differently-net-framework-45.md b/includes/migration-guide/runtime/xml/xmlserializer-serializes-fields-differently-net-framework-45.md index 9e68740ea4552..847df6bd33e26 100644 --- a/includes/migration-guide/runtime/xml/xmlserializer-serializes-fields-differently-net-framework-45.md +++ b/includes/migration-guide/runtime/xml/xmlserializer-serializes-fields-differently-net-framework-45.md @@ -7,5 +7,5 @@ |Scope|Major| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/xml/xmltextreader-dtd-entity-expansion-limited-10000000-characters.md b/includes/migration-guide/runtime/xml/xmltextreader-dtd-entity-expansion-limited-10000000-characters.md index 9e6090c82f99e..bb3dcf4a85f2a 100644 --- a/includes/migration-guide/runtime/xml/xmltextreader-dtd-entity-expansion-limited-10000000-characters.md +++ b/includes/migration-guide/runtime/xml/xmltextreader-dtd-entity-expansion-limited-10000000-characters.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0033
| diff --git a/includes/migration-guide/runtime/xml/xslt-forward-compat-now-works.md b/includes/migration-guide/runtime/xml/xslt-forward-compat-now-works.md index d93e1af0376c2..dc72e50dcb89b 100644 --- a/includes/migration-guide/runtime/xml/xslt-forward-compat-now-works.md +++ b/includes/migration-guide/runtime/xml/xslt-forward-compat-now-works.md @@ -7,5 +7,5 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| diff --git a/includes/migration-guide/runtime/xml/xslt-style-sheet-exception-message-changed.md b/includes/migration-guide/runtime/xml/xslt-style-sheet-exception-message-changed.md index e3b56ecd2c0ba..6bd3b78e26da2 100644 --- a/includes/migration-guide/runtime/xml/xslt-style-sheet-exception-message-changed.md +++ b/includes/migration-guide/runtime/xml/xslt-style-sheet-exception-message-changed.md @@ -7,6 +7,6 @@ |Scope|Edge| |Version|4.5| |Type|Runtime| -|Affected APIs|
| +|Affected APIs|
| |Analyzers|
  • CD0035
| diff --git a/styleguide/template.md b/styleguide/template.md index 66f97f1071277..5f95ecb1dd38d 100644 --- a/styleguide/template.md +++ b/styleguide/template.md @@ -132,7 +132,7 @@ The UID equates to the fully qualified class and member name. If you add a \* af You can use one of the following syntax: -1. Auto-link: `` or `` +1. Auto-link: `` or `` The `displayProperty` query parameter produces a fully qualified link text. By default, link text shows only the member or type name. @@ -142,7 +142,7 @@ You can use one of the following syntax: Examples: - `` renders as [String](https://docs.microsoft.com/dotnet/api/system.string) -- `` renders as [System.String](https://docs.microsoft.com/dotnet/api/system.string) +- `` renders as [System.String](https://docs.microsoft.com/dotnet/api/system.string) - `[String class](xref:System.String)` renders as [String class](https://docs.microsoft.com/dotnet/api/system.string) For more information about using this notation, see [Using cross reference](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html#using-cross-reference). diff --git a/xml/Microsoft.JScript.Vsa/JSVsaError.xml b/xml/Microsoft.JScript.Vsa/JSVsaError.xml index 085811c9c6ccf..51f7a2655526f 100644 --- a/xml/Microsoft.JScript.Vsa/JSVsaError.xml +++ b/xml/Microsoft.JScript.Vsa/JSVsaError.xml @@ -1870,7 +1870,7 @@ ## Remarks Exception string: The specified element could not be saved. - Thrown by the method and methods when a call to the `SaveElement` method fails. The `InnerException` property of the class is set to the actual exception thrown by the underlying code (for example, an out of disk space exception). For more information, see . The `SaveSourceState` method returns the `SaveElementFailed` exception from the `SaveElement` method back to the caller. + Thrown by the method and methods when a call to the `SaveElement` method fails. The `InnerException` property of the class is set to the actual exception thrown by the underlying code (for example, an out of disk space exception). For more information, see . The `SaveSourceState` method returns the `SaveElementFailed` exception from the `SaveElement` method back to the caller. ]]> diff --git a/xml/Microsoft.VisualBasic.ApplicationServices/ApplicationBase.xml b/xml/Microsoft.VisualBasic.ApplicationServices/ApplicationBase.xml index 84585647a722c..20dde17531390 100644 --- a/xml/Microsoft.VisualBasic.ApplicationServices/ApplicationBase.xml +++ b/xml/Microsoft.VisualBasic.ApplicationServices/ApplicationBase.xml @@ -246,7 +246,7 @@ , except that this method raises an exception if the environment variable specified by `name` does not exist. + The `My.Application.GetEnvironmentVariable` method returns the environment variable with the name `name`. This method is similar to , except that this method raises an exception if the environment variable specified by `name` does not exist. ## Availability by Project Type diff --git a/xml/Microsoft.VisualBasic.ApplicationServices/ShutdownEventHandler.xml b/xml/Microsoft.VisualBasic.ApplicationServices/ShutdownEventHandler.xml index 586fca46128e5..7d58c2d689d15 100644 --- a/xml/Microsoft.VisualBasic.ApplicationServices/ShutdownEventHandler.xml +++ b/xml/Microsoft.VisualBasic.ApplicationServices/ShutdownEventHandler.xml @@ -34,7 +34,7 @@ ## Examples - + [Overview of the Visual Basic Application Model](~/docs/visual-basic/developing-apps/development-with-my/overview-of-the-visual-basic-application-model.md) diff --git a/xml/Microsoft.VisualBasic.ApplicationServices/StartupEventHandler.xml b/xml/Microsoft.VisualBasic.ApplicationServices/StartupEventHandler.xml index 51cb451600419..a097de6774859 100644 --- a/xml/Microsoft.VisualBasic.ApplicationServices/StartupEventHandler.xml +++ b/xml/Microsoft.VisualBasic.ApplicationServices/StartupEventHandler.xml @@ -34,7 +34,7 @@ ## Examples - + [Overview of the Visual Basic Application Model](~/docs/visual-basic/developing-apps/development-with-my/overview-of-the-visual-basic-application-model.md) diff --git a/xml/Microsoft.VisualBasic.ApplicationServices/StartupNextInstanceEventHandler.xml b/xml/Microsoft.VisualBasic.ApplicationServices/StartupNextInstanceEventHandler.xml index 87bb2682eb848..299f069c6c32e 100644 --- a/xml/Microsoft.VisualBasic.ApplicationServices/StartupNextInstanceEventHandler.xml +++ b/xml/Microsoft.VisualBasic.ApplicationServices/StartupNextInstanceEventHandler.xml @@ -34,7 +34,7 @@ ## Examples - + [Overview of the Visual Basic Application Model](~/docs/visual-basic/developing-apps/development-with-my/overview-of-the-visual-basic-application-model.md) diff --git a/xml/Microsoft.VisualBasic.ApplicationServices/UnhandledExceptionEventHandler.xml b/xml/Microsoft.VisualBasic.ApplicationServices/UnhandledExceptionEventHandler.xml index 5cce4bc600662..d9594e1675c38 100644 --- a/xml/Microsoft.VisualBasic.ApplicationServices/UnhandledExceptionEventHandler.xml +++ b/xml/Microsoft.VisualBasic.ApplicationServices/UnhandledExceptionEventHandler.xml @@ -34,7 +34,7 @@ ## Examples - + [Overview of the Visual Basic Application Model](~/docs/visual-basic/developing-apps/development-with-my/overview-of-the-visual-basic-application-model.md) diff --git a/xml/Microsoft.VisualBasic.ApplicationServices/User.xml b/xml/Microsoft.VisualBasic.ApplicationServices/User.xml index 85f6546b342e8..377d94d51dff6 100644 --- a/xml/Microsoft.VisualBasic.ApplicationServices/User.xml +++ b/xml/Microsoft.VisualBasic.ApplicationServices/User.xml @@ -140,7 +140,7 @@ . + You can use the `My.User.InitializeWithWindowsUser` method to set the thread's current principal to the Windows user that started the application. The Visual Basic Application Model in a Windows application calls this method at startup by default. In other project types, you must set the thread's current principal by calling this method explicitly or by assigning a value to . In Windows projects, the `My.User` object is based on the thread's current principal; therefore, this method can change the information `My.User` returns. In an ASP.NET application, the `My.User` object is based on the current HTTP request's user identity, and is unaffected by this method. @@ -185,7 +185,7 @@ object, this property wraps the property. Override this method in a derived class to provide different behavior. For example, the property overrides this property. + In the object, this property wraps the property. Override this method in a derived class to provide different behavior. For example, the property overrides this property. ]]> diff --git a/xml/Microsoft.VisualBasic.ApplicationServices/WebUser.xml b/xml/Microsoft.VisualBasic.ApplicationServices/WebUser.xml index ba79b2709909a..27a785da87b9d 100644 --- a/xml/Microsoft.VisualBasic.ApplicationServices/WebUser.xml +++ b/xml/Microsoft.VisualBasic.ApplicationServices/WebUser.xml @@ -80,7 +80,7 @@ object, this property wraps the property of the property. + In the object, this property wraps the property of the property. For more detailed information, see the property. diff --git a/xml/Microsoft.VisualBasic.ApplicationServices/WindowsFormsApplicationBase.xml b/xml/Microsoft.VisualBasic.ApplicationServices/WindowsFormsApplicationBase.xml index df0469f73ac06..97405601b08c9 100644 --- a/xml/Microsoft.VisualBasic.ApplicationServices/WindowsFormsApplicationBase.xml +++ b/xml/Microsoft.VisualBasic.ApplicationServices/WindowsFormsApplicationBase.xml @@ -745,7 +745,7 @@ property. + The `My.Application.OpenForms` property gets a collection of all the application's open forms. The behavior is identical to the property. > [!NOTE] > The `My.Application.OpenForms` property returns all open forms, regardless of which thread opened them. You should check the property of each form before accessing it; otherwise, it might throw an exception. diff --git a/xml/Microsoft.VisualBasic.Devices/Clock.xml b/xml/Microsoft.VisualBasic.Devices/Clock.xml index faf610f2f6d97..0c463de486e27 100644 --- a/xml/Microsoft.VisualBasic.Devices/Clock.xml +++ b/xml/Microsoft.VisualBasic.Devices/Clock.xml @@ -63,7 +63,7 @@ property. + The `My.Computer.Clock.GmtTime` property has the same behavior as the property. ## Availability by Project Type @@ -107,7 +107,7 @@ property. + The `My.Computer.Clock.LocalTime` property has the same behavior as the property. ## Availability by Project Type @@ -164,7 +164,7 @@ Use the property or property to obtain the current local date and time on this computer. - The `My.Computer.Clock.TickCount` property has the same behavior as the property. + The `My.Computer.Clock.TickCount` property has the same behavior as the property. ## Availability by Project Type diff --git a/xml/Microsoft.VisualBasic.Devices/NetworkAvailableEventArgs.xml b/xml/Microsoft.VisualBasic.Devices/NetworkAvailableEventArgs.xml index 4d9965561b8ca..6e1a9cf996167 100644 --- a/xml/Microsoft.VisualBasic.Devices/NetworkAvailableEventArgs.xml +++ b/xml/Microsoft.VisualBasic.Devices/NetworkAvailableEventArgs.xml @@ -16,7 +16,7 @@ and the events occur when the availability of the network changes. + The and the events occur when the availability of the network changes. contains the new state of the network connection. To get the current state of the network connection, use the property. @@ -43,7 +43,7 @@ and the events occur when the availability of the network changes. + The and the events occur when the availability of the network changes. contains the new state of the network connection. To get the current state of the network connection, use the property. @@ -70,7 +70,7 @@ and the events occur when the availability of the network changes. + The and the events occur when the availability of the network changes. contains the new state of the network connection. To get the current state of the network connection, use the property. diff --git a/xml/Microsoft.VisualBasic.Devices/NetworkAvailableEventHandler.xml b/xml/Microsoft.VisualBasic.Devices/NetworkAvailableEventHandler.xml index 11a07dfa33d8c..0bfeff680725e 100644 --- a/xml/Microsoft.VisualBasic.Devices/NetworkAvailableEventHandler.xml +++ b/xml/Microsoft.VisualBasic.Devices/NetworkAvailableEventHandler.xml @@ -29,7 +29,7 @@ event or the event. + In Visual Basic, you do not need to work with this delegate explicitly. For more information, see the event or the event. ]]> diff --git a/xml/Microsoft.VisualBasic.Devices/Ports.xml b/xml/Microsoft.VisualBasic.Devices/Ports.xml index 7628c4eaf2025..9f5457867738a 100644 --- a/xml/Microsoft.VisualBasic.Devices/Ports.xml +++ b/xml/Microsoft.VisualBasic.Devices/Ports.xml @@ -503,7 +503,7 @@ This example requires: -- A reference to the namespace. +- A reference to the namespace. - That your form have a control named `ListBox1`. diff --git a/xml/Microsoft.VisualBasic.FileIO/FileSystem.xml b/xml/Microsoft.VisualBasic.FileIO/FileSystem.xml index 5483599f31225..de70427f54ace 100644 --- a/xml/Microsoft.VisualBasic.FileIO/FileSystem.xml +++ b/xml/Microsoft.VisualBasic.FileIO/FileSystem.xml @@ -1591,7 +1591,7 @@ ## Examples - This example retrieves a object for the file `MyLogFile.log` and uses it to report the file's full name, last access time, and length. + This example retrieves a object for the file `MyLogFile.log` and uses it to report the file's full name, last access time, and length. [!code-vb[VbRefFile#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb#1)] diff --git a/xml/Microsoft.VisualBasic.FileIO/MalformedLineException.xml b/xml/Microsoft.VisualBasic.FileIO/MalformedLineException.xml index 8c297a9e21b26..da3b7764a48c5 100644 --- a/xml/Microsoft.VisualBasic.FileIO/MalformedLineException.xml +++ b/xml/Microsoft.VisualBasic.FileIO/MalformedLineException.xml @@ -319,7 +319,7 @@ If there is no error message or if it is an empty string (""), then no error message is returned. The name of the inner exception and the stack trace are returned only if they are not a null reference (`Nothing` in Visual Basic). - This method overrides . + This method overrides . ]]> diff --git a/xml/Microsoft.VisualBasic.Logging/AspLog.xml b/xml/Microsoft.VisualBasic.Logging/AspLog.xml index b3464a0442bed..8978f24bd13c9 100644 --- a/xml/Microsoft.VisualBasic.Logging/AspLog.xml +++ b/xml/Microsoft.VisualBasic.Logging/AspLog.xml @@ -18,7 +18,7 @@ ## Remarks The `My.Application.Log` object provides a straightforward entry point from which to access the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)]'s logging services. The `WriteEntry` and `WriteException` methods write messages to the application's log listeners. The listeners can be configured by the application's configuration file. For more information, see [Walkthrough: Changing Where My.Application.Log Writes Information](~/docs/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information.md) and [Working with Application Logs](~/docs/visual-basic/developing-apps/programming/log-info/working-with-application-logs.md). - The `My.Application.Log` object is available only for client applications. For Web applications, use `My.Log`. For more information, see . + The `My.Application.Log` object is available only for client applications. For Web applications, use `My.Log`. For more information, see . The following table lists examples of tasks involving the `My.Application.Log` object. diff --git a/xml/Microsoft.VisualBasic.Logging/FileLogTraceListener.xml b/xml/Microsoft.VisualBasic.Logging/FileLogTraceListener.xml index e6118cd67eaf0..94a84b01ada0a 100644 --- a/xml/Microsoft.VisualBasic.Logging/FileLogTraceListener.xml +++ b/xml/Microsoft.VisualBasic.Logging/FileLogTraceListener.xml @@ -23,7 +23,7 @@ ## Remarks The class provides automated maintenance capabilities to archive log files as needed, on a daily or per-application basis. This automatic archival functionality helps reduce the maintenance responsibilities of developers and administrators. - An instance of can be added to the or collections to redirect output from logging to a text file. Instances of this class can also be added to `My.Application.Log` or `My.Log` (for Web applications) in [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] applications. For more information, see [Walkthrough: Changing Where My.Application.Log Writes Information](~/docs/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information.md)`.` + An instance of can be added to the or collections to redirect output from logging to a text file. Instances of this class can also be added to `My.Application.Log` or `My.Log` (for Web applications) in [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] applications. For more information, see [Walkthrough: Changing Where My.Application.Log Writes Information](~/docs/visual-basic/developing-apps/programming/log-info/walkthrough-changing-where-my-application-log-writes-information.md)`.` The main features of this class are: diff --git a/xml/Microsoft.VisualBasic.MyServices/FileSystemProxy.xml b/xml/Microsoft.VisualBasic.MyServices/FileSystemProxy.xml index 136a1a0b0a68c..aabda09ed336b 100644 --- a/xml/Microsoft.VisualBasic.MyServices/FileSystemProxy.xml +++ b/xml/Microsoft.VisualBasic.MyServices/FileSystemProxy.xml @@ -1574,7 +1574,7 @@ ## Examples - This example retrieves a object for the file `MyLogFile.log` and uses it to report the file's full name, last access time, and length. + This example retrieves a object for the file `MyLogFile.log` and uses it to report the file's full name, last access time, and length. [!code-vb[VbRefFile#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbRefFile/VB/Class1.vb#1)] diff --git a/xml/Microsoft.VisualBasic/Collection.xml b/xml/Microsoft.VisualBasic/Collection.xml index 120fca3b60bb1..a28bd72a19e2c 100644 --- a/xml/Microsoft.VisualBasic/Collection.xml +++ b/xml/Microsoft.VisualBasic/Collection.xml @@ -36,7 +36,7 @@ ## Remarks > [!NOTE] -> Whenever possible, you should use the generic collections in the namespace or the namespace instead of a Visual Basic `Collection`. For more information, see [Collections](http://msdn.microsoft.com/library/e76533a9-5033-4a0b-b003-9c2be60d185b). +> Whenever possible, you should use the generic collections in the namespace or the namespace instead of a Visual Basic `Collection`. For more information, see [Collections](http://msdn.microsoft.com/library/e76533a9-5033-4a0b-b003-9c2be60d185b). The Visual Basic `Collection` object provides a convenient way to refer to a related group of items as a single object. The items, or *elements*, in a collection need only be related by the fact that they exist in the collection. Elements of a collection do not have to share the same data type. @@ -99,7 +99,7 @@ Dim coll As New Microsoft.VisualBasic.Collection() ## Remarks The [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] collection returned by this constructor is empty and does not have any initial capacity allocated. - [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] collections are not compatible with the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] collections available in the , , and namespaces. + [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)] collections are not compatible with the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] collections available in the , , and namespaces. diff --git a/xml/Microsoft.VisualBasic/Conversion.xml b/xml/Microsoft.VisualBasic/Conversion.xml index 4675a239d1c27..ea85f478aa033 100644 --- a/xml/Microsoft.VisualBasic/Conversion.xml +++ b/xml/Microsoft.VisualBasic/Conversion.xml @@ -1950,7 +1950,7 @@ Val("&HFFFF")  ``` > [!NOTE] -> The `Val` function recognizes only the period (`.`) as a valid decimal separator. When different decimal separators are used, as in international applications, use `CDbl` or `CInt` instead to convert a string to a number. To convert the string representation of a number in a particular culture to a numeric value, use the numeric type's `Parse(String, IFormatProvider)` method. For example, use when converting a string to a `Double`. +> The `Val` function recognizes only the period (`.`) as a valid decimal separator. When different decimal separators are used, as in international applications, use `CDbl` or `CInt` instead to convert a string to a number. To convert the string representation of a number in a particular culture to a numeric value, use the numeric type's `Parse(String, IFormatProvider)` method. For example, use when converting a string to a `Double`. > [!NOTE] > An exception might be raised in response to certain uncommon number formats. For example, the following code raises this exception. @@ -2024,7 +2024,7 @@ Val("&HFFFF")  ``` > [!NOTE] -> The `Val` function recognizes only the period (`.`) as a valid decimal separator. When other decimal separators are used, as in international applications, use `CDbl` or `CInt` instead to convert a string to a number. To convert the string representation of a number in a particular culture to a numeric value, use the numeric type's `Parse(String, IFormatProvider)` method. For example, use when converting a string to a `Double`. +> The `Val` function recognizes only the period (`.`) as a valid decimal separator. When other decimal separators are used, as in international applications, use `CDbl` or `CInt` instead to convert a string to a number. To convert the string representation of a number in a particular culture to a numeric value, use the numeric type's `Parse(String, IFormatProvider)` method. For example, use when converting a string to a `Double`. > [!NOTE] > An exception might be raised in response to certain uncommon number formats. For example, the following code raises this exception. @@ -2098,7 +2098,7 @@ Val("&HFFFF")  ``` > [!NOTE] -> The `Val` function recognizes only the period (`.`) as a valid decimal separator. When other decimal separators are used, as in international applications, use `CDbl` or `CInt` instead to convert a string to a number. To convert the string representation of a number in a particular culture to a numeric value, use the numeric type's `Parse(String, IFormatProvider)` method. For example, use when converting a string to a `Double`. +> The `Val` function recognizes only the period (`.`) as a valid decimal separator. When other decimal separators are used, as in international applications, use `CDbl` or `CInt` instead to convert a string to a number. To convert the string representation of a number in a particular culture to a numeric value, use the numeric type's `Parse(String, IFormatProvider)` method. For example, use when converting a string to a `Double`. > [!NOTE] > An exception might be raised in response to certain uncommon number formats. For example, the following code raises this exception. diff --git a/xml/Microsoft.VisualBasic/DateAndTime.xml b/xml/Microsoft.VisualBasic/DateAndTime.xml index 7298b8e685cd8..6072b32c2f0cb 100644 --- a/xml/Microsoft.VisualBasic/DateAndTime.xml +++ b/xml/Microsoft.VisualBasic/DateAndTime.xml @@ -252,7 +252,7 @@ NextTime = NextTime.AddDays(3.4) ' Increment by 3 2/5 days. For cultures such as Japanese that have multiple eras, the `DateDiff` method does not return a difference in years if the difference spans two or more eras. Instead, you can calculate the difference in values returned by the property, as shown in the following example: `date2.Year - date1.Year`. -- **Other Intervals.** Since every `Date` value is supported by a structure, its methods give you additional options in finding time intervals. For example, you can use the `Subtract` method in either of its overloaded forms: subtracts a from a `Date` variable to return another `Date` value, and subtracts a `Date` value to return a . You can time a process to find out how many milliseconds it takes, as the following example shows. +- **Other Intervals.** Since every `Date` value is supported by a structure, its methods give you additional options in finding time intervals. For example, you can use the `Subtract` method in either of its overloaded forms: subtracts a from a `Date` variable to return another `Date` value, and subtracts a `Date` value to return a . You can time a process to find out how many milliseconds it takes, as the following example shows. [!code-vb[VbVbalrFunctions#61](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrFunctions/VB/Class1.vb#61)] @@ -363,7 +363,7 @@ NextTime = NextTime.AddDays(3.4) ' Increment by 3 2/5 days. For cultures such as Japanese that have multiple eras, the `DateDiff` method does not return a difference in years if the difference spans two or more eras. Instead, you can calculate the difference in values returned by the property, as shown in the following example: `date2.Year - date1.Year`. -- **Other Intervals.** Since every `Date` value is supported by a structure, its methods give you additional options in finding time intervals. For example, you can use the `Subtract` method in either of its overloaded forms: subtracts a from a `Date` variable to return another `Date` value, and subtracts a `Date` value to return a . You can time a process to find out how many milliseconds it takes, as the following example shows. +- **Other Intervals.** Since every `Date` value is supported by a structure, its methods give you additional options in finding time intervals. For example, you can use the `Subtract` method in either of its overloaded forms: subtracts a from a `Date` variable to return another `Date` value, and subtracts a `Date` value to return a . You can time a process to find out how many milliseconds it takes, as the following example shows. [!code-vb[VbVbalrFunctions#61](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrFunctions/VB/Class1.vb#61)] @@ -812,7 +812,7 @@ Dim thisDay As Integer = Microsoft.VisualBasic.DateAndTime.Day(Now) [!code-vb[VbVbalrFunctions#30](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrFunctions/VB/Class1.vb#30)] - `Day` is qualified to distinguish it from the enumeration. + `Day` is qualified to distinguish it from the enumeration. ]]> @@ -1104,7 +1104,7 @@ Dim thisDay As Integer = Microsoft.VisualBasic.DateAndTime.Day(Now) [!code-vb[VbVbalrTimerProperty#1](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrTimerProperty/VB/Form1.vb#1)] - Note that you must qualify the `Timer` property with the namespace, because `Timer` is also a defined class in the , , and namespaces. + Note that you must qualify the `Timer` property with the namespace, because `Timer` is also a defined class in the , , and namespaces. ]]> @@ -1156,7 +1156,7 @@ MsgBox(TimeSerial(23, 75, 0)) If the values of the arguments result in a negative calculated time, the date information is set to 1/1/0001 and the time information is adjusted to be between 00:00:00 and 23:59:59. However, if the calculated time is less than negative 24 hours, an error occurs. - Since every `Date` value is supported by a structure, its methods give you additional options in assembling a `Date` value. For example, you can employ one of the overloaded constructors to populate a `Date` variable using the desired combination of components. The following example sets `newDateTime` to May 6, 1978 at one tenth of a second before 8:30 in the morning: + Since every `Date` value is supported by a structure, its methods give you additional options in assembling a `Date` value. For example, you can employ one of the overloaded constructors to populate a `Date` variable using the desired combination of components. The following example sets `newDateTime` to May 6, 1978 at one tenth of a second before 8:30 in the morning: ```vb Dim newDateTime As Date = New Date(1978, 5, 6, 8, 29, 59, 900) diff --git a/xml/Microsoft.VisualBasic/FileSystem.xml b/xml/Microsoft.VisualBasic/FileSystem.xml index d244bd1364f52..c17462fd663da 100644 --- a/xml/Microsoft.VisualBasic/FileSystem.xml +++ b/xml/Microsoft.VisualBasic/FileSystem.xml @@ -4748,7 +4748,7 @@ Result = GetAttr(FName) And vbArchive The leftmost print position on an output line is always 1. When you use the `Print` or `PrintLine` functions to print to files, the rightmost print position is the current width of the output file, which you can set using the `FileWidth` function. - The `TAB` function can also be used with the `WriteLine` function. It cannot be used with or . + The `TAB` function can also be used with the `WriteLine` function. It cannot be used with or . > [!NOTE] > Make sure your tabular columns are wide enough to contain wide letters. @@ -4795,7 +4795,7 @@ Result = GetAttr(FName) And vbArchive The leftmost print position on an output line is always 1. When you use the `Print` or `PrintLine` functions to print to files, the rightmost print position is the current width of the output file, which you can set using the `FileWidth` function. - The `TAB` function can also be used with the `WriteLine` function. It cannot be used with or . + The `TAB` function can also be used with the `WriteLine` function. It cannot be used with or . > [!NOTE] > Make sure your tabular columns are wide enough to contain wide letters. diff --git a/xml/Microsoft.VisualBasic/Information.xml b/xml/Microsoft.VisualBasic/Information.xml index c6eb99f1ae336..312f0dc58217a 100644 --- a/xml/Microsoft.VisualBasic/Information.xml +++ b/xml/Microsoft.VisualBasic/Information.xml @@ -225,7 +225,7 @@ testVbName = VbTypeName(sysBadName) ## Remarks `IsDBNull` returns `True` if the data type of `Expression` evaluates to the type; otherwise, `IsDBNull` returns `False`. - The value indicates that the `Object` represents missing or nonexistent data. `DBNull` is not the same as `Nothing`, which indicates that a variable has not yet been initialized. `DBNull` is also not the same as a zero-length string (`""`), which is sometimes referred to as a null string. + The value indicates that the `Object` represents missing or nonexistent data. `DBNull` is not the same as `Nothing`, which indicates that a variable has not yet been initialized. `DBNull` is also not the same as a zero-length string (`""`), which is sometimes referred to as a null string. @@ -263,7 +263,7 @@ testVbName = VbTypeName(sysBadName) ## Remarks `IsError` returns `True` if the expression represents an `Object` variable that derives from the class in the namespace. - An exception that derives from can be caught with the `Try...Catch...Finally` statements. + An exception that derives from can be caught with the `Try...Catch...Finally` statements. @@ -640,7 +640,7 @@ Dim a(100, 5, 4) As Byte If `VarName` is an array, the returned string can be any one of the strings in the preceding table with empty parentheses appended. For example, if `VarName` points to an array of integers, `TypeName` returns "Integer()". - When `TypeName` returns the name of a reference type such as a class, it returns only the name itself, not the qualified name. For example, if `VarName` points to an object of class , `TypeName` returns "PaperSource". Note that if the variable is declared to be of a certain class type but does not have an object assigned to it, `TypeName` returns "Nothing". + When `TypeName` returns the name of a reference type such as a class, it returns only the name itself, not the qualified name. For example, if `VarName` points to an object of class , `TypeName` returns "PaperSource". Note that if the variable is declared to be of a certain class type but does not have an object assigned to it, `TypeName` returns "Nothing". @@ -751,7 +751,7 @@ total = (UBound(A, 1) + 1) * (UBound(A, 2) + 1) * (UBound(A, 3) + 1) |Enumeration|Underlying data type (`SByte`, `Byte`, `Short`, `UShort`, `Integer`, `UInteger`, `Long`, or `ULong`)| |Array|Bitwise OR of array element type and `VariantType.Array`| |Array of arrays|Bitwise OR of `VariantType.Object` and `VariantType.Array`| -|Structure ()|`VariantType.UserDefinedType`| +|Structure ()|`VariantType.UserDefinedType`| ||`VariantType.Error`| |Unknown|`VariantType.Object`| diff --git a/xml/Microsoft.VisualBasic/Interaction.xml b/xml/Microsoft.VisualBasic/Interaction.xml index b093da82aeba3..18e176c2ab67c 100644 --- a/xml/Microsoft.VisualBasic/Interaction.xml +++ b/xml/Microsoft.VisualBasic/Interaction.xml @@ -26,7 +26,7 @@ ## Examples - The following example uses the `Shell` function to run an application specified by the user. Specifying as the second argument opens the application in normal size and gives it the focus. + The following example uses the `Shell` function to run an application specified by the user. Specifying as the second argument opens the application in normal size and gives it the focus. ``` Dim procID As Integer @@ -1152,7 +1152,7 @@ drawObj.SaveAs("C:\Drawings\sample.drw") The return value of the `Shell` function depends on whether the program named in `PathName` is still executing when `Shell` returns. If you set `Wait` to `True` and the program finishes before the timeout expires, `Shell` returns zero. If the timeout expires, or if you omit `Wait` or set it to `False`, `Shell` returns the process ID of the program. The process ID is a unique number that identifies the running program. ## Failure to Start - If the `Shell` function cannot start the named program, a error occurs. This can happen, for example, when you attempt to run a 16-bit program, such as `command.com`, from an application using . For a workaround, you can run a 32-bit program that calls the desired 16-bit program. In the case of `command.com`, you can run `cmd.exe` as an alternative. + If the `Shell` function cannot start the named program, a error occurs. This can happen, for example, when you attempt to run a 16-bit program, such as `command.com`, from an application using . For a workaround, you can run a 32-bit program that calls the desired 16-bit program. In the case of `command.com`, you can run `cmd.exe` as an alternative. ## Waiting for Completion By default, the `Shell` function runs the program asynchronously. This means that a program started with the `Shell` function might not finish executing before the statements following the `Shell` function are executed. If you want to wait for the program to finish before you continue, set `Wait` to `True`. @@ -1200,7 +1200,7 @@ ID = Shell("""C:\Program Files\display.exe"" -a -q", , True, 100000) ## Examples - The following example uses the `Shell` function to run an application specified by the user. Specifying as the second argument opens the application in normal size and gives it the focus. + The following example uses the `Shell` function to run an application specified by the user. Specifying as the second argument opens the application in normal size and gives it the focus. [!code-vb[VbVbalrFunctions#47](~/samples/snippets/visualbasic/VS_Snippets_VBCSharp/VbVbalrFunctions/VB/Class1.vb#47)] diff --git a/xml/Microsoft.VisualBasic/Strings.xml b/xml/Microsoft.VisualBasic/Strings.xml index 0dc28ecc3fdbb..d135e851bb525 100644 --- a/xml/Microsoft.VisualBasic/Strings.xml +++ b/xml/Microsoft.VisualBasic/Strings.xml @@ -223,7 +223,7 @@ ## Remarks The asymmetric range accepted for `CharCode` compensates for the storage differences between the `Short` and the `Integer`. For example, -29183 is a `Short` but +36353 is an `Integer`. This also facilitates compatibility with Visual Basic 6.0. - `Chr` uses the class in the namespace to determine if the current thread is using a single-byte character set (SBCS) or a double-byte character set (DBCS). It then takes `CharCode` as a code point in the appropriate set. The range can be 0 through 255 for SBCS characters and -32768 through 65535 for DBCS characters. + `Chr` uses the class in the namespace to determine if the current thread is using a single-byte character set (SBCS) or a double-byte character set (DBCS). It then takes `CharCode` as a code point in the appropriate set. The range can be 0 through 255 for SBCS characters and -32768 through 65535 for DBCS characters. The returned value depends on the code page for the current thread, which is contained in the property of the class in the namespace. You can obtain by specifying `System.Globalization.CultureInfo.CurrentCulture.TextInfo.ANSICodePage`. @@ -272,7 +272,7 @@ ## Remarks The asymmetric range accepted for `CharCode` compensates for the storage differences between the `Short` and the `Integer`. For example, -29183 is a `Short` but +36353 is an `Integer`. This also facilitates compatibility with Visual Basic 6.0. - `Chr` uses the class in the namespace to determine if the current thread is using a single-byte character set (SBCS) or a double-byte character set (DBCS). It then takes `CharCode` as a code point in the appropriate set. The range can be 0 through 255 for SBCS characters and -32768 through 65535 for DBCS characters. + `Chr` uses the class in the namespace to determine if the current thread is using a single-byte character set (SBCS) or a double-byte character set (DBCS). It then takes `CharCode` as a code point in the appropriate set. The range can be 0 through 255 for SBCS characters and -32768 through 65535 for DBCS characters. The returned value depends on the code page for the current thread, which is contained in the property of the class in the namespace. You can obtain by specifying `System.Globalization.CultureInfo.CurrentCulture.TextInfo.ANSICodePage`. @@ -440,7 +440,7 @@ method also provides similar functionality. + The method also provides similar functionality. If you are formatting a nonlocalized numeric string, you should use a user-defined numeric format to ensure that you get the look you want. @@ -1303,7 +1303,7 @@ This function uses the application's culture information when manipulating the string so that the case changes are appropriate for the locale in which the application is being used. > [!IMPORTANT] -> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). +> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). @@ -1344,7 +1344,7 @@ This function uses the application's culture information when manipulating the string so that the case changes are appropriate for the locale in which the application is being used. > [!IMPORTANT] -> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). +> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). @@ -2752,7 +2752,7 @@ Dim aString As String = Replace(TestString, "o", "i") This function uses the application's culture information when manipulating the string so that the case changes are appropriate for the locale in which the application is being used. > [!IMPORTANT] -> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). +> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). The `Conversion` argument settings are: @@ -3015,7 +3015,7 @@ Dim aString As String = Replace(TestString, "o", "i") This function uses the application's culture information when manipulating the string so that the case changes are appropriate for the locale in which the application is being used. > [!IMPORTANT] -> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). +> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). @@ -3056,7 +3056,7 @@ Dim aString As String = Replace(TestString, "o", "i") This function uses the application's culture information when manipulating the string so that the case changes are appropriate for the locale in which the application is being used. > [!IMPORTANT] -> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). +> If your application makes security decisions based on the result of a comparison or case-change operation, then the operation should use the method, and pass or for the `comparisonType` argument. For more information, see [How Culture Affects Strings in Visual Basic](~/docs/visual-basic/programming-guide/language-features/strings/how-culture-affects-strings.md). diff --git a/xml/Microsoft.VisualC.StlClr.Generic/ConstContainerBidirectionalIterator`1.xml b/xml/Microsoft.VisualC.StlClr.Generic/ConstContainerBidirectionalIterator`1.xml index 9a13a94196c18..c6ca92d6e8bc8 100644 --- a/xml/Microsoft.VisualC.StlClr.Generic/ConstContainerBidirectionalIterator`1.xml +++ b/xml/Microsoft.VisualC.StlClr.Generic/ConstContainerBidirectionalIterator`1.xml @@ -343,7 +343,7 @@ if the two iterators are the same object; otherwise, . - ]]> + ]]> @@ -455,7 +455,7 @@ if the two iterators are different objects; otherwise, . - ]]> + ]]> diff --git a/xml/Microsoft.VisualC.StlClr.Generic/ConstContainerRandomAccessIterator`1.xml b/xml/Microsoft.VisualC.StlClr.Generic/ConstContainerRandomAccessIterator`1.xml index 9b6e31a3bb235..5c78dfced8761 100644 --- a/xml/Microsoft.VisualC.StlClr.Generic/ConstContainerRandomAccessIterator`1.xml +++ b/xml/Microsoft.VisualC.StlClr.Generic/ConstContainerRandomAccessIterator`1.xml @@ -357,7 +357,7 @@ Increments the iterator by the given number of elements. The integer parameter is specified on the right side of the addition operator. An iterator. - ]]> + ]]> @@ -535,7 +535,7 @@ if the two iterators are the same object; otherwise, . - ]]> + ]]> @@ -641,7 +641,7 @@ if the left-side iterator is greater than or equal to the given right-side iterator; otherwise, . - ]]> + ]]> @@ -753,7 +753,7 @@ if the two iterators are different objects; otherwise, . - ]]> + ]]> @@ -810,7 +810,7 @@ if the left-side iterator is less than the given right-side iterator; otherwise, . - ]]> + ]]> @@ -950,7 +950,7 @@ Determines the difference between two iterators. The difference, in number of elements, between the two iterators. - ]]> + ]]> @@ -976,7 +976,7 @@ Decrements the iterator by the given number of elements. The integer parameter is specified on the right side of the addition operator. A decremented iterator. - ]]> + ]]> diff --git a/xml/Microsoft.VisualC.StlClr.Generic/ConstReverseBidirectionalIterator`1.xml b/xml/Microsoft.VisualC.StlClr.Generic/ConstReverseBidirectionalIterator`1.xml index 451cbbabe8d3d..1a0c32bb30b0d 100644 --- a/xml/Microsoft.VisualC.StlClr.Generic/ConstReverseBidirectionalIterator`1.xml +++ b/xml/Microsoft.VisualC.StlClr.Generic/ConstReverseBidirectionalIterator`1.xml @@ -362,7 +362,7 @@ if the two iterators are the same object; otherwise, . - ]]> + ]]> @@ -474,7 +474,7 @@ if the two iterators are different objects; otherwise, . - ]]> + ]]> diff --git a/xml/Microsoft.VisualC.StlClr.Generic/ConstReverseRandomAccessIterator`1.xml b/xml/Microsoft.VisualC.StlClr.Generic/ConstReverseRandomAccessIterator`1.xml index 4780063da5f1b..7a07092949a20 100644 --- a/xml/Microsoft.VisualC.StlClr.Generic/ConstReverseRandomAccessIterator`1.xml +++ b/xml/Microsoft.VisualC.StlClr.Generic/ConstReverseRandomAccessIterator`1.xml @@ -374,7 +374,7 @@ Increments the reverse iterator by the given number of elements. The integer parameter is specified on the right side of the addition operator. An iterator. - ]]> + ]]> @@ -796,7 +796,7 @@ Determines the difference between two iterators. The difference (number of elements) between the two iterators. - ]]> + ]]> @@ -822,7 +822,7 @@ Decrements the iterator by the given number of elements. The integer parameter is specified on the right side of the subtraction operator. An iterator. - ]]> + ]]> diff --git a/xml/Microsoft.VisualC.StlClr.Generic/ContainerBidirectionalIterator`1.xml b/xml/Microsoft.VisualC.StlClr.Generic/ContainerBidirectionalIterator`1.xml index ef965af2158f1..0460907a74b40 100644 --- a/xml/Microsoft.VisualC.StlClr.Generic/ContainerBidirectionalIterator`1.xml +++ b/xml/Microsoft.VisualC.StlClr.Generic/ContainerBidirectionalIterator`1.xml @@ -303,7 +303,7 @@ if the two iterators are the same object; otherwise, . - ]]> + ]]> @@ -415,7 +415,7 @@ if the two iterators are different objects; otherwise, . - ]]> + ]]> diff --git a/xml/Microsoft.VisualC.StlClr.Generic/ContainerRandomAccessIterator`1.xml b/xml/Microsoft.VisualC.StlClr.Generic/ContainerRandomAccessIterator`1.xml index 61b93da0e4b6d..6794c5d722da8 100644 --- a/xml/Microsoft.VisualC.StlClr.Generic/ContainerRandomAccessIterator`1.xml +++ b/xml/Microsoft.VisualC.StlClr.Generic/ContainerRandomAccessIterator`1.xml @@ -339,7 +339,7 @@ Increments the iterator by the given number of elements. The integer parameter is specified on the right side of the addition operator. An iterator. - ]]> + ]]> @@ -495,7 +495,7 @@ if the two iterators are the same object; otherwise, . - ]]> + ]]> @@ -601,7 +601,7 @@ if the left-side iterator is greater than or equal to the given right-side iterator; otherwise, . - ]]> + ]]> @@ -713,7 +713,7 @@ if the two iterators are different objects; otherwise, . - ]]> + ]]> @@ -770,7 +770,7 @@ if the left-side iterator is less than the given right-side iterator; otherwise, . - ]]> + ]]> @@ -910,7 +910,7 @@ Determines the difference between two iterators. The difference (number of elements) between the two iterators. - ]]> + ]]> @@ -936,7 +936,7 @@ Decrements the iterator by the given number of elements. The integer parameter is specified on the right side of the subtraction operator. An iterator. - ]]> + ]]> diff --git a/xml/Microsoft.Win32.SafeHandles/CriticalHandleMinusOneIsInvalid.xml b/xml/Microsoft.Win32.SafeHandles/CriticalHandleMinusOneIsInvalid.xml index 5a56db2bfb7fa..6b41c07c0558c 100644 --- a/xml/Microsoft.Win32.SafeHandles/CriticalHandleMinusOneIsInvalid.xml +++ b/xml/Microsoft.Win32.SafeHandles/CriticalHandleMinusOneIsInvalid.xml @@ -30,7 +30,7 @@ class. It describes the format of an invalid handle that uses a value of -1. Further derivations of this class (for example, file or registry handles) can specialize this further. + This class derives from the class. It describes the format of an invalid handle that uses a value of -1. Further derivations of this class (for example, file or registry handles) can specialize this further. This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. diff --git a/xml/Microsoft.Win32.SafeHandles/CriticalHandleZeroOrMinusOneIsInvalid.xml b/xml/Microsoft.Win32.SafeHandles/CriticalHandleZeroOrMinusOneIsInvalid.xml index e0bf1a2f551f7..de7a8d1c787d0 100644 --- a/xml/Microsoft.Win32.SafeHandles/CriticalHandleZeroOrMinusOneIsInvalid.xml +++ b/xml/Microsoft.Win32.SafeHandles/CriticalHandleZeroOrMinusOneIsInvalid.xml @@ -30,7 +30,7 @@ class. It describes the format of an invalid handle. For example, some handles use -1 as an invalid handle value, while others use 0. Further derivations of this class (for example, file or registry handles) can specialize this further. + This class derives from the class. It describes the format of an invalid handle. For example, some handles use -1 as an invalid handle value, while others use 0. Further derivations of this class (for example, file or registry handles) can specialize this further. Use the class when you need to wrap an unmanaged resource that does not have an existing managed wrapper. diff --git a/xml/Microsoft.Win32.SafeHandles/SafeHandleMinusOneIsInvalid.xml b/xml/Microsoft.Win32.SafeHandles/SafeHandleMinusOneIsInvalid.xml index f03aaed497993..daf666c0cd25f 100644 --- a/xml/Microsoft.Win32.SafeHandles/SafeHandleMinusOneIsInvalid.xml +++ b/xml/Microsoft.Win32.SafeHandles/SafeHandleMinusOneIsInvalid.xml @@ -30,7 +30,7 @@ class. It describes the format of an invalid handle that uses a value of -1. Further derivations of this class (for example, file or registry handles) can specialize this further. See the class for an example of a class that derives from . + This class derives from the class. It describes the format of an invalid handle that uses a value of -1. Further derivations of this class (for example, file or registry handles) can specialize this further. See the class for an example of a class that derives from . > [!WARNING] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`-`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. diff --git a/xml/Microsoft.Win32.SafeHandles/SafeHandleZeroOrMinusOneIsInvalid.xml b/xml/Microsoft.Win32.SafeHandles/SafeHandleZeroOrMinusOneIsInvalid.xml index 12fde7c462ecd..b622480f2920c 100644 --- a/xml/Microsoft.Win32.SafeHandles/SafeHandleZeroOrMinusOneIsInvalid.xml +++ b/xml/Microsoft.Win32.SafeHandles/SafeHandleZeroOrMinusOneIsInvalid.xml @@ -30,7 +30,7 @@ class. It describes the format of an invalid handle. For example, some handles use -1 as an invalid handle value, while others use 0. Further derivations of this class (for example, file or registry handles) can specialize this further. See the class for an example of a class that derives from . + This class derives from the class. It describes the format of an invalid handle. For example, some handles use -1 as an invalid handle value, while others use 0. Further derivations of this class (for example, file or registry handles) can specialize this further. See the class for an example of a class that derives from . > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. diff --git a/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedFileHandle.xml b/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedFileHandle.xml index ab19e409141bc..9e6150de9ac08 100644 --- a/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedFileHandle.xml +++ b/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedFileHandle.xml @@ -27,7 +27,7 @@ property to obtain the safe handle. + Use the property to obtain the safe handle. > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. diff --git a/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedViewHandle.xml b/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedViewHandle.xml index e067b3ab33b01..0c753022bd22f 100644 --- a/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedViewHandle.xml +++ b/xml/Microsoft.Win32.SafeHandles/SafeMemoryMappedViewHandle.xml @@ -26,7 +26,7 @@ property to obtain the safe handle. + Use the property to obtain the safe handle. > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. diff --git a/xml/Microsoft.Win32.SafeHandles/SafeRegistryHandle.xml b/xml/Microsoft.Win32.SafeHandles/SafeRegistryHandle.xml index b9771d5539f7a..a4a2517068544 100644 --- a/xml/Microsoft.Win32.SafeHandles/SafeRegistryHandle.xml +++ b/xml/Microsoft.Win32.SafeHandles/SafeRegistryHandle.xml @@ -28,7 +28,7 @@ object, and then use it to create registry keys with the method. + You can use platform invoke on the native `RegCreateKeyEx` Windows function to obtain a object, and then use it to create registry keys with the method. > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. diff --git a/xml/Microsoft.Win32.SafeHandles/SafeWaitHandle.xml b/xml/Microsoft.Win32.SafeHandles/SafeWaitHandle.xml index 2f53e50f4a363..ee55d94dc6a6f 100644 --- a/xml/Microsoft.Win32.SafeHandles/SafeWaitHandle.xml +++ b/xml/Microsoft.Win32.SafeHandles/SafeWaitHandle.xml @@ -35,7 +35,7 @@ class is used by the class. It is a wrapper for Win32 mutexes and auto and manual reset events. + The class is used by the class. It is a wrapper for Win32 mutexes and auto and manual reset events. > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. diff --git a/xml/Microsoft.Win32/IntranetZoneCredentialPolicy.xml b/xml/Microsoft.Win32/IntranetZoneCredentialPolicy.xml index 4a886a56f1fa2..e65cb992f83f0 100644 --- a/xml/Microsoft.Win32/IntranetZoneCredentialPolicy.xml +++ b/xml/Microsoft.Win32/IntranetZoneCredentialPolicy.xml @@ -25,7 +25,7 @@ > [!NOTE] > policies are invoked only if the or the that is associated with the request has credentials that are not `null`. Setting this policy has no effect on requests that do not specify credentials. - Use the property to set the policy. The that handles authentication for the request will invoke the method before performing the authentication. If the requested resource is in a different domain than the client, the method returns `false`, and authentication is not performed. + Use the property to set the policy. The that handles authentication for the request will invoke the method before performing the authentication. If the requested resource is in a different domain than the client, the method returns `false`, and authentication is not performed. This policy affects all instances of with non-null credentials in the current application domain. The policy cannot be overridden on individual requests. diff --git a/xml/Microsoft.Win32/Registry.xml b/xml/Microsoft.Win32/Registry.xml index 95f39e0831a11..0ce324a7d4622 100644 --- a/xml/Microsoft.Win32/Registry.xml +++ b/xml/Microsoft.Win32/Registry.xml @@ -291,10 +291,10 @@ Valid root names are HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS, HKEY_PERFORMANCE_DATA, HKEY_CURRENT_CONFIG, and HKEY_DYN_DATA. For example, in Visual Basic the string "HKEY_CURRENT_USER\MyTestKey" accesses key/value pairs for the subkey "MyTestKey" in the HKEY_CURRENT_USER root. - When the method retrieves expandable string values (), it expands environment strings using data from the local environment. If a value containing expandable references to environment variables has been stored as a string (), rather than as an expandable string (), does not expand it. You can expand such a string after it has been retrieved by calling the method. + When the method retrieves expandable string values (), it expands environment strings using data from the local environment. If a value containing expandable references to environment variables has been stored as a string (), rather than as an expandable string (), does not expand it. You can expand such a string after it has been retrieved by calling the method. > [!NOTE] -> The recommended way to retrieve data from HKEY_PERFORMANCE_DATA is to use the class rather than the method. +> The recommended way to retrieve data from HKEY_PERFORMANCE_DATA is to use the class rather than the method. The and methods open and close registry keys each time they are used, so they do not perform as well as the methods of the class if you access a large number of values. @@ -490,13 +490,13 @@ Valid root names include HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS, HKEY_PERFORMANCE_DATA, HKEY_CURRENT_CONFIG, and HKEY_DYN_DATA. > [!NOTE] -> The method opens a registry key, sets the value, and closes the key each time it is called. If you need to modify a large number of values, the method might provide better performance. The class also provides methods that allow you to add an access control list (ACL) to a registry key, to test the data type of a value before retrieving it, and to delete keys. +> The method opens a registry key, sets the value, and closes the key each time it is called. If you need to modify a large number of values, the method might provide better performance. The class also provides methods that allow you to add an access control list (ACL) to a registry key, to test the data type of a value before retrieving it, and to delete keys. - This overload of stores 64-bit integers as strings (). To store 64-bit numbers as values, use the method overload. + This overload of stores 64-bit integers as strings (). To store 64-bit numbers as values, use the method overload. - This overload of stores all string values as objects, even if they contain expandable references to environment variables. To save string values as expandable strings (), use the method overload. + This overload of stores all string values as objects, even if they contain expandable references to environment variables. To save string values as expandable strings (), use the method overload. - This overload is equivalent to calling the method overload with . + This overload is equivalent to calling the method overload with . > [!NOTE] > On Windows 98 and Windows Millennium Edition (Windows Me), the registry is not Unicode, and not all Unicode characters are valid for all code pages. A Unicode character that is invalid for the current code page is replaced by the best available match. No exception is thrown. @@ -573,12 +573,12 @@ Valid root names include HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS, HKEY_PERFORMANCE_DATA, HKEY_CURRENT_CONFIG, and HKEY_DYN_DATA. > [!NOTE] -> The method opens a registry key, sets the value, and closes the key each time it is called. If you need to modify a large number of values, the method might provide better performance. The class also provides methods that allow you to add an access control list (ACL) to a registry key, to test the data type of a value before retrieving it, and to delete keys. +> The method opens a registry key, sets the value, and closes the key each time it is called. If you need to modify a large number of values, the method might provide better performance. The class also provides methods that allow you to add an access control list (ACL) to a registry key, to test the data type of a value before retrieving it, and to delete keys. - If the type of the specified `value` does not match the specified `valueKind`, and the data cannot be converted, is thrown. For example, you can store a as a , but only if its value is less than the maximum value of a . You cannot store a single string value as a . + If the type of the specified `value` does not match the specified `valueKind`, and the data cannot be converted, is thrown. For example, you can store a as a , but only if its value is less than the maximum value of a . You cannot store a single string value as a . > [!NOTE] -> If boxed values are passed for or , the conversion is done using the invariant culture. +> If boxed values are passed for or , the conversion is done using the invariant culture. > [!NOTE] > On Windows 98 and Windows Millennium Edition (Windows Me), the registry is not Unicode, and not all Unicode characters are valid for all code pages. A Unicode character that is invalid for the current code page is replaced by the best available match. No exception is thrown. diff --git a/xml/Microsoft.Win32/RegistryKey.xml b/xml/Microsoft.Win32/RegistryKey.xml index 0bd15070e0493..9b627c5745667 100644 --- a/xml/Microsoft.Win32/RegistryKey.xml +++ b/xml/Microsoft.Win32/RegistryKey.xml @@ -368,9 +368,9 @@ ## Remarks The method creates a registry key that has the access control specified by the `registrySecurity` parameter. The object that is returned represents the registry key, but that object is not restricted by the access control specified in the `registrySecurity` parameter. - If `permissionCheck` is , the key is opened for read/write access. If `permissionCheck` is , the key is opened for read access. + If `permissionCheck` is , the key is opened for read/write access. If `permissionCheck` is , the key is opened for read access. - For backward compatibility, the key is opened for reading and writing if `permissionCheck` is and the parent key also has . If the parent key has any other setting, read/write status is controlled by the parent key's setting. + For backward compatibility, the key is opened for reading and writing if `permissionCheck` is and the parent key also has . If the parent key has any other setting, read/write status is controlled by the parent key's setting. In order to perform this action, the user must have permissions at this level and below in the registry hierarchy. @@ -1002,9 +1002,9 @@ method overload with the bitwise combination of the following flags: , , and . You can use that overload to search for other permissions. + This method overload is equivalent to calling the method overload with the bitwise combination of the following flags: , , and . You can use that overload to search for other permissions. - The user must have rights to call this method. + The user must have rights to call this method. ]]> @@ -1040,9 +1040,9 @@ , , and . Alternatively, you can use the method overload, which specifies exactly that combination of values. + To request the access permissions currently granted to users, specify the bitwise combination of the following flags: , , and . Alternatively, you can use the method overload, which specifies exactly that combination of values. - The user must have rights to call this method. + The user must have rights to call this method. ]]> @@ -1130,13 +1130,13 @@ > [!NOTE] > A registry key can have one value that is not associated with any name. When this unnamed value is displayed in the registry editor, the string "(Default)" appears instead of a name. To retrieve this unnamed value, specify either `null` or the empty string ("") for `name`. - When the method retrieves expandable string values (), it expands environment strings using data from the local environment. To retrieve expandable string values from the registry on a remote computer, use the method overload to specify that you do not want environment strings expanded. + When the method retrieves expandable string values (), it expands environment strings using data from the local environment. To retrieve expandable string values from the registry on a remote computer, use the method overload to specify that you do not want environment strings expanded. > [!NOTE] -> If a value containing expandable references to environment variables has been stored as a string (), rather than as an expandable string (), does not expand it. You can expand such a string after it has been retrieved by calling the method. +> If a value containing expandable references to environment variables has been stored as a string (), rather than as an expandable string (), does not expand it. You can expand such a string after it has been retrieved by calling the method. > [!NOTE] -> The recommended way to retrieve data from the key is to use the class rather than the method. +> The recommended way to retrieve data from the key is to use the class rather than the method. > > does not support reading values of type REG_NONE or REG_LINK. In both cases, the default value (`null`) is returned instead of the actual value. @@ -1195,13 +1195,13 @@ > [!NOTE] > A registry key can have one value that is not associated with any name. When this unnamed value is displayed in the registry editor, the string "(Default)" appears instead of a name. To retrieve this unnamed value, specify either `null` or the empty string ("") for `name`. - When the method retrieves expandable string values (), it expands environment strings using data from the local environment. To retrieve expandable string values from the registry on a remote computer, use the overload to specify that you do not want environment strings expanded. + When the method retrieves expandable string values (), it expands environment strings using data from the local environment. To retrieve expandable string values from the registry on a remote computer, use the overload to specify that you do not want environment strings expanded. > [!NOTE] -> If a value containing expandable references to environment variables has been stored as a string (), rather than as an expandable string (), the method does not expand it. You can expand such a string after it has been retrieved by calling the method. +> If a value containing expandable references to environment variables has been stored as a string (), rather than as an expandable string (), the method does not expand it. You can expand such a string after it has been retrieved by calling the method. > [!NOTE] -> The recommended way to retrieve data from the key is to use the class rather than the method. +> The recommended way to retrieve data from the key is to use the class rather than the method. > > does not support reading values of type REG_NONE or REG_LINK. In both cases, the default value (`null`) is returned instead of the actual value. @@ -1262,7 +1262,7 @@ when retrieving a registry value of type to retrieve the string without expanding embedded environment variables. + Use this overload to specify special processing of the retrieved value. For example, you can specify when retrieving a registry value of type to retrieve the string without expanding embedded environment variables. Use the `defaultValue` parameter to specify the value to return if `name` does not exist. @@ -1548,7 +1548,7 @@ . The requested key must be a root key on the remote machine, and is identified by the appropriate value. + The local machine registry is opened if `machineName` is . The requested key must be a root key on the remote machine, and is identified by the appropriate value. In order for a key to be opened remotely, both the server and client machines must be running the remote registry service, and have remote administration enabled. @@ -1610,7 +1610,7 @@ . The requested key must be a root key on the remote machine, and is identified by the appropriate value. + The local machine registry is opened if `machineName` is . The requested key must be a root key on the remote machine, and is identified by the appropriate value. In order for a key to be opened remotely, both the server and client machines must be running the remote registry service, and have remote administration enabled. @@ -1718,7 +1718,7 @@ ## Remarks Rather than throwing an exception, this method returns `null` if the requested key does not exist. - If `permissionCheck` is , the key is opened for reading and writing; if `permissionCheck` is or , the key is opened for reading unless the parent key was opened with . + If `permissionCheck` is , the key is opened for reading and writing; if `permissionCheck` is or , the key is opened for reading unless the parent key was opened with . In order to use the method, you must have an instance of the class. To get an instance of , use one of the static members of the class. @@ -1884,9 +1884,9 @@ ## Remarks Rather than throwing an exception, this method returns `null` if the requested key does not exist. - If `permissionCheck` is , the key is opened for reading and writing; if `permissionCheck` is or , the key is opened for reading unless the parent key was opened with . + If `permissionCheck` is , the key is opened for reading and writing; if `permissionCheck` is or , the key is opened for reading unless the parent key was opened with . - The access specified for `permissionCheck` takes precedence over the access specified for `rights`. For example, if you specify for `permissionCheck` and for `rights`, an attempt to write to the subkey throws an exception. + The access specified for `permissionCheck` takes precedence over the access specified for `rights`. For example, if you specify for `permissionCheck` and for `rights`, an attempt to write to the subkey throws an exception. In order to use the method, you must have an instance of the class. To get an instance of , use one of the static members of the class. @@ -1996,9 +1996,9 @@ If the specified `name` does not exist in the key, it is created and the associated value is set to `value`. - This overload of stores 64-bit integers as strings (). To store 64-bit numbers as values, use the overload that specifies . + This overload of stores 64-bit integers as strings (). To store 64-bit numbers as values, use the overload that specifies . - This overload of stores all string values as , even if they contain expandable references to environment variables. To save string values as expandable strings (), use the overload that specifies . + This overload of stores all string values as , even if they contain expandable references to environment variables. To save string values as expandable strings (), use the overload that specifies . Numeric types other than 32-bit integers are stored as strings by this method overload. Enumeration elements are stored as strings containing the element names. @@ -2084,10 +2084,10 @@ > [!NOTE] > Specifying the registry data type is the same as using the overload. - If the type of the specified `value` does not match the specified `valueKind`, and the data cannot be converted, is thrown. For example, you can store a as a , but only if its value is less than the maximum value of a . You cannot store a single string value as a . + If the type of the specified `value` does not match the specified `valueKind`, and the data cannot be converted, is thrown. For example, you can store a as a , but only if its value is less than the maximum value of a . You cannot store a single string value as a . > [!NOTE] -> If boxed values are passed for or , the conversion is done using the invariant culture. +> If boxed values are passed for or , the conversion is done using the invariant culture. > [!CAUTION] > Do not expose objects in such a way that a malicious program could create thousands of meaningless subkeys or key/value pairs. For example, do not allow callers to enter arbitrary keys or values. diff --git a/xml/Microsoft.Win32/RegistryOptions.xml b/xml/Microsoft.Win32/RegistryOptions.xml index cbf977a60c987..a30d0a1de1d32 100644 --- a/xml/Microsoft.Win32/RegistryOptions.xml +++ b/xml/Microsoft.Win32/RegistryOptions.xml @@ -26,7 +26,7 @@ method overloads that take an `options` parameter. + You can create a registry key that is available only in memory and that will not be persisted when the computer is restarted. This is known as a volatile key. You can specify that you want to create a volatile or non-volatile key by using the method overloads that take an `options` parameter. ]]> diff --git a/xml/Microsoft.Win32/RegistryValueKind.xml b/xml/Microsoft.Win32/RegistryValueKind.xml index 764a34b0b45e5..79ba7cbcfde25 100644 --- a/xml/Microsoft.Win32/RegistryValueKind.xml +++ b/xml/Microsoft.Win32/RegistryValueKind.xml @@ -28,12 +28,12 @@ ## Remarks The enumeration defines the set of supported registry data types and the value that is used for unsupported types (Unknown). Starting in the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you can specify not to use a data type with the None value. - Use the method to determine the data type of a registry key value before retrieving the value. When you set a registry key value, use the method to specify the registry data type explicitly. + Use the method to determine the data type of a registry key value before retrieving the value. When you set a registry key value, use the method to specify the registry data type explicitly. ## Examples - The following code example creates a registry key and sets several values for that key, using to specify the registry data types. The example then uses to check the registry data types, in order to retrieve the values and display them. + The following code example creates a registry key and sets several values for that key, using to specify the registry data types. The example then uses to check the registry data types, in order to retrieve the values and display them. [!code-cpp[Microsoft.Win32.RegistryValueKind#1](~/samples/snippets/cpp/VS_Snippets_CLR/Microsoft.Win32.RegistryValueKind/CPP/source.cpp#1)] [!code-csharp[Microsoft.Win32.RegistryValueKind#1](~/samples/snippets/csharp/VS_Snippets_CLR/Microsoft.Win32.RegistryValueKind/CS/source.cs#1)] diff --git a/xml/Microsoft.Win32/RegistryValueOptions.xml b/xml/Microsoft.Win32/RegistryValueOptions.xml index fcbde93cc7bf0..004b741ad4b17 100644 --- a/xml/Microsoft.Win32/RegistryValueOptions.xml +++ b/xml/Microsoft.Win32/RegistryValueOptions.xml @@ -26,7 +26,7 @@ method overload. + Use the DoNotExpandEnvironmentNames flag with the method overload. diff --git a/xml/Microsoft.Win32/SystemEvents.xml b/xml/Microsoft.Win32/SystemEvents.xml index 7c4bb87aec89f..6c81cdaa4d7b8 100644 --- a/xml/Microsoft.Win32/SystemEvents.xml +++ b/xml/Microsoft.Win32/SystemEvents.xml @@ -49,7 +49,7 @@ The service in this example starts a thread that runs an instance of `HiddenForm`. The events are hooked up and handled in the form. The events must be hooked up in the load event of the form, to make sure that the form is completely loaded first; otherwise the events will not be raised. > [!NOTE] -> The example provides all the necessary code, including the form initialization code typically generated by [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] designers. If you are developing your service in [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)], you can omit the second partial class and use the **Properties** window to set the height and width of the hidden form to zero, the border style to , and the window state to . +> The example provides all the necessary code, including the form initialization code typically generated by [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] designers. If you are developing your service in [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)], you can omit the second partial class and use the **Properties** window to set the height and width of the hidden form to zero, the border style to , and the window state to . To run the example: diff --git a/xml/System.Activities.Statements/Interop.xml b/xml/System.Activities.Statements/Interop.xml index 00c12d07400e0..2c488f006197e 100644 --- a/xml/System.Activities.Statements/Interop.xml +++ b/xml/System.Activities.Statements/Interop.xml @@ -121,7 +121,7 @@ . + This type must derive from . ]]> diff --git a/xml/System.Activities/OutArgument`1.xml b/xml/System.Activities/OutArgument`1.xml index 66dd6239bf12f..9f5687ec96530 100644 --- a/xml/System.Activities/OutArgument`1.xml +++ b/xml/System.Activities/OutArgument`1.xml @@ -38,7 +38,7 @@ The `Divide` activity uses arguments to receive the input values and to provide the computed result values. The `Remainder` is used to pass out the remainder of the division, and the output argument provided by derived activities is used to pass out the quotient. > [!NOTE] -> If your custom activity is derived from the generic with an as its generic type argument, when you invoke the activity with the Invoke method, it returns an value. In Addition, the method will return an value instead of `void` and you do not need to set a return value. +> If your custom activity is derived from the generic with an as its generic type argument, when you invoke the activity with the Invoke method, it returns an value. In Addition, the method will return an value instead of `void` and you do not need to set a return value. [!code-csharp[CFX_WorkflowApplicationExample#120](~/samples/snippets/csharp/VS_Snippets_CFX/cfx_workflowapplicationexample/cs/program.cs#120)] diff --git a/xml/System.Activities/OverloadGroupAttribute.xml b/xml/System.Activities/OverloadGroupAttribute.xml index 536c513200904..ecc47a776abce 100644 --- a/xml/System.Activities/OverloadGroupAttribute.xml +++ b/xml/System.Activities/OverloadGroupAttribute.xml @@ -27,7 +27,7 @@ Any violation of the preceding rules results in a being thrown when the containing activity is prepared for execution. - The is set to `true` if the is applied to an argument. + The is set to `true` if the is applied to an argument. ]]> diff --git a/xml/System.Activities/RuntimeArgument.xml b/xml/System.Activities/RuntimeArgument.xml index 4605f741549ad..ba8d875e537a5 100644 --- a/xml/System.Activities/RuntimeArgument.xml +++ b/xml/System.Activities/RuntimeArgument.xml @@ -116,7 +116,7 @@ ## Remarks Required arguments that are unbound result in validation errors that are displayed at design time. - The is set to `true` if the is applied to an argument. + The is set to `true` if the is applied to an argument. Overload groups can be set on arguments through the . diff --git a/xml/System.Activities/WorkflowDataContext.xml b/xml/System.Activities/WorkflowDataContext.xml index d04dc30583c44..995bb8f88299a 100644 --- a/xml/System.Activities/WorkflowDataContext.xml +++ b/xml/System.Activities/WorkflowDataContext.xml @@ -77,7 +77,7 @@ event can indicate all properties on the object have changed by using either `null` (`Nothing` in Visual Basic) or as the property name in the . [!INCLUDE[crdefault](~/includes/crdefault-md.md)]. + The event can indicate all properties on the object have changed by using either `null` (`Nothing` in Visual Basic) or as the property name in the . [!INCLUDE[crdefault](~/includes/crdefault-md.md)]. ]]> diff --git a/xml/System.AddIn.Contract.Automation/IRemoteMethodInfoContract.xml b/xml/System.AddIn.Contract.Automation/IRemoteMethodInfoContract.xml index da2fc1500f375..d4ea8594f315e 100644 --- a/xml/System.AddIn.Contract.Automation/IRemoteMethodInfoContract.xml +++ b/xml/System.AddIn.Contract.Automation/IRemoteMethodInfoContract.xml @@ -80,7 +80,7 @@ returns a default in which the property is set to the value and the property is set to the value . + If the invoked method does not have a return value (for example, the method is a constructor), returns a default in which the property is set to the value and the property is set to the value . ]]> diff --git a/xml/System.AddIn.Contract.Automation/RemoteTypeData.xml b/xml/System.AddIn.Contract.Automation/RemoteTypeData.xml index 8ba9140330976..e3838b4c6356a 100644 --- a/xml/System.AddIn.Contract.Automation/RemoteTypeData.xml +++ b/xml/System.AddIn.Contract.Automation/RemoteTypeData.xml @@ -81,7 +81,7 @@ property. + The assembly-qualified name of a type includes the name of the assembly from which the type was loaded. For more information about the format of an assembly-qualified name, see the property. ]]> @@ -259,7 +259,7 @@ , the value of this field is . + If the remote type is an , the value of this field is . ]]> diff --git a/xml/System.AddIn.Contract/RemoteArgument.xml b/xml/System.AddIn.Contract/RemoteArgument.xml index 1f2082870ac14..ce2ebe4641e44 100644 --- a/xml/System.AddIn.Contract/RemoteArgument.xml +++ b/xml/System.AddIn.Contract/RemoteArgument.xml @@ -20,7 +20,7 @@ You can use to pass the following types and values as remote arguments: -- . +- . - . @@ -28,11 +28,11 @@ - Arrays that contain elements of intrinsic data types. - An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . provides constructors for each of the types that it supports. You can also use the methods to create objects. The methods automatically call the appropriate constructor for your argument type. - If you create a using the default parameterless constructor, the property is set to the value and the property is set to the value . + If you create a using the default parameterless constructor, the property is set to the value and the property is set to the value . ]]> @@ -57,7 +57,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -110,7 +110,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -135,7 +135,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -160,7 +160,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -185,7 +185,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -210,7 +210,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -235,7 +235,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -260,7 +260,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -285,7 +285,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -310,7 +310,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -335,7 +335,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -365,7 +365,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -390,7 +390,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -415,7 +415,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -445,7 +445,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -475,7 +475,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -505,7 +505,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -533,7 +533,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -562,7 +562,7 @@ ## Remarks This constructor assigns the default value of the data type specified by the `typeCode` parameter to the . - An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> @@ -631,7 +631,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -659,7 +659,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -687,7 +687,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -715,7 +715,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -743,7 +743,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -771,7 +771,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -799,7 +799,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -827,7 +827,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -855,7 +855,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -883,7 +883,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -916,7 +916,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -944,7 +944,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -972,7 +972,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1005,7 +1005,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1038,7 +1038,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1071,7 +1071,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1103,7 +1103,7 @@ ## Remarks This constructor assigns the default value of the data type specified by the `typeCode` parameter to the . - An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> @@ -1377,7 +1377,7 @@ ## Remarks This method calls the constructor that applies to the type of the `value` parameter. - You cannot use this method to create a that represents a `null` array that contains elements of intrinsic data types. An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + You cannot use this method to create a that represents a `null` array that contains elements of intrinsic data types. An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> @@ -1649,7 +1649,7 @@ property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> diff --git a/xml/System.AddIn.Contract/RemoteArgumentKind.xml b/xml/System.AddIn.Contract/RemoteArgumentKind.xml index 7263452e7aba0..d386cfccedb84 100644 --- a/xml/System.AddIn.Contract/RemoteArgumentKind.xml +++ b/xml/System.AddIn.Contract/RemoteArgumentKind.xml @@ -15,9 +15,9 @@ enumeration is used by the property. + The enumeration is used by the property. - An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> diff --git a/xml/System.AddIn.Contract/SerializableObjectData.xml b/xml/System.AddIn.Contract/SerializableObjectData.xml index 3934b1a719856..746e28c6a567c 100644 --- a/xml/System.AddIn.Contract/SerializableObjectData.xml +++ b/xml/System.AddIn.Contract/SerializableObjectData.xml @@ -194,7 +194,7 @@ can use the class. + To create an object ID, implementations of can use the class. ]]> diff --git a/xml/System.AddIn.Hosting/AddInEnvironment.xml b/xml/System.AddIn.Hosting/AddInEnvironment.xml index 4fe60bd55ac2a..20982b4e9a128 100644 --- a/xml/System.AddIn.Hosting/AddInEnvironment.xml +++ b/xml/System.AddIn.Hosting/AddInEnvironment.xml @@ -87,7 +87,7 @@ Pass the object obtained with this property to the appropriate method overload. - If you want to activate them in the same domain in an external process you should pass the object directly to the method overload. + If you want to activate them in the same domain in an external process you should pass the object directly to the method overload. ]]> diff --git a/xml/System.AddIn.Hosting/AddInProcess.xml b/xml/System.AddIn.Hosting/AddInProcess.xml index 8663ee22561dc..20042a8de76ce 100644 --- a/xml/System.AddIn.Hosting/AddInProcess.xml +++ b/xml/System.AddIn.Hosting/AddInProcess.xml @@ -16,7 +16,7 @@ object to the appropriate method overload. + To activate an add-in in an external process, pass an object to the appropriate method overload. The executable that runs the add-in is obtained from one of two files installed with the .NET Framework under the Windows directory. By default, the executable that matches the bits-per-word of the host application is used. If the host is a 64-bit process, AddInProcess.exe is run; otherwise, AddInProcess32.exe is run. To specify the way the executable is selected, use the constructor to create the object. @@ -53,7 +53,7 @@ constructor with the flag, to specify that the process that runs the add-in will have the same bits-per-word as the host process. + This constructor has the same effect as using the constructor with the flag, to specify that the process that runs the add-in will have the same bits-per-word as the host process. ]]> @@ -126,7 +126,7 @@ If the value of this property is `true`, the add-in is running in-process with the host application. In that case, using the or method throws an . > [!NOTE] -> The property returns an object that represents the host application process if the add-in is running in-process. +> The property returns an object that represents the host application process if the add-in is running in-process. diff --git a/xml/System.AddIn.Hosting/AddInToken.xml b/xml/System.AddIn.Hosting/AddInToken.xml index 29734235079fd..f354236051c82 100644 --- a/xml/System.AddIn.Hosting/AddInToken.xml +++ b/xml/System.AddIn.Hosting/AddInToken.xml @@ -22,7 +22,7 @@ ## Remarks An object represents an add-in, and its associated pipeline segments, that can be activated. The token contains the name, assembly name, description, publisher, and version of the add-in that it represents. - Use the method to get a collection of tokens that represent add-ins whose pipelines match a specified host view. Use the method to get a collection of tokens that represent all the pipelines for a specified add-in that match a specified host view. + Use the method to get a collection of tokens that represent add-ins whose pipelines match a specified host view. Use the method to get a collection of tokens that represent all the pipelines for a specified add-in that match a specified host view. To activate an add-in, pass the token that represents the desired add-in to the method. This method returns an instance of the type that represents the host view of the add-in. @@ -360,7 +360,7 @@ property. This value is always available on an instance of an object. + This property obtains the full name of the add-in as it would be returned by the property. This value is always available on an instance of an object. @@ -393,7 +393,7 @@ property. This value is always available on an instance of an object. + This property obtains the display name of the assembly that contains the add-in, as it would be returned by the property. This value is always available on an instance of an object. @@ -524,7 +524,7 @@ Use the enumerator returned by this method to iterate through the qualification data items of the pipeline segments associated with the current token. Each item of qualification data is a structure that identifies the pipeline segment and contains a name/value pair from a attribute applied to that segment. > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . Alternatively, you can use the property to get a nested set of dictionaries that contain the qualification data of the pipeline segments. @@ -651,7 +651,7 @@ The keys and values of these inner dictionaries are the names and values specified in the attributes for the segments. If no qualification data has been applied to a segment, its dictionary is empty. > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, the dictionary for is always empty. +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, the dictionary for is always empty. Alternatively, you can obtain qualification data by enumerating an as if it were a collection of structures, using a `foreach` statement (`For Each` in Visual Basic, `for each` in Visual C++). See the example provided for the structure. @@ -692,7 +692,7 @@ Use the enumerator returned by this method to iterate through the qualification data items of the pipeline segments associated with the current token. Each item of qualification data is a structure that identifies the pipeline segment and contains the name/value pair from a attribute applied to that segment. > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . Alternatively, you can use the property to get a nested set of dictionaries containing the qualification data of the pipeline segments. diff --git a/xml/System.AddIn.Hosting/PipelineStoreLocation.xml b/xml/System.AddIn.Hosting/PipelineStoreLocation.xml index 69cbb296d703e..483ad1a3bb240 100644 --- a/xml/System.AddIn.Hosting/PipelineStoreLocation.xml +++ b/xml/System.AddIn.Hosting/PipelineStoreLocation.xml @@ -19,7 +19,7 @@ The methods in the class that use this enumeration enable partially trusted hosts, which may not have permission to discover their own location, to find and activate add-ins in their own directory. - You can use the and method overloads to specify a location for updating or rebuilding the pipeline store, and the method overload to specify a location for finding add-ins. + You can use the and method overloads to specify a location for updating or rebuilding the pipeline store, and the method overload to specify a location for finding add-ins. diff --git a/xml/System.AddIn.Hosting/QualificationDataItem.xml b/xml/System.AddIn.Hosting/QualificationDataItem.xml index 3f0c59e0de501..26f2fbe964d14 100644 --- a/xml/System.AddIn.Hosting/QualificationDataItem.xml +++ b/xml/System.AddIn.Hosting/QualificationDataItem.xml @@ -18,9 +18,9 @@ ## Remarks Each item of qualification data consists of a name/value pair that was applied to a pipeline segment by using the attribute, to provide information that qualifies the use of the segment (for example, the recommended isolation level for the segment). The structure contains one name/value pair and the type of pipeline segment it was applied to. - Use the property to get a nested set of dictionaries that contains structures for the pipeline segments associated with an . + Use the property to get a nested set of dictionaries that contains structures for the pipeline segments associated with an . - Alternatively, use the method to get an enumerator for the structures of the pipeline segments associated with a token, or simply use a `foreach` statement (`For Each` in Visual Basic, `for each` in Visual C++) to treat the token as if it were a collection of structures. + Alternatively, use the method to get an enumerator for the structures of the pipeline segments associated with a token, or simply use a `foreach` statement (`For Each` in Visual Basic, `for each` in Visual C++) to treat the token as if it were a collection of structures. diff --git a/xml/System.AddIn.Pipeline/ContractHandle.xml b/xml/System.AddIn.Pipeline/ContractHandle.xml index 178903ada8024..5d3ac7ab4ad84 100644 --- a/xml/System.AddIn.Pipeline/ContractHandle.xml +++ b/xml/System.AddIn.Pipeline/ContractHandle.xml @@ -197,7 +197,7 @@ . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. When called by the garbage collector, this method calls the method. diff --git a/xml/System.CodeDom.Compiler/CodeDomProvider.xml b/xml/System.CodeDom.Compiler/CodeDomProvider.xml index 1ea9dde02df00..2fbe8ea98c071 100644 --- a/xml/System.CodeDom.Compiler/CodeDomProvider.xml +++ b/xml/System.CodeDom.Compiler/CodeDomProvider.xml @@ -475,13 +475,13 @@ > [!NOTE] > This method is most commonly used to create an instance of a code provider in an application that may optionally use one of several providers. allows you to specify at run time the code provider you wish to instantiate. If you know at design time which code provider is to be used, you should create an instance of that code provider rather than use the method. - The method returns a instance for a specific language name; it is similar to calling the method with the language provider type. Use when you want to dynamically find a configured provider implementation for a language name. + The method returns a instance for a specific language name; it is similar to calling the method with the language provider type. Use when you want to dynamically find a configured provider implementation for a language name. If more than one provider implementation is configured for the language name, returns a provider instance for the last matching configuration element. - Use the method overload when you want a specific language provider implementation. For example, use the method to get a provider instance that supports the language name `"CSharp"`; use the method overload to get a provider instance specifically for the implementation. You should use the [\], CultureInfo, Object\ method if you have multiple code providers for a language and you desire to instantiate a specific code provider. + Use the method overload when you want a specific language provider implementation. For example, use the method to get a provider instance that supports the language name `"CSharp"`; use the method overload to get a provider instance specifically for the implementation. You should use the [\], CultureInfo, Object\ method if you have multiple code providers for a language and you desire to instantiate a specific code provider. - The method checks whether at least one provider implementation supports a specific language. You can validate a language name using before passing it to . If you pass an unsupported language name to a is thrown. + The method checks whether at least one provider implementation supports a specific language. You can validate a language name using before passing it to . If you pass an unsupported language name to a is thrown. The method can be used to determine all implementations on a computer, including additional implementations provided by developers and compiler vendors that are identified in the [<system.codedom> Element](~/docs/framework/configure-apps/file-schema/compiler/system-codedom-element.md) in the machine configuration file (Machine.config). @@ -628,7 +628,7 @@ ## Examples - The following code example creates an instance of . The example displays the provider name, hash code and default file name extension for the new provider instance. + The following code example creates an instance of . The example displays the provider name, hash code and default file name extension for the new provider instance. [!code-cpp[CodeDom_CompilerInfo#3](~/samples/snippets/cpp/VS_Snippets_CLR/CodeDom_CompilerInfo/CPP/source.cpp#3)] [!code-csharp[CodeDom_CompilerInfo#3](~/samples/snippets/csharp/VS_Snippets_CLR/CodeDom_CompilerInfo/CS/source.cs#3)] @@ -761,7 +761,7 @@ . See for documentation describing an implementation of this method. + The base class implementation throws a . See for documentation describing an implementation of this method. @@ -985,7 +985,7 @@ ## Remarks The [<system.codedom> Element](~/docs/framework/configure-apps/file-schema/compiler/system-codedom-element.md) in the machine configuration file contains the language provider and compiler configuration settings for each implementation on the computer. For information about machine configuration files, see the Machine Configuration Files section in [Configuring Apps](http://msdn.microsoft.com/library/86bd26d3-737e-4484-9782-19b17f34cd1f). The method searches each provider configuration element for the specified language name. The returned instance contains the configured language provider and compiler settings. - The method checks whether at least one provider implementation supports a specific language. You can validate a language name using before passing it to . This prevents throwing a when you access the instance for an unsupported language name. + The method checks whether at least one provider implementation supports a specific language. You can validate a language name using before passing it to . This prevents throwing a when you access the instance for an unsupported language name. If more than one provider implementation is configured for the input language name, returns the settings from the last matching provider configuration element. @@ -1075,7 +1075,7 @@ ## Remarks The [<system.codedom> Element](~/docs/framework/configure-apps/file-schema/compiler/system-codedom-element.md) in the machine configuration file (Machine.config) contains the language provider and compiler configuration settings for each implementation on the computer. The method searches each provider configuration element for the specified file name extension. - The method checks whether at least one provider implementation supports a specific file name extension. You can validate a file name extension using before passing it to . This prevents from throwing a for an unsupported file name extension. + The method checks whether at least one provider implementation supports a specific file name extension. You can validate a file name extension using before passing it to . This prevents from throwing a for an unsupported file name extension. If a provider implementation supports the input file name extension, and there are multiple supported languages configured for that provider, then returns the first language name for that provider. If more than one provider implementation is configured for the input file name extension, returns the language name from the last matching provider configuration element. diff --git a/xml/System.CodeDom.Compiler/CompilerInfo.xml b/xml/System.CodeDom.Compiler/CompilerInfo.xml index 3de0405bfd26c..dbc5d657f2998 100644 --- a/xml/System.CodeDom.Compiler/CompilerInfo.xml +++ b/xml/System.CodeDom.Compiler/CompilerInfo.xml @@ -116,11 +116,11 @@ method to examine the compiler settings of the instances returned by the and methods. + Use the method to examine the compiler settings of the instances returned by the and methods. - The [<system.codedom> Element](~/docs/framework/configure-apps/file-schema/compiler/system-codedom-element.md) in the machine configuration file contains the language provider and compiler configuration settings for each implementation on the computer. Each language provider configuration element can contain optional `compilerOptions` and `warningLevel` attributes. These attributes define the default values for the and properties. + The [<system.codedom> Element](~/docs/framework/configure-apps/file-schema/compiler/system-codedom-element.md) in the machine configuration file contains the language provider and compiler configuration settings for each implementation on the computer. Each language provider configuration element can contain optional `compilerOptions` and `warningLevel` attributes. These attributes define the default values for the and properties. - If the language provider configuration element does not define the `compilerOptions` attribute, the property value is an empty string (""). If the language provider configuration element does not define the `warningLevel` attribute, the property value is –1. + If the language provider configuration element does not define the `compilerOptions` attribute, the property value is an empty string (""). If the language provider configuration element does not define the `warningLevel` attribute, the property value is –1. @@ -162,7 +162,7 @@ ## Remarks The method returns a instance for the current language provider settings. - Use the method to get a implementation for a instance returned by the or method. + Use the method to get a implementation for a instance returned by the or method. @@ -207,7 +207,7 @@ ## Remarks The method returns a instance for the current language provider settings and the specified provider options. For information about supported provider options, see the specific CodeDOM provider documentation. - Use the method to get a implementation for a instance returned by the or method. + Use the method to get a implementation for a instance returned by the or method. ]]> @@ -244,7 +244,7 @@ method. + This method overrides the method. The two instances are considered equal if the values of the following properties are equal: @@ -281,7 +281,7 @@ implementation on the computer. Each configured language provider supports one or more file name extensions. For example, a might support the file name extensions ".cs" and ".c#". + The [<system.codedom> Element](~/docs/framework/configure-apps/file-schema/compiler/system-codedom-element.md) in the machine configuration file contains the language provider and compiler configuration settings for each implementation on the computer. Each configured language provider supports one or more file name extensions. For example, a might support the file name extensions ".cs" and ".c#". @@ -321,14 +321,14 @@ method. + This method overrides the method. This method generates the same hash code for two objects that are equal according to the method. ## Examples - The following code example creates an instance of the class. The example displays the provider name, hash code, and default file name extension for the new provider instance. This code example is part of a larger example provided for the class. + The following code example creates an instance of the class. The example displays the provider name, hash code, and default file name extension for the new provider instance. This code example is part of a larger example provided for the class. [!code-cpp[CodeDom_CompilerInfo#3](~/samples/snippets/cpp/VS_Snippets_CLR/CodeDom_CompilerInfo/CPP/source.cpp#3)] [!code-csharp[CodeDom_CompilerInfo#3](~/samples/snippets/csharp/VS_Snippets_CLR/CodeDom_CompilerInfo/CS/source.cs#3)] @@ -363,7 +363,7 @@ implementation on the computer. Each configured language provider supports one or more language names. For example, the object for a might return an array with the language names "c#", "cs", and "csharp". + The [<system.codedom> Element](~/docs/framework/configure-apps/file-schema/compiler/system-codedom-element.md) in the machine configuration file contains the language provider and compiler configuration settings for each implementation on the computer. Each configured language provider supports one or more language names. For example, the object for a might return an array with the language names "c#", "cs", and "csharp". diff --git a/xml/System.CodeDom.Compiler/CompilerParameters.xml b/xml/System.CodeDom.Compiler/CompilerParameters.xml index 339d374f63f0d..804e252028333 100644 --- a/xml/System.CodeDom.Compiler/CompilerParameters.xml +++ b/xml/System.CodeDom.Compiler/CompilerParameters.xml @@ -218,7 +218,7 @@ property. + If the value of this property is an empty string or `null`, the compiler uses the default core assembly. Depending on the compiler version, the default core assembly may be mscorlib.dll or System.Runtime.dll in a Framework directory or reference assembly directory. If the value of this property is not empty, the Code Document Object Model (CodeDOM) explicitly references the specified assembly and emits compiler options that cause the compiler to not reference any assemblies implicitly during compilation.. For compilers that reference the core or standard assembly only implicitly by default, this property can be used on its own. For compilers that implicitly reference assemblies in addition to the core or standard assembly, using this option may require specifying additional entries in the property. > [!NOTE] > An or implementation may choose to ignore this property. diff --git a/xml/System.CodeDom.Compiler/TempFileCollection.xml b/xml/System.CodeDom.Compiler/TempFileCollection.xml index 2ef3d70cab5d8..0438b887e938e 100644 --- a/xml/System.CodeDom.Compiler/TempFileCollection.xml +++ b/xml/System.CodeDom.Compiler/TempFileCollection.xml @@ -423,9 +423,9 @@ and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. + This method overrides and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. - Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). diff --git a/xml/System.CodeDom/CodeTryCatchFinallyStatement.xml b/xml/System.CodeDom/CodeTryCatchFinallyStatement.xml index 356aa43f68e9b..e40bc5962a9f0 100644 --- a/xml/System.CodeDom/CodeTryCatchFinallyStatement.xml +++ b/xml/System.CodeDom/CodeTryCatchFinallyStatement.xml @@ -33,7 +33,7 @@ The property contains the statements to execute within a `try` block. The property contains the `catch` clauses to handle caught exceptions. The property contains the statements to execute within a `finally` block. > [!NOTE] -> Not all languages support `try`/`catch` blocks. Call the method with the flag to determine whether a code generator supports `try`/`catch` blocks. +> Not all languages support `try`/`catch` blocks. Call the method with the flag to determine whether a code generator supports `try`/`catch` blocks. diff --git a/xml/System.CodeDom/CodeTypeReference.xml b/xml/System.CodeDom/CodeTypeReference.xml index c90b6830c145e..a6ce7991dbd5e 100644 --- a/xml/System.CodeDom/CodeTypeReference.xml +++ b/xml/System.CodeDom/CodeTypeReference.xml @@ -28,7 +28,7 @@ object is used to represent a type for CodeDOM objects. When CodeDOM types have a `Type` property, it is of type . For example, the property is a that represents a field's data type. + A object is used to represent a type for CodeDOM objects. When CodeDOM types have a `Type` property, it is of type . For example, the property is a that represents a field's data type. A can be initialized with a object or a string. It is generally recommended to use a to do this, although it may not always be possible. If initializing an instance of this class with a string, it is strongly recommended to always use fully qualified types, such as "System.Console" instead of just "Console", because not all languages support importing namespaces. Array types can be specified by either passing in a type object for an array or using one of the constructors that accept rank as a parameter. diff --git a/xml/System.Collections.Concurrent/BlockingCollection`1.xml b/xml/System.Collections.Concurrent/BlockingCollection`1.xml index e31ebf45feebf..8aefc8d8539cd 100644 --- a/xml/System.Collections.Concurrent/BlockingCollection`1.xml +++ b/xml/System.Collections.Concurrent/BlockingCollection`1.xml @@ -722,7 +722,7 @@ or a PLINQ query. The enumerator will continue to provide items (if any exist) until returns true, and if is false the loop blocks until an item becomes available or until the is cancelled. + This method enables client code to remove items from the collection by using a foreach loop (For Each in Visual Basic), or or a PLINQ query. The enumerator will continue to provide items (if any exist) until returns true, and if is false the loop blocks until an item becomes available or until the is cancelled. ]]> @@ -821,7 +821,7 @@ , returns a standard enumerator that does not modify the underlying collection. If other threads are adding or removing elements concurrently when GetEnumerator is called, then the elements returned by the enumerator might not represent the current state of the collection. + Unlike , returns a standard enumerator that does not modify the underlying collection. If other threads are adding or removing elements concurrently when GetEnumerator is called, then the elements returned by the enumerator might not represent the current state of the collection. ]]> @@ -1804,7 +1804,7 @@ ## Examples - The following example shows how to use the method: + The following example shows how to use the method: [!code-csharp[System.Collections.Concurrent.BlockingCollection#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.concurrent.blockingcollection/cs/blockingcoll.cs#3)] [!code-vb[System.Collections.Concurrent.BlockingCollection#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.concurrent.blockingcollection/vb/blockingcoll.vb#3)] diff --git a/xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml b/xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml index 39c94fd877c89..7dfd3332a5a51 100644 --- a/xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml +++ b/xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml @@ -68,7 +68,7 @@ > [!NOTE] > implements the and interfaces starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)]; in previous versions of the .NET Framework, the class did not implement these interfaces. - Like the class, implements the interface. In addition, provides several methods for adding or updating key/value pairs in the dictionary, as described in the following table. + Like the class, implements the interface. In addition, provides several methods for adding or updating key/value pairs in the dictionary, as described in the following table. |To do this|Use this method|Usage notes| |----------------|---------------------|-----------------| @@ -581,7 +581,7 @@ at the moment when the property was accessed. + This property has snapshot semantics and represents the number of items in the at the moment when the property was accessed. ]]> @@ -1660,7 +1660,7 @@ ## Examples - The following example shows how to call the method: + The following example shows how to call the method: [!code-csharp[System.Collections.Concurrent.ConcurrentDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.concurrent.concurrentdictionary/cs/concdictionary.cs#2)] [!code-vb[System.Collections.Concurrent.ConcurrentDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.concurrent.concurrentdictionary/vb/concdictionary.vb#2)] @@ -1747,7 +1747,7 @@ method: + The following example shows how to call the method: [!code-csharp[System.Collections.Concurrent.ConcurrentDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.concurrent.concurrentdictionary/cs/concdictionary.cs#2)] [!code-vb[System.Collections.Concurrent.ConcurrentDictionary#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.concurrent.concurrentdictionary/vb/concdictionary.vb#2)] diff --git a/xml/System.Collections.Concurrent/EnumerablePartitionerOptions.xml b/xml/System.Collections.Concurrent/EnumerablePartitionerOptions.xml index cbc9a7d8ecc81..1abad7b0719d8 100644 --- a/xml/System.Collections.Concurrent/EnumerablePartitionerOptions.xml +++ b/xml/System.Collections.Concurrent/EnumerablePartitionerOptions.xml @@ -31,7 +31,7 @@ implementation is fast and non-blocking. These behaviors can be overridden by this enumeration by using the method. + Out-of-the-box partitioners are created with a set of default behaviors. For example, by default, some form of buffering and chunking will be used to achieve optimal performance in the common scenario where an implementation is fast and non-blocking. These behaviors can be overridden by this enumeration by using the method. ]]> diff --git a/xml/System.Collections.Concurrent/IProducerConsumerCollection`1.xml b/xml/System.Collections.Concurrent/IProducerConsumerCollection`1.xml index 0e6e83891c9cb..a633eec1934b8 100644 --- a/xml/System.Collections.Concurrent/IProducerConsumerCollection`1.xml +++ b/xml/System.Collections.Concurrent/IProducerConsumerCollection`1.xml @@ -40,7 +40,7 @@ ## Examples - The following example shows a stack data structure that implements . + The following example shows a stack data structure that implements . [!code-csharp[System.Collections.Concurrent.IProducerConsumerCollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.concurrent.iproducerconsumercollection/cs/iprodcon.cs#1)] [!code-vb[System.Collections.Concurrent.IProducerConsumerCollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.concurrent.iproducerconsumercollection/vb/iprodcon.vb#1)] diff --git a/xml/System.Collections.Concurrent/OrderablePartitioner`1.xml b/xml/System.Collections.Concurrent/OrderablePartitioner`1.xml index d0b1e94adf01d..6b3459e911d10 100644 --- a/xml/System.Collections.Concurrent/OrderablePartitioner`1.xml +++ b/xml/System.Collections.Concurrent/OrderablePartitioner`1.xml @@ -120,7 +120,7 @@ interface. Calling on the object creates another partition over the sequence. + The returned object implements the interface. Calling on the object creates another partition over the sequence. The default implementation provides the same behavior as except that the returned set of partitions does not provide the keys for the elements. @@ -164,7 +164,7 @@ interface. Calling on the object creates another partition over the sequence. + The returned object implements the interface. Calling on the object creates another partition over the sequence. Each partition is represented as an enumerator over key-value pairs. The value in the pair is the element itself, and the key is an integer which determines the relative ordering of this element against other elements. diff --git a/xml/System.Collections.Concurrent/Partitioner`1.xml b/xml/System.Collections.Concurrent/Partitioner`1.xml index 0399f55a31cc1..ed46e2fb12cff 100644 --- a/xml/System.Collections.Concurrent/Partitioner`1.xml +++ b/xml/System.Collections.Concurrent/Partitioner`1.xml @@ -103,7 +103,7 @@ interface. Calling on the object creates another partition over the sequence. + The returned object implements the interface. Calling on the object creates another partition over the sequence. The method is only supported if the property returns true. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md). diff --git a/xml/System.Collections.Generic/Comparer`1.xml b/xml/System.Collections.Generic/Comparer`1.xml index 8c3736c5cd2ee..697f5340d6065 100644 --- a/xml/System.Collections.Generic/Comparer`1.xml +++ b/xml/System.Collections.Generic/Comparer`1.xml @@ -40,13 +40,13 @@ ## Remarks Derive from this class to provide a custom implementation of the interface for use with collection classes such as the and generic classes. - The difference between deriving from the class and implementing the interface is as follows: + The difference between deriving from the class and implementing the interface is as follows: -- To specify how two objects should be compared by default, implement the interface in your class. This ensures that sort operations will use the default comparison code that you provided. +- To specify how two objects should be compared by default, implement the interface in your class. This ensures that sort operations will use the default comparison code that you provided. - To define a comparer to use instead of the default comparer, derive from the class. You can then use this comparer in sort operations that take a comparer as a parameter. - The object returned by the property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, the property returns a that uses the interface. + The object returned by the property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, the property returns a that uses the interface. @@ -231,7 +231,7 @@ returned by this property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, this property returns a that uses the interface. + The returned by this property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, this property returns a that uses the interface. diff --git a/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml b/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml index c8f34947cc375..84f0d9a9281ee 100644 --- a/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml +++ b/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml @@ -52,7 +52,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. ]]> @@ -97,7 +97,7 @@ returns the same object until is called. sets to the next element. If the collection is modified between and , returns the element that it is set to, even though the enumerator is invalidated. > [!NOTE] -> For better performance, this property does not throw an exception if the enumerator is positioned before the first element or after the last element. The value of the property is undefined. To get an exception instead, cast the to the interface before using it. +> For better performance, this property does not throw an exception if the enumerator is positioned before the first element or after the last element. The value of the property is undefined. To get an exception instead, cast the to the interface before using it. ]]> diff --git a/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml b/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml index 462fb74900e89..f838403ee34b7 100644 --- a/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml @@ -49,7 +49,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. ]]> @@ -130,7 +130,7 @@ method. + This method is called by the method. ]]> diff --git a/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml b/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml index 122074cda88da..5781bc6ce6f79 100644 --- a/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml +++ b/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml @@ -52,7 +52,7 @@ property returns an instance of this type, containing all the keys in that . The order of the keys in the is unspecified, but it is the same order as the associated values in the returned by the property. + The property returns an instance of this type, containing all the keys in that . The order of the keys in the is unspecified, but it is the same order as the associated values in the returned by the property. The is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . @@ -227,7 +227,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -519,7 +519,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -576,7 +576,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -618,7 +618,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -700,7 +700,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/Dictionary`2+ValueCollection+Enumerator.xml b/xml/System.Collections.Generic/Dictionary`2+ValueCollection+Enumerator.xml index bf878356eb2dc..568f0f6e95237 100644 --- a/xml/System.Collections.Generic/Dictionary`2+ValueCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/Dictionary`2+ValueCollection+Enumerator.xml @@ -49,7 +49,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. ]]> diff --git a/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml b/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml index 7babbd5930de4..0c21b4c9dad65 100644 --- a/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml +++ b/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml @@ -52,7 +52,7 @@ property returns an instance of this type, containing all the values in that . The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the property. + The property returns an instance of this type, containing all the values in that . The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the property. The is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . @@ -232,7 +232,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -524,7 +524,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -581,7 +581,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -623,7 +623,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -705,7 +705,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/Dictionary`2.xml b/xml/System.Collections.Generic/Dictionary`2.xml index 15ff09d79ac54..14dbc47362d87 100644 --- a/xml/System.Collections.Generic/Dictionary`2.xml +++ b/xml/System.Collections.Generic/Dictionary`2.xml @@ -80,7 +80,7 @@ As long as an object is used as a key in the , it must not change in any way that affects its hash value. Every key in a must be unique according to the dictionary's equality comparer. A key cannot be `null`, but a value can be, if the value type `TValue` is a reference type. - requires an equality implementation to determine whether keys are equal. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify an implementation, the default generic equality comparer is used. If type `TKey` implements the generic interface, the default equality comparer uses that implementation. + requires an equality implementation to determine whether keys are equal. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify an implementation, the default generic equality comparer is used. If type `TKey` implements the generic interface, the default equality comparer uses that implementation. > [!NOTE] > For example, you can use the case-insensitive string comparers provided by the class to create dictionaries with case-insensitive string keys. @@ -157,7 +157,7 @@ ## Remarks Every key in a must be unique according to the default equality comparer. - requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. + requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. > [!NOTE] > If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . @@ -213,7 +213,7 @@ The initial capacity of the new is large enough to contain all the elements in `dictionary`. - requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. + requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. This constructor is an O(`n`) operation, where `n` is the number of elements in `dictionary`. @@ -285,7 +285,7 @@ Every key in a must be unique according to the specified comparer. - requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. + requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. > [!NOTE] > If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . @@ -340,7 +340,7 @@ If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. + requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. This constructor is an O(1) operation. @@ -399,7 +399,7 @@ The initial capacity of the new is large enough to contain all the elements in `dictionary`. - requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. + requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. This constructor is an O(`n`) operation, where `n` is the number of elements in `dictionary`. @@ -482,7 +482,7 @@ If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. + requires an equality implementation to determine whether keys are equal. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default equality comparer uses that implementation. This constructor is an O(1) operation. @@ -665,7 +665,7 @@ requires an equality implementation to determine whether keys are equal. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify one, the default generic equality comparer is used. + requires an equality implementation to determine whether keys are equal. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify one, the default generic equality comparer is used. Getting the value of this property is an O(1) operation. @@ -768,7 +768,7 @@ for `TValue`, the type of values in the dictionary. + This method determines equality using the default equality comparer for `TValue`, the type of values in the dictionary. This method performs a linear search; therefore, the average execution time is proportional to . That is, this method is an O(`n`) operation, where `n` is . @@ -866,7 +866,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. @@ -1512,7 +1512,7 @@ Each element copied from a is a structure representing a value and its key. > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . This method is an O(`n`) operation, where `n` is . @@ -1569,7 +1569,7 @@ namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which can cause the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -1611,7 +1611,7 @@ namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1690,9 +1690,9 @@ finally { ## Examples - The following code example shows how to access the class through the interface. The code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key, or when a key or value of the wrong data type is supplied. + The following code example shows how to access the class through the interface. The code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key, or when a key or value of the wrong data type is supplied. - The code example demonstrates the use of several other members of the interface. + The code example demonstrates the use of several other members of the interface. [!code-csharp[Generic.Dictionary.IDictionary#1](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.Dictionary.IDictionary/CS/source.cs#1)] [!code-vb[Generic.Dictionary.IDictionary#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.Dictionary.IDictionary/VB/source.vb#1)] @@ -1755,7 +1755,7 @@ finally { ## Examples - The following code example shows how to use the method of the interface with a . The example demonstrates that the method returns `false` if a key of the wrong data type is supplied. + The following code example shows how to use the method of the interface with a . The example demonstrates that the method returns `false` if a key of the wrong data type is supplied. The code example is part of a larger example, including output, provided for the method. @@ -1819,14 +1819,14 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. ## Examples - The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -1968,9 +1968,9 @@ finally { ## Examples - The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. + The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. - The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. + The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. The code example is part of a larger example, including output, provided for the method. @@ -2031,7 +2031,7 @@ finally { ## Examples - The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -2086,7 +2086,7 @@ finally { ## Examples - The following code example shows how to use the of the interface with a . + The following code example shows how to use the of the interface with a . The code example is part of a larger example, including output, provided for the method. @@ -2140,7 +2140,7 @@ finally { ## Examples - The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -2207,7 +2207,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/EqualityComparer`1.xml b/xml/System.Collections.Generic/EqualityComparer`1.xml index 3b24c333cd1d9..9fbbe8047321b 100644 --- a/xml/System.Collections.Generic/EqualityComparer`1.xml +++ b/xml/System.Collections.Generic/EqualityComparer`1.xml @@ -38,11 +38,11 @@ generic interface for use with collection classes such as the generic class, or with methods such as . + Derive from this class to provide a custom implementation of the generic interface for use with collection classes such as the generic class, or with methods such as . - The property checks whether type `T` implements the generic interface and, if so, returns an that invokes the implementation of the method. Otherwise, it returns an , as provided by `T`. + The property checks whether type `T` implements the generic interface and, if so, returns an that invokes the implementation of the method. Otherwise, it returns an , as provided by `T`. - We recommend that you derive from the class instead of implementing the interface, because the class tests for equality using the method instead of the method. This is consistent with the `Contains`, `IndexOf`, `LastIndexOf`, and `Remove` methods of the class and other generic collections. + We recommend that you derive from the class instead of implementing the interface, because the class tests for equality using the method instead of the method. This is consistent with the `Contains`, `IndexOf`, `LastIndexOf`, and `Remove` methods of the class and other generic collections. @@ -114,14 +114,14 @@ property checks whether type `T` implements the interface and, if so, returns an that uses that implementation. Otherwise, it returns an that uses the overrides of and provided by `T`. + The property checks whether type `T` implements the interface and, if so, returns an that uses that implementation. Otherwise, it returns an that uses the overrides of and provided by `T`. ## Examples The following example creates two dictionary collections of type `Box`. Both dictionaries are created with the constructor that takes an as a parameter. - To determine the equality of dictionary keys, the `boxesByDim` dictionary uses an equality comparer (`BoxEqDimensions`) that uses the implementation of the method in the `Box` class. Two boxes are considered equal if their dimensions are the same. + To determine the equality of dictionary keys, the `boxesByDim` dictionary uses an equality comparer (`BoxEqDimensions`) that uses the implementation of the method in the `Box` class. Two boxes are considered equal if their dimensions are the same. The `boxesByVol` dictionary uses an equality comparer (`BoxEqVolume`) that defines equality by volume. Two boxes are considered equal if their volumes are the same. diff --git a/xml/System.Collections.Generic/HashSet`1+Enumerator.xml b/xml/System.Collections.Generic/HashSet`1+Enumerator.xml index 7eb9e0181663d..438d00f3e21ba 100644 --- a/xml/System.Collections.Generic/HashSet`1+Enumerator.xml +++ b/xml/System.Collections.Generic/HashSet`1+Enumerator.xml @@ -48,7 +48,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. ]]> @@ -93,7 +93,7 @@ returns the same object until is called. sets to the next element. If the list is modified between calling method and obtaining the contents of the property, returns the element that it is set to, even though the enumerator is invalidated. > [!NOTE] -> For better performance, this property does not throw an exception if the enumerator is positioned before the first element or after the last element. The value of the property is undefined. To get an exception instead, cast the to the interface before using it. +> For better performance, this property does not throw an exception if the enumerator is positioned before the first element or after the last element. The value of the property is undefined. To get an exception instead, cast the to the interface before using it. ]]> diff --git a/xml/System.Collections.Generic/HashSet`1.xml b/xml/System.Collections.Generic/HashSet`1.xml index e68771e389380..afbd41ea68002 100644 --- a/xml/System.Collections.Generic/HashSet`1.xml +++ b/xml/System.Collections.Generic/HashSet`1.xml @@ -888,7 +888,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. @@ -1618,7 +1618,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. @@ -1671,7 +1671,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/ICollection`1.xml b/xml/System.Collections.Generic/ICollection`1.xml index 3c59800b9878a..2ac000e9439e7 100644 --- a/xml/System.Collections.Generic/ICollection`1.xml +++ b/xml/System.Collections.Generic/ICollection`1.xml @@ -34,7 +34,7 @@ interface is the base interface for classes in the namespace. + The interface is the base interface for classes in the namespace. The interface extends ; and are more specialized interfaces that extend . A implementation is a collection of key/value pairs, like the class. A implementation is a collection of values, and its members can be accessed by index, like the class. @@ -167,7 +167,7 @@ uses , whereas allows the user to specify the implementation to use for comparing keys. + Implementations can vary in how they determine equality of objects; for example, uses , whereas allows the user to specify the implementation to use for comparing keys. ]]> @@ -321,7 +321,7 @@ uses , whereas, allows the user to specify the implementation to use for comparing keys. + Implementations can vary in how they determine equality of objects; for example, uses , whereas, allows the user to specify the implementation to use for comparing keys. In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. diff --git a/xml/System.Collections.Generic/IComparer`1.xml b/xml/System.Collections.Generic/IComparer`1.xml index d8c6e2c1a87c5..c0f7818f69b75 100644 --- a/xml/System.Collections.Generic/IComparer`1.xml +++ b/xml/System.Collections.Generic/IComparer`1.xml @@ -34,7 +34,7 @@ and methods. It provides a way to customize the sort order of a collection. Classes that implement this interface include the and generic classes. + This interface is used with the and methods. It provides a way to customize the sort order of a collection. Classes that implement this interface include the and generic classes. The default implementation of this interface is the class. The class implements this interface for type . diff --git a/xml/System.Collections.Generic/IDictionary`2.xml b/xml/System.Collections.Generic/IDictionary`2.xml index 2b95793884b2f..8ad862fe7c238 100644 --- a/xml/System.Collections.Generic/IDictionary`2.xml +++ b/xml/System.Collections.Generic/IDictionary`2.xml @@ -119,7 +119,7 @@ ## Remarks You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. Implementations can vary in whether they allow `key` to be `null`. @@ -128,7 +128,7 @@ ## Examples The following code example creates an empty of strings, with integer keys, and accesses it through the interface. The code example uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - This code is part of a larger example that can be compiled and executed. See . + This code is part of a larger example that can be compiled and executed. See . [!code-cpp[Generic.IDictionary#2](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#2)] [!code-csharp[Generic.IDictionary#2](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#2)] @@ -179,7 +179,7 @@ class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. Implementations can vary in whether they allow `key` to be `null`. @@ -188,7 +188,7 @@ ## Examples The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method, which can be a more efficient way to retrieve values if a program frequently tries key values that are not in the dictionary. Finally, it shows how to insert items using property (the indexer in C#). - This code is part of a larger example that can be compiled and executed. See . + This code is part of a larger example that can be compiled and executed. See . [!code-cpp[Generic.IDictionary#6](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#6)] [!code-csharp[Generic.IDictionary#6](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#6)] @@ -246,7 +246,7 @@ You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. The C# language uses the keyword to define the indexers instead of implementing the property. Visual Basic implements as a default property, which provides the same indexing functionality. @@ -259,7 +259,7 @@ The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. - This code is part of a larger example that can be compiled and executed. See . + This code is part of a larger example that can be compiled and executed. See . [!code-cpp[Generic.IDictionary#3](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#3)] [!code-csharp[Generic.IDictionary#3](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#3)] @@ -318,7 +318,7 @@ ## Examples The following code example shows how to enumerate keys alone using the property. - This code is part of a larger example that can be compiled and executed. See . + This code is part of a larger example that can be compiled and executed. See . [!code-cpp[Generic.IDictionary#9](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#9)] [!code-csharp[Generic.IDictionary#9](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#9)] @@ -365,14 +365,14 @@ class uses , whereas the class allows the user to specify the implementation to use for comparing keys. + Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. ## Examples The following code example shows how to remove a key/value pair from a dictionary using the method. - This code is part of a larger example that can be compiled and executed. See . + This code is part of a larger example that can be compiled and executed. See . [!code-cpp[Generic.IDictionary#10](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#10)] [!code-csharp[Generic.IDictionary#10](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#10)] @@ -433,7 +433,7 @@ ## Examples The example shows how to use the method to retrieve values. If a program frequently tries key values that are not in a dictionary, the method can be more efficient than using the property (the indexer in C#), which throws exceptions when attempting to retrieve nonexistent keys. - This code is part of a larger example that can be compiled and executed. See . + This code is part of a larger example that can be compiled and executed. See . [!code-cpp[Generic.IDictionary#5](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#5)] [!code-csharp[Generic.IDictionary#5](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#5)] @@ -487,7 +487,7 @@ ## Examples The following code example shows how to enumerate values alone using the property. - This code is part of a larger example that can be compiled and executed. See . + This code is part of a larger example that can be compiled and executed. See . [!code-cpp[Generic.IDictionary#8](~/samples/snippets/cpp/VS_Snippets_CLR/Generic.IDictionary/cpp/source.cpp#8)] [!code-csharp[Generic.IDictionary#8](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.IDictionary/CS/source.cs#8)] diff --git a/xml/System.Collections.Generic/IEnumerable`1.xml b/xml/System.Collections.Generic/IEnumerable`1.xml index 664794c980431..f77760ae9a652 100644 --- a/xml/System.Collections.Generic/IEnumerable`1.xml +++ b/xml/System.Collections.Generic/IEnumerable`1.xml @@ -42,9 +42,9 @@ > [!NOTE] > To view the .NET Framework source code for this type, see the [Reference Source](http://referencesource.microsoft.com/#mscorlib/system/collections/generic/ienumerable.cs#3acf01620172c7f0). You can browse through the source code online, download the reference for offline viewing, and step through the sources (including patches and updates) during debugging; see [instructions](http://referencesource.microsoft.com/). - is the base interface for collections in the namespace such as , , and and other generic collections such as and . Collections that implement can be enumerated by using the `foreach` statement. For the non-generic version of this interface, see . + is the base interface for collections in the namespace such as , , and and other generic collections such as and . Collections that implement can be enumerated by using the `foreach` statement. For the non-generic version of this interface, see . - For the non-generic version of this interface, see . + For the non-generic version of this interface, see . contains a single method that you must implement when implementing this interface; , which returns an object. The returned provides the ability to iterate through the collection by exposing a property. @@ -109,7 +109,7 @@ An enumerator does not have exclusive access to the collection so an enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - Default implementations of collections in the namespace aren't synchronized. + Default implementations of collections in the namespace aren't synchronized. diff --git a/xml/System.Collections.Generic/IEnumerator`1.xml b/xml/System.Collections.Generic/IEnumerator`1.xml index dd7cdcf2789f8..f3e81a322adbc 100644 --- a/xml/System.Collections.Generic/IEnumerator`1.xml +++ b/xml/System.Collections.Generic/IEnumerator`1.xml @@ -59,7 +59,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. diff --git a/xml/System.Collections.Generic/IEqualityComparer`1.xml b/xml/System.Collections.Generic/IEqualityComparer`1.xml index 3535c0109c2b7..80c7028c9bcbc 100644 --- a/xml/System.Collections.Generic/IEqualityComparer`1.xml +++ b/xml/System.Collections.Generic/IEqualityComparer`1.xml @@ -40,7 +40,7 @@ This interface supports only equality comparisons. Customization of comparisons for sorting and ordering is provided by the generic interface. - We recommend that you derive from the class instead of implementing the interface, because the class tests for equality using the method instead of the method. This is consistent with the `Contains`, `IndexOf`, `LastIndexOf`, and `Remove` methods of the class and other generic collections. + We recommend that you derive from the class instead of implementing the interface, because the class tests for equality using the method instead of the method. This is consistent with the `Contains`, `IndexOf`, `LastIndexOf`, and `Remove` methods of the class and other generic collections. diff --git a/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml b/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml index 1b3b522e782be..5f76d50d80c01 100644 --- a/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml +++ b/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml @@ -92,7 +92,7 @@ might use the property, or it might implement the method. + Implementations can vary in how they determine the equality of objects; for example, the class that implements might use the property, or it might implement the method. Implementations can vary in whether they allow `key` to be `null`. @@ -140,7 +140,7 @@ ## Remarks This property lets you access a specific element in the collection by using the following syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). - Implementations can vary in how they determine the equality of objects: for example, the class that implements might use the property, or it might implement the method. + Implementations can vary in how they determine the equality of objects: for example, the class that implements might use the property, or it might implement the method. Implementations can vary in whether they allow `key` to be `null`. diff --git a/xml/System.Collections.Generic/KeyValuePair`2.xml b/xml/System.Collections.Generic/KeyValuePair`2.xml index 71ff7fd9025e3..b84011c6a3392 100644 --- a/xml/System.Collections.Generic/KeyValuePair`2.xml +++ b/xml/System.Collections.Generic/KeyValuePair`2.xml @@ -35,7 +35,7 @@ property returns an instance of this type. + The property returns an instance of this type. The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of a collection based on is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: diff --git a/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml b/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml index 80df187f8e449..3ee214257f867 100644 --- a/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml +++ b/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml @@ -54,7 +54,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. ]]> diff --git a/xml/System.Collections.Generic/LinkedList`1.xml b/xml/System.Collections.Generic/LinkedList`1.xml index 24a49dbf389bd..014d905a2aeab 100644 --- a/xml/System.Collections.Generic/LinkedList`1.xml +++ b/xml/System.Collections.Generic/LinkedList`1.xml @@ -776,7 +776,7 @@ to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order in which the enumerator iterates through the . @@ -1021,7 +1021,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -1466,7 +1466,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -1511,7 +1511,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -1568,7 +1568,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1610,7 +1610,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1692,7 +1692,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/List`1+Enumerator.xml b/xml/System.Collections.Generic/List`1+Enumerator.xml index 4e33dd83fe25a..77f841d021e41 100644 --- a/xml/System.Collections.Generic/List`1+Enumerator.xml +++ b/xml/System.Collections.Generic/List`1+Enumerator.xml @@ -48,7 +48,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. ]]> @@ -93,7 +93,7 @@ returns the same object until is called. sets to the next element. If the list is modified between and , returns the element that it is set to, even though the enumerator is invalidated. > [!NOTE] -> For better performance, this property does not throw an exception if the enumerator is positioned before the first element or after the last element. The value of the property is undefined. To get an exception instead, cast the to the interface before using it. +> For better performance, this property does not throw an exception if the enumerator is positioned before the first element or after the last element. The value of the property is undefined. To get an exception instead, cast the to the interface before using it. ]]> diff --git a/xml/System.Collections.Generic/List`1.xml b/xml/System.Collections.Generic/List`1.xml index 50d6c8fc61c7a..a8979df382975 100644 --- a/xml/System.Collections.Generic/List`1.xml +++ b/xml/System.Collections.Generic/List`1.xml @@ -68,7 +68,7 @@ The class uses both an equality comparer and an ordering comparer. -- Methods such as , , , and use an equality comparer for the list elements. The default equality comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the equality comparer is the method of that interface; otherwise, the default equality comparer is . +- Methods such as , , , and use an equality comparer for the list elements. The default equality comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the equality comparer is the method of that interface; otherwise, the default equality comparer is . - Methods such as and use an ordering comparer for the list elements. The default comparer for type `T` is determined as follows. If type `T` implements the generic interface, then the default comparer is the method of that interface; otherwise, if type `T` implements the nongeneric interface, then the default comparer is the method of that interface. If type `T` implements neither interface, then there is no default comparer, and a comparer or comparison delegate must be provided explicitly. @@ -87,7 +87,7 @@ If a value type is used for type `T`, the compiler generates an implementation of the class specifically for that value type. That means a list element of a object does not have to be boxed before the element can be used, and after about 500 list elements are created the memory saved not boxing list elements is greater than the memory used to generate the class implementation. - Make certain the value type used for type `T` implements the generic interface. If not, methods such as must call the method, which boxes the affected list element. If the value type implements the interface and you own the source code, also implement the generic interface to prevent the and methods from boxing list elements. If you do not own the source code, pass an object to the and methods + Make certain the value type used for type `T` implements the generic interface. If not, methods such as must call the method, which boxes the affected list element. If the value type implements the interface and you own the source code, also implement the generic interface to prevent the and methods from boxing list elements. If you do not own the source code, pass an object to the and methods It is to your advantage to use the type-specific implementation of the class instead of using the class or writing a strongly typed wrapper collection yourself. The reason is your implementation must do what the .NET Framework does for you already, and the common language runtime can share Microsoft intermediate language code and metadata, which your implementation cannot. @@ -478,7 +478,7 @@ for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + This method uses the default comparer for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. @@ -550,7 +550,7 @@ If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. @@ -627,7 +627,7 @@ If `comparer` is provided, the elements of the are compared to the specified value using the specified implementation. - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws . The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. @@ -815,7 +815,7 @@ method for `T` (the type of values in the list). + This method determines equality by using the default equality comparer, as defined by the object's implementation of the method for `T` (the type of values in the list). This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -827,7 +827,7 @@ [!code-csharp[System.Collections.Generic.List.ContainsExists#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/cs/program.cs#1)] [!code-vb[System.Collections.Generic.List.ContainsExists#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.containsexists/vb/module1.vb#1)] - The following example contains a list of complex objects of type `Cube`. The `Cube` class implements the method so that two cubes are considered equal if their dimensions are the same. In this example, the method returns `true`, because a cube that has the specified dimensions is already in the collection. + The following example contains a list of complex objects of type `Cube`. The `Cube` class implements the method so that two cubes are considered equal if their dimensions are the same. In this example, the method returns `true`, because a cube that has the specified dimensions is already in the collection. [!code-csharp[System.Collections.Generic.List.Contains#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.generic.list.contains/cs/program.cs#1)] [!code-vb[System.Collections.Generic.List.Contains#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.generic.list.contains/vb/program.vb#1)] @@ -926,7 +926,7 @@ to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order in which the enumerator iterates through the . @@ -983,7 +983,7 @@ to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order in which the enumerator iterates through the . @@ -1046,7 +1046,7 @@ to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order in which the enumerator iterates through the . @@ -1940,7 +1940,7 @@ Public Function StartsWith(e As Employee) As Boolean The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. @@ -2049,7 +2049,7 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks The is searched forward starting at the first element and ending at the last element. - This method determines equality using the default equality comparer for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -2104,7 +2104,7 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks The is searched forward starting at `index` and ending at the last element. - This method determines equality using the default equality comparer for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from `index` to the end of the . @@ -2163,7 +2163,7 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks The is searched forward starting at `index` and ending at `index` plus `count` minus 1, if `count` is greater than 0. - This method determines equality using the default equality comparer for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. @@ -2426,7 +2426,7 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks The is searched backward starting at the last element and ending at the first element. - This method determines equality using the default equality comparer for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -2481,7 +2481,7 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks The is searched backward starting at `index` and ending at the first element. - This method determines equality using the default equality comparer for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is the number of elements from the beginning of the to `index`. @@ -2540,7 +2540,7 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks The is searched backward starting at `index` and ending at `index` minus `count` plus 1, if `count` is greater than 0. - This method determines equality using the default equality comparer for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is `count`. @@ -2602,7 +2602,7 @@ Public Function StartsWith(e As Employee) As Boolean generic interface, the equality comparer is the method of that interface; otherwise, the default equality comparer is . + If type `T` implements the generic interface, the equality comparer is the method of that interface; otherwise, the default equality comparer is . This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -2836,7 +2836,7 @@ Public Function StartsWith(e As Employee) As Boolean to reverse the order of the elements. + This method uses to reverse the order of the elements. This method is an O(*n*) operation, where *n* is . @@ -2888,7 +2888,7 @@ Public Function StartsWith(e As Employee) As Boolean to reverse the order of the elements. + This method uses to reverse the order of the elements. This method is an O(*n*) operation, where *n* is . @@ -2936,7 +2936,7 @@ Public Function StartsWith(e As Employee) As Boolean Sorts the elements in the entire list using the specified comparer. [List\.Sort(IComparer\ comparer)](xref:System.Collections.Generic.List%601.Sort%28System.Collections.Generic.IComparer%7B%600%7D%29) - Sorts the elements in the entire list using the specified . + Sorts the elements in the entire list using the specified . [List\.Sort(Int32 index, Int32 count, IComparer\ comparer)](xref:System.Collections.Generic.List%601.Sort%28System.Int32,System.Int32,System.Collections.Generic.IComparer%7B%600%7D%29) Sorts the elements in a range of elements in list using the specified comparer. @@ -2954,7 +2954,7 @@ Public Function StartsWith(e As Employee) As Boolean |Exception|Condition| |---------------|---------------| -||`comparer` is not specified or `null`, and the default comparer cannot find implementation of the generic interface or the interface for type T.| +||`comparer` is not specified or `null`, and the default comparer cannot find implementation of the generic interface or the interface for type T.| ||`comparison` is `null`.| ||The implementation of `comparison` or `comparer` caused an error during the sort. For example, `comparison` might not return 0 when comparing an item with itself.

-or-

`index` and `count` do not specify a valid range in the .| ||`index` is less than 0 or `count` is less than 0.| @@ -2993,9 +2993,9 @@ Public Function StartsWith(e As Employee) As Boolean for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + This method uses the default comparer for type `T` to determine the order of list elements. The property checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - This method uses the method, which applies the introspective sort as follows: + This method uses the method, which applies the introspective sort as follows: - If the partition size is fewer than 16 elements, it uses an insertion sort algorithm. @@ -3068,9 +3068,9 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks If `comparer` is provided, the elements of the are sorted using the specified implementation. - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - This method uses the method, which applies the introspective sort as follows: + This method uses the method, which applies the introspective sort as follows: - If the partition size is fewer than 16 elements, it uses an insertion sort algorithm. @@ -3141,7 +3141,7 @@ Public Function StartsWith(e As Employee) As Boolean If `comparison` is `null`, an is thrown. - This method uses , which applies the introspective sort as follows: + This method uses , which applies the introspective sort as follows: - If the partition size is fewer than 16 elements, it uses an insertion sort algorithm @@ -3217,9 +3217,9 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks If `comparer` is provided, the elements of the are sorted using the specified implementation. - If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . + If `comparer` is `null`, the default comparer checks whether type `T` implements the generic interface and uses that implementation, if available. If not, checks whether type `T` implements the interface. If type `T` does not implement either interface, throws an . - This method uses , which applies the introspective sort as follows: + This method uses , which applies the introspective sort as follows: - If the partition size is fewer than 16 elements, it uses an insertion sort algorithm @@ -3350,7 +3350,7 @@ Public Function StartsWith(e As Employee) As Boolean The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. @@ -3395,7 +3395,7 @@ Public Function StartsWith(e As Employee) As Boolean ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw , whereas the generic implementations throw . This method is an O(*n*) operation, where *n* is . @@ -3452,7 +3452,7 @@ Public Function StartsWith(e As Employee) As Boolean namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where enumeration contends with write accesses, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -3494,7 +3494,7 @@ Public Function StartsWith(e As Employee) As Boolean namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -3579,7 +3579,7 @@ finally The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. @@ -3664,7 +3664,7 @@ finally for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -3706,7 +3706,7 @@ finally for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -3923,7 +3923,7 @@ finally for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(*n*) operation, where *n* is . @@ -3964,7 +3964,7 @@ finally , which is an O(*n*) operation, where *n* is . + The elements are copied using , which is an O(*n*) operation, where *n* is . This method is an O(*n*) operation, where *n* is . diff --git a/xml/System.Collections.Generic/Queue`1+Enumerator.xml b/xml/System.Collections.Generic/Queue`1+Enumerator.xml index 5a56a4bc79f20..4bf68b93ce3ff 100644 --- a/xml/System.Collections.Generic/Queue`1+Enumerator.xml +++ b/xml/System.Collections.Generic/Queue`1+Enumerator.xml @@ -51,7 +51,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. ]]> diff --git a/xml/System.Collections.Generic/Queue`1.xml b/xml/System.Collections.Generic/Queue`1.xml index cc412808f6a62..b42437ac9edad 100644 --- a/xml/System.Collections.Generic/Queue`1.xml +++ b/xml/System.Collections.Generic/Queue`1.xml @@ -335,7 +335,7 @@ for `T`, the type of values in the queue. + This method determines equality using the default equality comparer for `T`, the type of values in the queue. This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -623,7 +623,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -750,7 +750,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -795,7 +795,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -852,7 +852,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -894,7 +894,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -976,7 +976,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/SortedDictionary`2+Enumerator.xml b/xml/System.Collections.Generic/SortedDictionary`2+Enumerator.xml index b6e53f56fd9e2..ecc6be4fb2ea2 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+Enumerator.xml @@ -58,7 +58,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. ]]> diff --git a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml index 098a7321c43f9..92743b652d73a 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml @@ -52,7 +52,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. ]]> diff --git a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml index e6e41bf54234d..51df90f843807 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml @@ -52,7 +52,7 @@ property returns an instance of this type, containing all the keys in that . The order of the keys in the is the same as the order of elements in the , the same as the order of the associated values in the returned by the property. + The property returns an instance of this type, containing all the keys in that . The order of the keys in the is the same as the order of elements in the , the same as the order of the associated values in the returned by the property. The is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . @@ -232,7 +232,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. @@ -524,7 +524,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . This method is an O(`n`) operation, where `n` is . @@ -581,7 +581,7 @@ namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -623,7 +623,7 @@ namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -708,7 +708,7 @@ finally The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection+Enumerator.xml b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection+Enumerator.xml index 8008cd5ef6b02..fb12d730f4beb 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection+Enumerator.xml @@ -52,7 +52,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. ]]> diff --git a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml index 5ab60701ac81a..f4f29ece4f770 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml @@ -52,7 +52,7 @@ property returns an instance of this type, containing all the values in that . The order of the values in the is the same as the order of the elements in the , and the same as the order of the associated keys in the returned by the property. + The property returns an instance of this type, containing all the values in that . The order of the values in the is the same as the order of the elements in the , and the same as the order of the associated keys in the returned by the property. The is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . @@ -232,7 +232,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. @@ -524,7 +524,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . This method is an O(`n`) operation, where `n` is . @@ -581,7 +581,7 @@ namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -623,7 +623,7 @@ namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -708,7 +708,7 @@ finally The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/SortedDictionary`2.xml b/xml/System.Collections.Generic/SortedDictionary`2.xml index 226df9ffce988..9cab1c5d362ac 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2.xml @@ -72,7 +72,7 @@ Keys must be immutable as long as they are used as keys in the . Every key in a must be unique. A key cannot be `null`, but a value can be, if the value type `TValue` is a reference type. - requires a comparer implementation to perform key comparisons. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify an implementation, the default genericcomparer is used. If type `TKey` implements the generic interface, the default comparer uses that implementation. + requires a comparer implementation to perform key comparisons. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter; if you do not specify an implementation, the default genericcomparer is used. If type `TKey` implements the generic interface, the default comparer uses that implementation. The `foreach` statement of the C# language (`for each` in C++, `For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . The following code shows C#, C++, and Visual Basic syntax. @@ -134,7 +134,7 @@ ## Remarks Every key in a must be unique according to the default comparer. - requires a comparer implementation to perform key comparisons. This constructor uses the default generic equality comparer . If type `TKey` implements the generic interface, the default comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. + requires a comparer implementation to perform key comparisons. This constructor uses the default generic equality comparer . If type `TKey` implements the generic interface, the default comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. This constructor is an O(1) operation. @@ -184,7 +184,7 @@ ## Remarks Every key in a must be unique according to the specified comparer. - requires a comparer implementation to perform key comparisons. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default comparer uses that implementation. + requires a comparer implementation to perform key comparisons. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default comparer uses that implementation. This constructor is an O(1) operation. @@ -232,7 +232,7 @@ ## Remarks Every key in a must be unique according to the default comparer; therefore, every key in the source `dictionary` must also be unique according to the default comparer. - requires a comparer implementation to perform key comparisons. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. + requires a comparer implementation to perform key comparisons. This constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default comparer uses that implementation. Alternatively, you can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. This constructor is an O(`n` log `n`) operation, where `n` is the number of elements in `dictionary`. @@ -286,7 +286,7 @@ ## Remarks Every key in a must be unique according to the specified comparer; therefore, every key in the source `dictionary` must also be unique according to the specified comparer. - requires a comparer implementation to perform key comparisons. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default comparer uses that implementation. + requires a comparer implementation to perform key comparisons. If `comparer` is `null`, this constructor uses the default generic equality comparer, . If type `TKey` implements the generic interface, the default comparer uses that implementation. This constructor is an O(`n` log `n`) operation, where `n` is the number of elements in `dictionary`. @@ -432,7 +432,7 @@ requires a comparer implementation to perform key comparisons. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. If you do not, the default generic equality comparer, , is used. If type `TKey` implements the generic interface, the default comparer uses that implementation. + requires a comparer implementation to perform key comparisons. You can specify an implementation of the generic interface by using a constructor that accepts a `comparer` parameter. If you do not, the default generic equality comparer, , is used. If type `TKey` implements the generic interface, the default comparer uses that implementation. Getting the value of this property is an O(1) operation. @@ -532,7 +532,7 @@ for the value type `TValue`. + This method determines equality using the default equality comparer for the value type `TValue`. This method performs a linear search; therefore, the average execution time is proportional to the property. That is, this method is an O(`n`) operation, where `n` is . @@ -577,7 +577,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -675,7 +675,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(log n) operation, where n is count. @@ -1165,7 +1165,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the nongeneric implementations of throw an , whereas the generic implementations throw an . This method is an O(`n`) operation, where `n` is . @@ -1222,7 +1222,7 @@ namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which can cause the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -1264,7 +1264,7 @@ namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1346,9 +1346,9 @@ finally ## Examples - The following code example shows how to access the class through the interface. The code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key, or when a key or value of the wrong data type is supplied. + The following code example shows how to access the class through the interface. The code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key, or when a key or value of the wrong data type is supplied. - The code example demonstrates the use of several other members of the interface. + The code example demonstrates the use of several other members of the interface. [!code-csharp[Generic.SortedDictionary.IDictionary#1](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.SortedDictionary.IDictionary/CS/source.cs#1)] [!code-vb[Generic.SortedDictionary.IDictionary#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.SortedDictionary.IDictionary/VB/source.vb#1)] @@ -1411,7 +1411,7 @@ finally ## Examples - The following code example shows how to use the method of the interface with a . The example demonstrates that the method returns `false` if a key of the wrong data type is supplied. + The following code example shows how to use the method of the interface with a . The example demonstrates that the method returns `false` if a key of the wrong data type is supplied. The code example is part of a larger example, including output, provided for the method. @@ -1475,14 +1475,14 @@ finally The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. ## Examples - The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to enumerate the key/value pairs in the dictionary by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -1624,9 +1624,9 @@ finally ## Examples - The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. + The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. - The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. + The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. The code example is part of a larger example, including output, provided for the method. @@ -1687,7 +1687,7 @@ finally ## Examples - The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -1742,7 +1742,7 @@ finally ## Examples - The following code example shows how to use the of the interface with a . + The following code example shows how to use the of the interface with a . The code example is part of a larger example, including output, provided for the method. @@ -1796,7 +1796,7 @@ finally ## Examples - The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -1860,7 +1860,7 @@ finally The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/SortedList`2.xml b/xml/System.Collections.Generic/SortedList`2.xml index b3b1f3524b55a..a9869a1872f94 100644 --- a/xml/System.Collections.Generic/SortedList`2.xml +++ b/xml/System.Collections.Generic/SortedList`2.xml @@ -80,7 +80,7 @@ Key objects must be immutable as long as they are used as keys in the . Every key in a must be unique. A key cannot be `null`, but a value can be, if the type of values in the list, `TValue`, is a reference type. - requires a comparer implementation to sort and to perform comparisons. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. + requires a comparer implementation to sort and to perform comparisons. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. The capacity can be decreased by calling or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . @@ -148,7 +148,7 @@ This constructor uses the default value for the initial capacity of the . To set the initial capacity, use the constructor. If the final size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the . - This constructor uses the default comparer for `TKey`. To specify a comparer, use the constructor. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. + This constructor uses the default comparer for `TKey`. To specify a comparer, use the constructor. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. This constructor is an O(1) operation. @@ -251,7 +251,7 @@ The capacity of the new is set to the number of elements in `dictionary`, so no resizing takes place while the list is being populated. - This constructor uses the default comparer for `TKey`. To specify a comparer, use the constructor. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. + This constructor uses the default comparer for `TKey`. To specify a comparer, use the constructor. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. If the data in `dictionary` are sorted, this constructor is an O(`n`) operation, where `n` is the number of elements in `dictionary`. Otherwise it is an O(`n`*`n`) operation. @@ -308,7 +308,7 @@ The capacity can be decreased by calling or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . - This constructor uses the default comparer for `TKey`. To specify a comparer, use the constructor. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. + This constructor uses the default comparer for `TKey`. To specify a comparer, use the constructor. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. This constructor is an O(`n`) operation, where `n` is `capacity`. @@ -713,7 +713,7 @@ for the value type `TValue`. checks whether the value type `TValue` implements and uses that implementation, if available. If not, checks whether the value type `TValue` implements . If the value type `TValue` does not implement either interface, this method uses . + This method determines equality using the default comparer for the value type `TValue`. checks whether the value type `TValue` implements and uses that implementation, if available. If not, checks whether the value type `TValue` implements . If the value type `TValue` does not implement either interface, this method uses . This method performs a linear search; therefore, the average execution time is proportional to . That is, this method is an O(`n`) operation, where `n` is . @@ -806,7 +806,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -888,7 +888,7 @@ for the value type `TValue`. checks whether the value type `TValue` implements and uses that implementation, if available. If not, checks whether the value type `TValue` implements . If the value type `TValue` does not implement either interface, this method uses . + This method determines equality using the default comparer for the value type `TValue`. checks whether the value type `TValue` implements and uses that implementation, if available. If not, checks whether the value type `TValue` implements . If the value type `TValue` does not implement either interface, this method uses . This method performs a linear search; therefore, the average execution time is proportional to . That is, this method is an O(`n`) operation, where `n` is . @@ -1458,7 +1458,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -1514,7 +1514,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1555,7 +1555,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1633,9 +1633,9 @@ finally { ## Examples - The following code example shows how to access the class through the interface. The code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key, or when a key or value of the wrong data type is supplied. + The following code example shows how to access the class through the interface. The code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key, or when a key or value of the wrong data type is supplied. - The code example demonstrates the use of several other members of the interface. + The code example demonstrates the use of several other members of the interface. [!code-csharp[Generic.SortedList.IDictionary#1](~/samples/snippets/csharp/VS_Snippets_CLR/Generic.SortedList.IDictionary/CS/source.cs#1)] [!code-vb[Generic.SortedList.IDictionary#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Generic.SortedList.IDictionary/VB/source.vb#1)] @@ -1697,7 +1697,7 @@ finally { ## Examples - The following code example shows how to use the method of the interface with a . The example demonstrates that the method returns `false` if a key of the wrong data type is supplied. + The following code example shows how to use the method of the interface with a . The example demonstrates that the method returns `false` if a key of the wrong data type is supplied. The code example is part of a larger example, including output, provided for the method. @@ -1758,14 +1758,14 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. ## Examples - The following code example shows how to enumerate the key/value pairs in the sorted list by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to enumerate the key/value pairs in the sorted list by using the `foreach` statement (`For Each` in Visual Basic, `for each` in C++), which hides the use of the enumerator. In particular, note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -1906,9 +1906,9 @@ finally { ## Examples - The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. + The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. - The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the sorted list. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the sorted list, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. + The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the sorted list. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the sorted list, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. The code example is part of a larger example, including output, provided for the method. @@ -1968,7 +1968,7 @@ finally { ## Examples - The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the sorted list; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the sorted list; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -2022,7 +2022,7 @@ finally { ## Examples - The following code example shows how to use the of the interface with a . + The following code example shows how to use the of the interface with a . The code example is part of a larger example, including output, provided for the method. @@ -2075,7 +2075,7 @@ finally { ## Examples - The following code example shows how to use the property of the interface with a , to list the values in the sorted list. The example also shows how to enumerate the key/value pairs in the sorted list; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the values in the sorted list. The example also shows how to enumerate the key/value pairs in the sorted list; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -2136,7 +2136,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml b/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml index d134ab5302d87..0ec072609cc4c 100644 --- a/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml @@ -57,7 +57,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in the namespace are not synchronized. + Default implementations of collections in the namespace are not synchronized. ]]> diff --git a/xml/System.Collections.Generic/SortedSet`1.xml b/xml/System.Collections.Generic/SortedSet`1.xml index 10b529e3afcd8..8ee19047b9893 100644 --- a/xml/System.Collections.Generic/SortedSet`1.xml +++ b/xml/System.Collections.Generic/SortedSet`1.xml @@ -709,7 +709,7 @@ ## Remarks The `memberEqualityComparer` and the current must have the same definition of equality. - You can use the comparer returned by this method in the constructor to create a hash table of individual sets. + You can use the comparer returned by this method in the constructor to create a hash table of individual sets. diff --git a/xml/System.Collections.Generic/Stack`1+Enumerator.xml b/xml/System.Collections.Generic/Stack`1+Enumerator.xml index fa1b86f22fc03..76e433943d045 100644 --- a/xml/System.Collections.Generic/Stack`1+Enumerator.xml +++ b/xml/System.Collections.Generic/Stack`1+Enumerator.xml @@ -51,7 +51,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. ]]> diff --git a/xml/System.Collections.Generic/Stack`1.xml b/xml/System.Collections.Generic/Stack`1.xml index 3e7972e7e8f72..dd4f5fdccf293 100644 --- a/xml/System.Collections.Generic/Stack`1.xml +++ b/xml/System.Collections.Generic/Stack`1.xml @@ -54,13 +54,13 @@ ## Remarks is implemented as an array. - Stacks and queues are useful when you need temporary storage for information; that is, when you might want to discard an element after retrieving its value. Use if you need to access the information in the same order that it is stored in the collection. Use if you need to access the information in reverse order. + Stacks and queues are useful when you need temporary storage for information; that is, when you might want to discard an element after retrieving its value. Use if you need to access the information in the same order that it is stored in the collection. Use if you need to access the information in reverse order. - Use the and types when you need to access the collection from multiple threads concurrently. + Use the and types when you need to access the collection from multiple threads concurrently. - A common use for is to preserve variable states during calls to other procedures. + A common use for is to preserve variable states during calls to other procedures. - Three main operations can be performed on a and its elements: + Three main operations can be performed on a and its elements: - inserts an element at the top of the . @@ -347,7 +347,7 @@ for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -536,7 +536,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -782,7 +782,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -827,7 +827,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -884,7 +884,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. In the rare case where enumerations contend with write accesses, you must lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -926,7 +926,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1008,7 +1008,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. diff --git a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml index 18a08a61c9dad..414ae5e9a66d2 100644 --- a/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableDictionary`2+Builder.xml @@ -43,7 +43,7 @@ and other methods already provide fast bulk change operations on a collection, the class allows multiple combinations of changes to be made to a set with equal efficiency. + Although and other methods already provide fast bulk change operations on a collection, the class allows multiple combinations of changes to be made to a set with equal efficiency. ]]> diff --git a/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml index 478e8c851ee59..86b8b91d92656 100644 --- a/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableHashSet`1+Builder.xml @@ -36,7 +36,7 @@ and other methods already provide fast bulk change operations on a collection, the class allows multiple combinations of changes to be made to a set with equal efficiency. + Although and other methods already provide fast bulk change operations on a collection, the class allows multiple combinations of changes to be made to a set with equal efficiency. ]]> diff --git a/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml index 40e175fda65f6..df4991035ed26 100644 --- a/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableList`1+Builder.xml @@ -42,7 +42,7 @@ and other methods already provide fast bulk change operations on the list, the class allows multiple combinations of changes to be made to a list with equal efficiency. + Although and other methods already provide fast bulk change operations on the list, the class allows multiple combinations of changes to be made to a list with equal efficiency. ]]> diff --git a/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml index af5d5fa4384e9..fc17e7fcfb9a7 100644 --- a/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableList`1+Enumerator.xml @@ -32,7 +32,7 @@ and . + This structure should be kept synchronized with the other two binary tree enumerators: and . > [!CAUTION] > When this enumerator is used as a value type (that is, when it isn't boxed), do not copy it by assigning it to a second variable or by passing it to another method. When this enumerator is disposed of, it returns a mutable reference type stack to a resource pool, and if the value type enumerator is copied (which can easily happen unintentionally if you pass the value around), there is a risk that a stack that has already been returned to the resource pool may still be in use by one of the enumerator copies, leading to data corruption or exceptions. diff --git a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml index b91e018cd62f9..757deebc8e69b 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedDictionary`2+Enumerator.xml @@ -33,7 +33,7 @@ and . + This structure should be kept synchronized with the other two binary tree enumerators: and . > [!CAUTION] > When this enumerator is used as a value type (that is, when it isn't boxed), do not copy it by assigning it to a second variable or by passing it to another method. When this enumerator is disposed of, it returns a mutable reference type stack to a resource pool, and if the value type enumerator is copied (which can easily happen unintentionally if you pass the value around), there is a risk that a stack that has already been returned to the resource pool may still be in use by one of the enumerator copies, leading to data corruption or exceptions. diff --git a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml index a4f9350f8f2cf..745b3e028f488 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Builder.xml @@ -39,7 +39,7 @@ and other methods already provide fast bulk change operations on a collection, the class enables multiple combinations of changes to be made to a set with equal or greater efficiency, depending on the operation. + Although and other methods already provide fast bulk change operations on a collection, the class enables multiple combinations of changes to be made to a set with equal or greater efficiency, depending on the operation. ]]> diff --git a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml index 4c117034fde34..0760db18cd1d4 100644 --- a/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml +++ b/xml/System.Collections.Immutable/ImmutableSortedSet`1+Enumerator.xml @@ -32,7 +32,7 @@ and . + This structure should be kept synchronized with the other two binary tree enumerators: and . > [!CAUTION] > When this enumerator is used as a value type (that is, when it isn't boxed), do not copy it by assigning it to a second variable or by passing it to another method. When this enumerator is disposed of, it returns a mutable reference type stack to a resource pool, and if the value type enumerator is copied (which can easily happen unintentionally if you pass the value around), there is a risk that a stack that has already been returned to the resource pool may still be in use by one of the enumerator copies, leading to data corruption or exceptions. diff --git a/xml/System.Collections.ObjectModel/Collection`1.xml b/xml/System.Collections.ObjectModel/Collection`1.xml index 6c94359ab542c..bd9b701eace54 100644 --- a/xml/System.Collections.ObjectModel/Collection`1.xml +++ b/xml/System.Collections.ObjectModel/Collection`1.xml @@ -389,7 +389,7 @@ object is created using the default constructor, this method determines equality using the default equality comparer for `T`, the type of values in the list. If type `T` does not implement the interface, the method is used. + If the object is created using the default constructor, this method determines equality using the default equality comparer for `T`, the type of values in the list. If type `T` does not implement the interface, the method is used. If the Collection object is created by passing an object to the constructor, the method will be determined by the interface used by that object. @@ -436,7 +436,7 @@ to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order in which the enumerator iterates through the . @@ -545,7 +545,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -591,7 +591,7 @@ ## Remarks The is searched forward starting at the first element and ending at the last element. - This method determines equality using the default equality comparer for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, the average execution time is proportional to . That is, this method is an O(`n`) operation, where `n` is . @@ -874,7 +874,7 @@ for `T`, the type of values in the list. + This method determines equality using the default equality comparer for `T`, the type of values in the list. This method performs a linear search; therefore, the average execution time is proportional to . That is, this method is an O(`n`) operation, where `n` is . @@ -1157,7 +1157,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -1216,7 +1216,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1260,7 +1260,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1344,7 +1344,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -1479,7 +1479,7 @@ finally { . checks whether type `T` implements and uses that implementation, if available. If not, checks whether type `T` implements . If type `T` does not implement either interface, this method uses . + This method determines equality using the default comparer . checks whether type `T` implements and uses that implementation, if available. If not, checks whether type `T` implements . If type `T` does not implement either interface, this method uses . This method is an O(`n`) operation, where `n` is . @@ -1708,7 +1708,7 @@ finally { . checks whether type `T` implements and uses that implementation, if available. If not, checks whether type `T` implements . If type `T` does not implement either interface, this method uses . + This method determines equality using the default comparer . checks whether type `T` implements and uses that implementation, if available. If not, checks whether type `T` implements . If type `T` does not implement either interface, this method uses . This method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections.ObjectModel/KeyedCollection`2.xml b/xml/System.Collections.ObjectModel/KeyedCollection`2.xml index 60f4a01bc7116..0d6d3c5e19b1d 100644 --- a/xml/System.Collections.ObjectModel/KeyedCollection`2.xml +++ b/xml/System.Collections.ObjectModel/KeyedCollection`2.xml @@ -120,7 +120,7 @@ created with this constructor uses the default generic equality comparer for the type of the key, obtained from . To specify a different generic equality comparer, use the constructor or the constructor. + A created with this constructor uses the default generic equality comparer for the type of the key, obtained from . To specify a different generic equality comparer, use the constructor or the constructor. By default, the includes a lookup dictionary that is created when the first item is added. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior can be overridden by using the constructor and specifying a dictionary creation threshold. @@ -723,7 +723,7 @@ This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). > [!NOTE] -> This property is distinct from the inherited property, which gets and sets elements by numeric index. However, if `TKey` is of type , this property masks the inherited property. In that case, you can access the inherited property by casting the to its base type. For example, `KeyedCollection` (`KeyedCollection(Of Integer, MyType)` in Visual Basic, `KeyedCollection` in C++) can be cast to `Collection` (`Collection(Of MyType)` in Visual Basic, `Collection` in C++). +> This property is distinct from the inherited property, which gets and sets elements by numeric index. However, if `TKey` is of type , this property masks the inherited property. In that case, you can access the inherited property by casting the to its base type. For example, `KeyedCollection` (`KeyedCollection(Of Integer, MyType)` in Visual Basic, `KeyedCollection` in C++) can be cast to `Collection` (`Collection(Of MyType)` in Visual Basic, `Collection` in C++). If the has a lookup dictionary, `key` is used to retrieve the element from the dictionary. If there is no lookup dictionary, the key of each element is extracted using the method and compared with the specified key. @@ -736,7 +736,7 @@ ## Examples This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. - The code example calls both the property, which is read-only and retrieves by key, and the property, which is settable and retrieves by index. It shows how to access the latter property when the objects in the derived collection have integer keys, indistinguishable from the integers used for indexed retrieval. + The code example calls both the property, which is read-only and retrieves by key, and the property, which is settable and retrieves by index. It shows how to access the latter property when the objects in the derived collection have integer keys, indistinguishable from the integers used for indexed retrieval. The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . @@ -935,14 +935,14 @@ Override this method to provide customized behavior for setting the property inherited from the generic class. > [!NOTE] -> This method does not affect the behavior of the property, which is read-only. +> This method does not affect the behavior of the property, which is read-only. Call the base class implementation of this method to set the item in the underlying collection and to update the lookup dictionary. ## Examples - This section contains two code examples that demonstrate overriding the method to provide custom behavior for setting the property. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. + This section contains two code examples that demonstrate overriding the method to provide custom behavior for setting the property. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. Example 1 diff --git a/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml b/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml index 636fde94d5fc8..cdea43d7c9fb4 100644 --- a/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml +++ b/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml @@ -184,7 +184,7 @@ . + This method determines equality using the default equality comparer . This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -242,7 +242,7 @@ to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order that the enumerator iterates through the . @@ -368,7 +368,7 @@ The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -423,7 +423,7 @@ ## Remarks The is searched forward starting at the first element and ending at the last element. - This method determines equality using the default comparer . + This method determines equality using the default comparer . This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -888,7 +888,7 @@ ## Remarks > [!NOTE] -> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . +> If the type of the source cannot be cast automatically to the type of the destination `array`, the non-generic implementations of throw , whereas the generic implementations throw . This method is an O(`n`) operation, where `n` is . @@ -949,7 +949,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -995,7 +995,7 @@ are not synchronized. + Default implementations of collections in are not synchronized. Enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. @@ -1081,7 +1081,7 @@ finally { The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - Default implementations of collections in are not synchronized. + Default implementations of collections in are not synchronized. This method is an O(1) operation. @@ -1210,7 +1210,7 @@ finally { . + This method determines equality using the default comparer . This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -1258,7 +1258,7 @@ finally { . + This method determines equality using the default comparer . This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections.Specialized/BitVector32+Section.xml b/xml/System.Collections.Specialized/BitVector32+Section.xml index fa3cfa1e40ea9..a3e22720aec49 100644 --- a/xml/System.Collections.Specialized/BitVector32+Section.xml +++ b/xml/System.Collections.Specialized/BitVector32+Section.xml @@ -108,7 +108,7 @@ . + This method overrides . Two instances are considered equal if both sections are of the same length and are in the same location within a . @@ -146,7 +146,7 @@ . + This method overrides . This method generates the same hash code for two objects that are equal according to the method. @@ -243,7 +243,7 @@ if the and parameters represent the same object, otherwise, . - .]]> + .]]> @@ -314,7 +314,7 @@ . + This method overrides . ]]> diff --git a/xml/System.Collections.Specialized/BitVector32.xml b/xml/System.Collections.Specialized/BitVector32.xml index f41048fdeaa11..6596f116f9886 100644 --- a/xml/System.Collections.Specialized/BitVector32.xml +++ b/xml/System.Collections.Specialized/BitVector32.xml @@ -30,7 +30,7 @@ A structure can be set up to contain either sections for small integers or bit flags for Booleans, but not both. A is a window into the and is composed of the smallest number of consecutive bits that can contain the maximum value specified in . For example, a section with a maximum value of 1 is composed of only one bit, whereas a section with a maximum value of 5 is composed of three bits. You can create a with a maximum value of 1 to serve as a Boolean, thereby allowing you to store integers and Booleans in the same . - Some members can be used for a that is set up as sections, while other members can be used for one that is set up as bit flags. For example, the property is the indexer for a that is set up as sections, and the property is the indexer for a that is set up as bit flags. creates a series of masks that can be used to access individual bits in a that is set up as bit flags. + Some members can be used for a that is set up as sections, while other members can be used for one that is set up as bit flags. For example, the property is the indexer for a that is set up as sections, and the property is the indexer for a that is set up as bit flags. creates a series of masks that can be used to access individual bits in a that is set up as bit flags. Using a mask on a that is set up as sections might cause unexpected results. @@ -597,7 +597,7 @@ . + This method overrides . This method is an O(1) operation. diff --git a/xml/System.Collections.Specialized/CollectionsUtil.xml b/xml/System.Collections.Specialized/CollectionsUtil.xml index f2abe549d55bb..e59a3c5afc215 100644 --- a/xml/System.Collections.Specialized/CollectionsUtil.xml +++ b/xml/System.Collections.Specialized/CollectionsUtil.xml @@ -103,7 +103,7 @@ method, use the constructor to create a case-insensitive class. + Instead of using the method, use the constructor to create a case-insensitive class. ]]> @@ -142,7 +142,7 @@ method, use the constructor to create a case-insensitive class. + Instead of using the method, use the constructor to create a case-insensitive class. ]]> @@ -183,7 +183,7 @@ method, use the constructor to create a case-insensitive class. + Instead of using the method, use the constructor to create a case-insensitive class. ]]> diff --git a/xml/System.Collections.Specialized/HybridDictionary.xml b/xml/System.Collections.Specialized/HybridDictionary.xml index 4a4a1ce599e67..35bcf677f80f3 100644 --- a/xml/System.Collections.Specialized/HybridDictionary.xml +++ b/xml/System.Collections.Specialized/HybridDictionary.xml @@ -34,7 +34,7 @@ If the initial size of the collection is greater than the optimal size for a , the collection is stored in a to avoid the overhead of copying elements from the to a . - The constructor accepts a Boolean parameter that allows the user to specify whether the collection ignores the case when comparing strings. If the collection is case-sensitive, it uses the key's implementations of and . If the collection is case-insensitive, it performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. By default, the collection is case-sensitive. For more information on the invariant culture, see . + The constructor accepts a Boolean parameter that allows the user to specify whether the collection ignores the case when comparing strings. If the collection is case-sensitive, it uses the key's implementations of and . If the collection is case-insensitive, it performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. By default, the collection is case-sensitive. For more information on the invariant culture, see . A key cannot be null, but a value can. @@ -90,7 +90,7 @@ as the hash code provider and the key's implementation of as the comparer. + By default, the collection is case-sensitive and uses the key's implementation of as the hash code provider and the key's implementation of as the comparer. The comparer determines whether two keys are equal. Every key in a must be unique. @@ -138,7 +138,7 @@ and . If `caseInsensitive` is `true`, the collection performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. For more information on the invariant culture, see . + If `caseInsensitive` is `false`, the collection uses the key's implementations of and . If `caseInsensitive` is `true`, the collection performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. For more information on the invariant culture, see . This constructor is an O(1) operation. @@ -177,7 +177,7 @@ ## Remarks If the initial size of the collection is greater than the optimal size for a , the collection is stored in a to avoid the overhead of copying elements from the to the . - By default, the collection is case-sensitive and uses the key's implementation of as the hash code provider and the key's implementation of as the comparer. + By default, the collection is case-sensitive and uses the key's implementation of as the hash code provider and the key's implementation of as the comparer. The comparer determines whether two keys are equal. Every key in a must be unique. @@ -220,7 +220,7 @@ ## Remarks If the initial size of the collection is greater than the optimal size for a , the collection is stored in a to avoid the overhead of copying elements from the to the . - If `caseInsensitive` is `false`, the collection uses the key's implementations of and . If `caseInsensitive` is `true`, the collection performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. For more information on the invariant culture, see . + If `caseInsensitive` is `false`, the collection uses the key's implementations of and . If `caseInsensitive` is `true`, the collection performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. For more information on the invariant culture, see . This constructor is an O(`n`) operation, where `n` is `initialSize`. @@ -584,7 +584,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. @@ -625,7 +625,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. @@ -666,7 +666,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. Derived classes can provide a synchronized version of the using the property. diff --git a/xml/System.Collections.Specialized/ListDictionary.xml b/xml/System.Collections.Specialized/ListDictionary.xml index 2492547ae339f..1a74d0b7eeefb 100644 --- a/xml/System.Collections.Specialized/ListDictionary.xml +++ b/xml/System.Collections.Specialized/ListDictionary.xml @@ -90,7 +90,7 @@ must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . This constructor is an O(1) operation. @@ -140,7 +140,7 @@ must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The custom comparer enables such scenarios as doing lookups with case-insensitive strings. @@ -503,7 +503,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. @@ -544,7 +544,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. @@ -585,7 +585,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. Derived classes can provide a synchronized version of the using the property. diff --git a/xml/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection.xml b/xml/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection.xml index ea3f378d07ab2..99d9cc54570c8 100644 --- a/xml/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection.xml +++ b/xml/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection.xml @@ -243,7 +243,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. This method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections.Specialized/NameObjectCollectionBase.xml b/xml/System.Collections.Specialized/NameObjectCollectionBase.xml index 0066ce1fb108a..ef2b87175585f 100644 --- a/xml/System.Collections.Specialized/NameObjectCollectionBase.xml +++ b/xml/System.Collections.Specialized/NameObjectCollectionBase.xml @@ -46,7 +46,7 @@ The comparer determines whether two keys are equal. The default comparer is the . - In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses when comparing strings. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](~/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md). + In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses when comparing strings. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](~/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md). `null` is allowed as a key or as a value. @@ -1312,7 +1312,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. While the method is not visible to COM clients by default, inheriting the class can expose it and can cause undesirable behavior in COM clients. diff --git a/xml/System.Collections.Specialized/NameValueCollection.xml b/xml/System.Collections.Specialized/NameValueCollection.xml index 0c25c70f8ce85..4391833f3e2d1 100644 --- a/xml/System.Collections.Specialized/NameValueCollection.xml +++ b/xml/System.Collections.Specialized/NameValueCollection.xml @@ -40,7 +40,7 @@ The comparer determines whether two keys are equal. The default comparer is the . - In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses when comparing strings. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](~/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md). + In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses when comparing strings. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](~/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md). `null` is allowed as a key or as a value. @@ -669,7 +669,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. This method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections.Specialized/OrderedDictionary.xml b/xml/System.Collections.Specialized/OrderedDictionary.xml index 97b2dd9b8caa2..2597f025b6876 100644 --- a/xml/System.Collections.Specialized/OrderedDictionary.xml +++ b/xml/System.Collections.Specialized/OrderedDictionary.xml @@ -90,7 +90,7 @@ collection must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a collection must be unique. The default comparer is the key's implementation of . @@ -138,7 +138,7 @@ collection must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a collection must be unique. The default comparer is the key's implementation of . The custom comparer enables such scenarios as doing lookups with case-insensitive strings. @@ -175,7 +175,7 @@ collection must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a collection must be unique. The default comparer is the key's implementation of . ]]> @@ -216,7 +216,7 @@ collection must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a collection must be unique. The default comparer is the key's implementation of . The custom comparer enables such scenarios as doing lookups with case-insensitive strings. @@ -254,7 +254,7 @@ collection must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a collection must be unique. The default comparer is the key's implementation of . ]]> diff --git a/xml/System.Collections.Specialized/StringCollection.xml b/xml/System.Collections.Specialized/StringCollection.xml index e9e130726f3d6..52310f66c1ae7 100644 --- a/xml/System.Collections.Specialized/StringCollection.xml +++ b/xml/System.Collections.Specialized/StringCollection.xml @@ -269,7 +269,7 @@ ## Remarks The method can confirm the existence of a string before performing further operations. - This method determines equality by calling . String comparisons are case-sensitive. + This method determines equality by calling . String comparisons are case-sensitive. This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -481,7 +481,7 @@ . String comparisons are case-sensitive. + This method determines equality by calling . String comparisons are case-sensitive. This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -590,7 +590,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. @@ -738,7 +738,7 @@ In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - This method determines equality by calling . String comparisons are case-sensitive. + This method determines equality by calling . String comparisons are case-sensitive. This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -891,7 +891,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. This method is an O(`n`) operation, where `n` is . @@ -1044,7 +1044,7 @@ . + This method determines equality by calling . This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -1089,7 +1089,7 @@ ## Remarks The is searched forward starting at the first element and ending at the last element. - This method determines equality by calling . + This method determines equality by calling . This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -1323,7 +1323,7 @@ In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - This method determines equality by calling . + This method determines equality by calling . This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections.Specialized/StringDictionary.xml b/xml/System.Collections.Specialized/StringDictionary.xml index c62bc0fdd5c8b..9b30df6b52b51 100644 --- a/xml/System.Collections.Specialized/StringDictionary.xml +++ b/xml/System.Collections.Specialized/StringDictionary.xml @@ -39,7 +39,7 @@ The key is handled in a case-insensitive manner; it is translated to lowercase before it is used with the string dictionary. - In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses when comparing strings. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](~/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md). + In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses when comparing strings. For more information about how culture affects comparisons and sorting, see [Performing Culture-Insensitive String Operations](~/docs/standard/globalization-localization/performing-culture-insensitive-string-operations.md). @@ -288,7 +288,7 @@ method. + The values of the elements of the StringDictionary are compared to the specified value using the method. This method performs a linear search; therefore, the average execution time is proportional to . That is, this method is an O(`n`) operation, where `n` is . @@ -341,7 +341,7 @@ copies objects that can be typecast to . contains both the key and the value. + copies objects that can be typecast to . contains both the key and the value. The elements copied to the are sorted in the same order that the enumerator iterates through the . diff --git a/xml/System.Collections/ArrayList.xml b/xml/System.Collections/ArrayList.xml index fc4bc099ebe7f..1ec67aa54f9e5 100644 --- a/xml/System.Collections/ArrayList.xml +++ b/xml/System.Collections/ArrayList.xml @@ -790,7 +790,7 @@ ## Remarks This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . - This method determines equality by calling . + This method determines equality by calling . Starting with the .NET Framework 2.0, this method uses the collection’s objects’ and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. @@ -835,7 +835,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order in which the enumerator iterates through the . @@ -844,7 +844,7 @@ ## Examples - The following code example shows how to copy an into a one-dimensional . + The following code example shows how to copy an into a one-dimensional . [!code-cpp[Classic ArrayList.CopyTo Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic ArrayList.CopyTo Example/CPP/source.cpp#1)] [!code-csharp[Classic ArrayList.CopyTo Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic ArrayList.CopyTo Example/CS/source.cs#1)] @@ -902,7 +902,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order in which the enumerator iterates through the . @@ -911,7 +911,7 @@ ## Examples - The following code example shows how to copy an into a one-dimensional . + The following code example shows how to copy an into a one-dimensional . [!code-cpp[Classic ArrayList.CopyTo1 Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic ArrayList.CopyTo1 Example/CPP/source.cpp#1)] [!code-csharp[Classic ArrayList.CopyTo1 Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic ArrayList.CopyTo1 Example/CS/source.cs#1)] @@ -975,7 +975,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. The elements are copied to the in the same order in which the enumerator iterates through the . @@ -984,7 +984,7 @@ ## Examples - The following code example shows how to copy an into a one-dimensional . + The following code example shows how to copy an into a one-dimensional . [!code-cpp[Classic ArrayList.CopyTo1 Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic ArrayList.CopyTo1 Example/CPP/source.cpp#1)] [!code-csharp[Classic ArrayList.CopyTo1 Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic ArrayList.CopyTo1 Example/CS/source.cs#1)] @@ -1405,7 +1405,7 @@ This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . - This method determines equality by calling . + This method determines equality by calling . Starting with the .NET Framework 2.0, this method uses the collection’s objects’ and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. @@ -1464,7 +1464,7 @@ This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is the number of elements from `startIndex` to the end of the . - This method determines equality by calling . + This method determines equality by calling . Starting with the .NET Framework 2.0, this method uses the collection’s objects’ and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. @@ -1527,7 +1527,7 @@ This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is `count`. - This method determines equality by calling . + This method determines equality by calling . Starting with the .NET Framework 2.0, this method uses the collection’s objects’ and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. @@ -2030,7 +2030,7 @@ This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is the number of elements from the beginning of the to `startIndex`. - This method determines equality by calling . + This method determines equality by calling . Starting with the .NET Framework 2.0, this method uses the collection’s objects’ and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. @@ -2093,7 +2093,7 @@ This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is `count`. - This method determines equality by calling . + This method determines equality by calling . Starting with the .NET Framework 2.0, this method uses the collection’s objects’ and methods on `item` to determine whether item exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. @@ -2264,7 +2264,7 @@ This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . - This method determines equality by calling . + This method determines equality by calling . In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. @@ -2507,7 +2507,7 @@ to reverse the order of the elements, such that the element at [i], where i is any index within the range, moves to [j], where j equals `index` + `index` + `count` - i - 1. + This method uses to reverse the order of the elements, such that the element at [i], where i is any index within the range, moves to [j], where j equals `index` + `index` + `count` - i - 1. This method is an O(`n`) operation, where `n` is . @@ -2562,7 +2562,7 @@ to reverse the order of the elements, such that the element at [i], where i is any index within the range, moves to [j], where j equals `index` + `index` + `count` - i - 1. + This method uses to reverse the order of the elements, such that the element at [i], where i is any index within the range, moves to [j], where j equals `index` + `index` + `count` - i - 1. This method is an O(`n`) operation, where `n` is `count`. @@ -2685,7 +2685,7 @@ , which uses the QuickSort algorithm. The QuickSort algorithm is a comparison sort (also called an unstable sort), which means that a "less than or equal to" comparison operation determines which of two elements should occur first in the final sorted list. However, if two elements are equal, their original order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. To perform a stable sort, you must implement a custom interface to use with the other overloads of this method. + This method uses , which uses the QuickSort algorithm. The QuickSort algorithm is a comparison sort (also called an unstable sort), which means that a "less than or equal to" comparison operation determines which of two elements should occur first in the final sorted list. However, if two elements are equal, their original order might not be preserved. In contrast, a stable sort preserves the order of elements that are equal. To perform a stable sort, you must implement a custom interface to use with the other overloads of this method. On average, this method is an O(`n` log `n`) operation, where `n` is ; in the worst case it is an O(`n`^2) operation. @@ -3039,7 +3039,7 @@ , which is an O(`n`) operation, where `n` is . + The elements are copied using , which is an O(`n`) operation, where `n` is . ]]> @@ -3088,7 +3088,7 @@ ## Remarks All of the objects in the object will be cast to the specified in the `type` parameter. - The elements are copied using , which is an O(`n`) operation, where `n` is . + The elements are copied using , which is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections/BitArray.xml b/xml/System.Collections/BitArray.xml index 5cfb964748fa5..2d06c2fed0882 100644 --- a/xml/System.Collections/BitArray.xml +++ b/xml/System.Collections/BitArray.xml @@ -43,7 +43,7 @@ The class is a structure that provides the same functionality as , but with faster performance. is faster because it is a value type and therefore allocated on the stack, whereas is a reference type and, therefore, allocated on the heap. - can store exactly 32 bits, whereas can store a variable number of bits. stores both bit flags and small integers, thereby making it ideal for data that is not exposed to the user. However, if the number of required bit flags is unknown, is variable, or is greater than 32, use instead. + can store exactly 32 bits, whereas can store a variable number of bits. stores both bit flags and small integers, thereby making it ideal for data that is not exposed to the user. However, if the number of required bit flags is unknown, is variable, or is greater than 32, use instead. is in the namespace; is in the namespace. @@ -432,7 +432,7 @@ ## Remarks The specified array must be of a compatible type. Only `bool`, `int`, and `byte` types of arrays are supported. - This method uses to copy the elements. + This method uses to copy the elements. This method is an O(`n`) operation, where `n` is . @@ -630,7 +630,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. @@ -670,7 +670,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections/CaseInsensitiveComparer.xml b/xml/System.Collections/CaseInsensitiveComparer.xml index 9db56321f4108..169a4f9ec543f 100644 --- a/xml/System.Collections/CaseInsensitiveComparer.xml +++ b/xml/System.Collections/CaseInsensitiveComparer.xml @@ -39,7 +39,7 @@ The class is the default implementation of the interface and performs case-sensitive string comparisons. - The objects used as keys by a are required to override the method (or the interface) and the method (or the interface). The implementation of both methods or interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use this class with the class or any case-insensitive implementation. + The objects used as keys by a are required to override the method (or the interface) and the method (or the interface). The implementation of both methods or interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use this class with the class or any case-insensitive implementation. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). @@ -82,7 +82,7 @@ instance is created using this constructor, the of the current thread is saved. Comparison procedures use the saved culture to determine the sort order and casing rules; therefore, string comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + When the instance is created using this constructor, the of the current thread is saved. Comparison procedures use the saved culture to determine the sort order and casing rules; therefore, string comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). @@ -126,7 +126,7 @@ to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + Comparison procedures use the specified to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). @@ -196,7 +196,7 @@ to compare the strings with the casing ignored; otherwise, it uses the implementation of either object. That is, if `a` implements , then this method returns the result of `a`. `CompareTo` (`b`); otherwise, if `b` implements , then it returns the negated result of `b`. `CompareTo` (`a`). + If `a` and `b` are both strings, this method uses to compare the strings with the casing ignored; otherwise, it uses the implementation of either object. That is, if `a` implements , then this method returns the result of `a`. `CompareTo` (`b`); otherwise, if `b` implements , then it returns the negated result of `b`. `CompareTo` (`a`). Comparing `null` with any type is allowed and does not generate an exception when using . When sorting, `null` is considered to be less than any other object. @@ -240,7 +240,7 @@ instance is created using the parameterless constructor, the of the current thread is saved. Comparison procedures use the saved culture to determine the sort order and casing rules; therefore, string comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + When the instance is created using the parameterless constructor, the of the current thread is saved. Comparison procedures use the saved culture to determine the sort order and casing rules; therefore, string comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). ]]> @@ -275,7 +275,7 @@ to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + Comparison procedures use the to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). diff --git a/xml/System.Collections/CaseInsensitiveHashCodeProvider.xml b/xml/System.Collections/CaseInsensitiveHashCodeProvider.xml index 631f1e9b8bdfb..b95181519d19e 100644 --- a/xml/System.Collections/CaseInsensitiveHashCodeProvider.xml +++ b/xml/System.Collections/CaseInsensitiveHashCodeProvider.xml @@ -39,7 +39,7 @@ ## Remarks implements the interface supporting case-insensitive comparisons on strings, just as implements the interface supporting case-insensitive comparisons on strings. - The objects used as keys by a are required to override the method (or the interface) and the method (or the interface). The implementation of both methods or interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use this class with the class or any case-insensitive implementation. + The objects used as keys by a are required to override the method (or the interface) and the method (or the interface). The implementation of both methods or interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use this class with the class or any case-insensitive implementation. @@ -79,7 +79,7 @@ instance is created using this constructor, the of the current thread is saved. Comparison procedures use the saved culture to determine the casing rules; therefore, hash code comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + When the instance is created using this constructor, the of the current thread is saved. Comparison procedures use the saved culture to determine the casing rules; therefore, hash code comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). @@ -122,7 +122,7 @@ to determine the casing rules. Hash code comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + Comparison procedures use the specified to determine the casing rules. Hash code comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). @@ -167,7 +167,7 @@ instance is created using the parameterless constructor, the of the current thread is saved. Comparison procedures use the saved culture to determine the casing rules; therefore, hash code comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + When the instance is created using the parameterless constructor, the of the current thread is saved. Comparison procedures use the saved culture to determine the casing rules; therefore, hash code comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). ]]> @@ -201,7 +201,7 @@ to determine the casing rules. Hash code comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + Comparison procedures use the to determine the casing rules. Hash code comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). diff --git a/xml/System.Collections/CollectionBase.xml b/xml/System.Collections/CollectionBase.xml index 41a60f252d0c5..2fdf8d500149e 100644 --- a/xml/System.Collections/CollectionBase.xml +++ b/xml/System.Collections/CollectionBase.xml @@ -1008,7 +1008,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. This method is an O(`n`) operation, where `n` is . @@ -1212,7 +1212,7 @@ ## Remarks This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . - This method determines equality by calling . + This method determines equality by calling . Starting with the .NET Framework 2.0, this method uses the collection’s objects’ and methods on `item` to determine whether `item` exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. @@ -1264,7 +1264,7 @@ ## Remarks This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . - This method determines equality by calling . + This method determines equality by calling . Starting with the .NET Framework 2.0, this method uses the collection’s objects’ and methods on `item` to determine whether `item` exists. In the earlier versions of the .NET Framework, this determination was made by using the and methods of the `item` parameter on the objects in the collection. @@ -1525,7 +1525,7 @@ This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . - This method determines equality by calling . + This method determines equality by calling . In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. diff --git a/xml/System.Collections/Comparer.xml b/xml/System.Collections/Comparer.xml index 0cd351e9a8293..0d21a9630ec5d 100644 --- a/xml/System.Collections/Comparer.xml +++ b/xml/System.Collections/Comparer.xml @@ -43,7 +43,7 @@ ## Remarks This class is the default implementation of the interface. The class is the implementation of the interface that performs case-insensitive string comparisons. - Comparison procedures use the of the current thread unless otherwise specified. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + Comparison procedures use the of the current thread unless otherwise specified. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). @@ -90,7 +90,7 @@ to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + Comparison procedures use the specified to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). @@ -218,7 +218,7 @@ of the current thread to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + Comparison procedures use the of the current thread to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). ]]> @@ -255,7 +255,7 @@ to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). + Comparison procedures use the to determine the sort order and casing rules. String comparisons might have different results depending on the culture. For more information on culture-specific comparisons, see the namespace and [Globalization and Localization](http://msdn.microsoft.com/library/9a59696b-d89b-45bd-946d-c75da4732d02). diff --git a/xml/System.Collections/DictionaryEntry.xml b/xml/System.Collections/DictionaryEntry.xml index f09d872f175aa..470f46a18efe8 100644 --- a/xml/System.Collections/DictionaryEntry.xml +++ b/xml/System.Collections/DictionaryEntry.xml @@ -34,7 +34,7 @@ method returns an instance of this type. + The method returns an instance of this type. The `foreach` statement of the C# language (`for each` in Visual C++, `For Each` in Visual Basic) requires the type of each element in the collection. Since each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: diff --git a/xml/System.Collections/Hashtable.xml b/xml/System.Collections/Hashtable.xml index c74cfa0b6f89e..02bc71a172e84 100644 --- a/xml/System.Collections/Hashtable.xml +++ b/xml/System.Collections/Hashtable.xml @@ -59,9 +59,9 @@ Each element is a key/value pair stored in a object. A key cannot be `null`, but a value can be. - The objects used as keys by a are required to override the method (or the interface) and the method (or the interface). The implementation of both methods and interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use the class (or any case-insensitive implementation) with the class (or any case-insensitive implementation). + The objects used as keys by a are required to override the method (or the interface) and the method (or the interface). The implementation of both methods and interfaces must handle case sensitivity the same way; otherwise, the might behave incorrectly. For example, when creating a , you must use the class (or any case-insensitive implementation) with the class (or any case-insensitive implementation). - Furthermore, these methods must produce the same results when called with the same parameters while the key exists in the . An alternative is to use a constructor with an parameter. If key equality were simply reference equality, the inherited implementation of and would suffice. + Furthermore, these methods must produce the same results when called with the same parameters while the key exists in the . An alternative is to use a constructor with an parameter. If key equality were simply reference equality, the inherited implementation of and would suffice. Key objects must be immutable as long as they are used as keys in the . @@ -142,9 +142,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . This constructor is an O(1) operation. @@ -199,9 +199,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The elements of the new are sorted in the same order in which the enumerator iterates through the object. @@ -264,11 +264,11 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. + The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The enables scenarios such as doing lookups with case-insensitive strings. @@ -325,9 +325,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . This constructor is an O(`n`) operation, where `n` is `capacity`. @@ -390,11 +390,11 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. + The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The enables scenarios such as doing lookups with case-insensitive strings. @@ -457,9 +457,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The elements of the new are sorted in the same order in which the enumerator iterates through the object. @@ -535,9 +535,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. @@ -600,11 +600,11 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. + The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The enables scenarios such as doing lookups with case-insensitive strings. @@ -665,9 +665,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . This constructor is an O(`n`) operation, where `n` is the `capacity` parameter. @@ -732,9 +732,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . This constructor is an O(`n`) operation, where `n` is . @@ -797,9 +797,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. @@ -868,11 +868,11 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. + The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the object are not required to override the and methods. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The enables scenarios such as doing lookups with case-insensitive strings. @@ -952,9 +952,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. @@ -1021,11 +1021,11 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. + The object includes both the hash code provider and the comparer. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The enables scenarios such as doing lookups with case-insensitive strings. @@ -1107,9 +1107,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the object. The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. @@ -1191,9 +1191,9 @@ When the actual load factor reaches the specified load factor, the number of buckets is automatically increased to the smallest prime number that is larger than twice the current number of buckets. - The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . + The hash code provider dispenses hash codes for keys in the . The default hash code provider is the key's implementation of . - The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . + The comparer determines whether two keys are equal. Every key in a must be unique. The default comparer is the key's implementation of . The custom hash code provider and the custom comparer enable scenarios such as doing lookups with case-insensitive strings. @@ -1465,7 +1465,7 @@ implements . It behaves exactly as . + implements . It behaves exactly as . This method is an O(1) operation. @@ -1581,7 +1581,7 @@ are compared to the specified value using the method. + The values of the elements of the are compared to the specified value using the method. This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . @@ -1739,7 +1739,7 @@ includes both the comparer and the hash code provider. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. + The includes both the comparer and the hash code provider. If an is used in the constructor, the objects used as keys in the are not required to override the and methods. Retrieving the value of this property is an O(1) operation. @@ -1850,7 +1850,7 @@ implementation, this method uses that hash code provider; otherwise, it uses the implementation of `key`. + If the hash table was created with a specific implementation, this method uses that hash code provider; otherwise, it uses the implementation of `key`. This method is an O(1) operation. diff --git a/xml/System.Collections/ICollection.xml b/xml/System.Collections/ICollection.xml index f77802a599cb6..c7a92b3c2023c 100644 --- a/xml/System.Collections/ICollection.xml +++ b/xml/System.Collections/ICollection.xml @@ -43,7 +43,7 @@ If neither the interface nor the interface meet the requirements of the required collection, derive the new collection class from the interface instead for more flexibility. - For the generic version of this interface, see . + For the generic version of this interface, see . ]]> @@ -165,7 +165,7 @@ ## Remarks returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -213,7 +213,7 @@ ## Remarks For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: diff --git a/xml/System.Collections/IComparer.xml b/xml/System.Collections/IComparer.xml index 403746d15a434..f8e344adcac3e 100644 --- a/xml/System.Collections/IComparer.xml +++ b/xml/System.Collections/IComparer.xml @@ -31,9 +31,9 @@ and methods. It provides a way to customize the sort order of a collection. See the method for notes on parameters and return value. + This interface is used in conjunction with the and methods. It provides a way to customize the sort order of a collection. See the method for notes on parameters and return value. - The default implementation of this interface is the class. For the generic version of this interface, see . + The default implementation of this interface is the class. For the generic version of this interface, see . diff --git a/xml/System.Collections/IDictionary.xml b/xml/System.Collections/IDictionary.xml index 96e4717ca5cd8..e4eb4ac9357cb 100644 --- a/xml/System.Collections/IDictionary.xml +++ b/xml/System.Collections/IDictionary.xml @@ -35,7 +35,7 @@ interface is the base interface for nongeneric collections of key/value pairs. For the generic version of this interface, see . + The interface is the base interface for nongeneric collections of key/value pairs. For the generic version of this interface, see . Each element is a key/value pair stored in a object. diff --git a/xml/System.Collections/IEnumerable.xml b/xml/System.Collections/IEnumerable.xml index 1d5307267d0d9..f223444d82fec 100644 --- a/xml/System.Collections/IEnumerable.xml +++ b/xml/System.Collections/IEnumerable.xml @@ -38,7 +38,7 @@ > [!NOTE] > To view the .NET Framework source code for this type, see the [Reference Source](http://referencesource.microsoft.com/#mscorlib/system/collections/ienumerable.cs#9be451ac13d86a97). You can browse through the source code online, download the reference for offline viewing, and step through the sources (including patches and updates) during debugging; see [instructions](http://referencesource.microsoft.com/). - is the base interface for all non-generic collections that can be enumerated. For the generic version of this interface see . contains a single method, , which returns an . provides the ability to iterate through the collection by exposing a property and and methods. + is the base interface for all non-generic collections that can be enumerated. For the generic version of this interface see . contains a single method, , which returns an . provides the ability to iterate through the collection by exposing a property and and methods. It is a best practice to implement and on your collection classes to enable the `foreach` (`For Each` in Visual Basic) syntax, however implementing is not required. If your collection does not implement , you must still follow the iterator pattern to support this syntax by providing a `GetEnumerator` method that returns an interface, class or struct. When using Visual Basic, you must provide an implementation, which is returned by `GetEnumerator`. When developing with C# you must provide a class that contains a `Current` property, and `MoveNext` and `Reset` methods as described by , but the class does not have to implement . diff --git a/xml/System.Collections/IEqualityComparer.xml b/xml/System.Collections/IEqualityComparer.xml index 21aafe9f5909d..029aa47986656 100644 --- a/xml/System.Collections/IEqualityComparer.xml +++ b/xml/System.Collections/IEqualityComparer.xml @@ -35,7 +35,7 @@ This interface supports only equality comparisons. Customization of comparisons for sorting and ordering is provided by the interface. - For the generic version of this interface, see . + For the generic version of this interface, see . ]]> @@ -85,7 +85,7 @@ ## Examples - The following code example demonstrates the implementation of a case-insensitive . In this example, the method is used to determine whether two objects are equal, based on the provided . + The following code example demonstrates the implementation of a case-insensitive . In this example, the method is used to determine whether two objects are equal, based on the provided . [!code-cpp[System.Collections.Hashtable_ctor#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/CPP/hashtable_ctor.cpp#2)] [!code-csharp[System.Collections.Hashtable_ctor#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Collections.Hashtable_ctor/CS/hashtable_ctor.cs#2)] diff --git a/xml/System.Collections/IHashCodeProvider.xml b/xml/System.Collections/IHashCodeProvider.xml index 4dd6b6b999622..79b790cc094dd 100644 --- a/xml/System.Collections/IHashCodeProvider.xml +++ b/xml/System.Collections/IHashCodeProvider.xml @@ -30,9 +30,9 @@ interface is used in conjunction with the class. The objects used as keys by a object must override the and methods. or the key's implementation of is used as the hash code provider. or the key's implementation of is used as the comparer. + The interface is used in conjunction with the class. The objects used as keys by a object must override the and methods. or the key's implementation of is used as the hash code provider. or the key's implementation of is used as the comparer. - However, some overloads of the constructor take a parameter that is an implementation, or a parameter that is an implementation, or both. If an implementation is passed to the constructor, the method of that implementation is used as the hash code provider. If an implementation is passed to the constructor, the method of that implementation is used as the comparer. + However, some overloads of the constructor take a parameter that is an implementation, or a parameter that is an implementation, or both. If an implementation is passed to the constructor, the method of that implementation is used as the hash code provider. If an implementation is passed to the constructor, the method of that implementation is used as the comparer. ]]> diff --git a/xml/System.Collections/IList.xml b/xml/System.Collections/IList.xml index a6995439d8279..e16f46389bb22 100644 --- a/xml/System.Collections/IList.xml +++ b/xml/System.Collections/IList.xml @@ -37,7 +37,7 @@ ## Remarks is a descendant of the interface and is the base interface of all non-generic lists. implementations fall into three categories: read-only, fixed-size, and variable-size. A read-only cannot be modified. A fixed-size does not allow the addition or removal of elements, but it allows the modification of existing elements. A variable-size allows the addition, removal, and modification of elements. - For the generic version of this interface, see . + For the generic version of this interface, see . @@ -133,7 +133,7 @@ and the capacity of a collection. Typically, the count is set to zero, and references to other objects from elements of the collection are also released. The capacity can be set to zero or a default value, or it can remain unchanged. + Implementations of this method can vary in how they handle the and the capacity of a collection. Typically, the count is set to zero, and references to other objects from elements of the collection are also released. The capacity can be set to zero or a default value, or it can remain unchanged. diff --git a/xml/System.Collections/IStructuralComparable.xml b/xml/System.Collections/IStructuralComparable.xml index 7a27210a81053..5386f7e255f96 100644 --- a/xml/System.Collections/IStructuralComparable.xml +++ b/xml/System.Collections/IStructuralComparable.xml @@ -38,7 +38,7 @@ > [!NOTE] > The interface supports only structural comparisons for sorting or ordering. The interface supports custom comparisons for structural equality. - The .NET Framework provides two default comparers. One is returned by the property; the other is returned by the property. + The .NET Framework provides two default comparers. One is returned by the property; the other is returned by the property. The generic tuple classes (, , , and so on) and the class provide explicit implementations of the interface. By casting (in C#) or converting (in Visual Basic) the current instance of an array or tuple to an interface value and providing your implementation as an argument to the method, you can define a custom sort order for the array or collection. However, you do not call the method directly in most cases. Instead, the method is called by sorting methods such as . In this case, you define your implementation and pass it as an argument to a sorting method or collection object's class constructor. The method with your custom comparer is then called automatically whenever the collection is sorted. @@ -119,13 +119,13 @@ method supports custom structural comparison and sorting of array and tuple objects. The method calls the `comparer` object's method to compare individual array elements or tuple components, starting with the first element or component. The individual calls to end and the method returns a value when one of the following conditions becomes true: + The method supports custom structural comparison and sorting of array and tuple objects. The method calls the `comparer` object's method to compare individual array elements or tuple components, starting with the first element or component. The individual calls to end and the method returns a value when one of the following conditions becomes true: -- The method returns -1. +- The method returns -1. -- The method returns 1. +- The method returns 1. -- The method is called for the last element or component in the collection object. +- The method is called for the last element or component in the collection object. @@ -134,7 +134,7 @@ The `PopulationComparer` class provides an implementation that allows the array of sextuples to be sorted by any one of its components. Two values are provided to the `PopulationComparer` class in its constructor: the position of the component that defines the sort order, and a value that indicates whether the tuple objects should be sorted in ascending or descending order. - The example then displays the elements in the array in unsorted order, sorts them by the third component (the population in 1970) and displays them, and then sorts them by the sixth component (the population in 2000) and displays them. Note that the example does not directly call the implementation. The method is called implicitly by the method for each tuple object in the array. + The example then displays the elements in the array in unsorted order, sorts them by the third component (the population in 1970) and displays them, and then sorts them by the sixth component (the population in 2000) and displays them. Note that the example does not directly call the implementation. The method is called implicitly by the method for each tuple object in the array. [!code-csharp[System.Tuple\`6.CompareTo#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.tuple`6.compareto/cs/compareto2.cs#2)] [!code-vb[System.Tuple\`6.CompareTo#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.tuple`6.compareto/vb/compareto2.vb#2)] diff --git a/xml/System.Collections/IStructuralEquatable.xml b/xml/System.Collections/IStructuralEquatable.xml index 91473f876bb71..7af7b0f91e353 100644 --- a/xml/System.Collections/IStructuralEquatable.xml +++ b/xml/System.Collections/IStructuralEquatable.xml @@ -36,7 +36,7 @@ > [!NOTE] > The interface supports only custom comparisons for structural equality. The interface supports custom structural comparisons for sorting and ordering. - The .NET Framework also provides default equality comparers, which are returned by the and properties. For more information, see the example. + The .NET Framework also provides default equality comparers, which are returned by the and properties. For more information, see the example. The generic tuple classes (, , , and so on) and the class provide explicit implementations of the interface. By casting (in C#) or converting (in Visual Basic) the current instance of an array or tuple to an interface value and providing your implementation as an argument to the method, you can define a custom equality comparison for the array or collection. @@ -48,7 +48,7 @@ [!code-csharp[System.Collections.IStructuralEquatable#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.istructuralequatable/cs/nanexample1.cs#1)] [!code-vb[System.Collections.IStructuralEquatable#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.istructuralequatable/vb/nanexample1.vb#1)] - The following example creates two identical 3-tuple objects whose components consist of three values. The value of the second component is . The example then calls the method, and it calls the method three times. The first time, it passes the default equality comparer that is returned by the property. The second time, it passes the default equality comparer that is returned by the property. The third time, it passes the custom `NanComparer` object. As the output from the example shows, the first three method calls return `true`, whereas the fourth call returns `false`. + The following example creates two identical 3-tuple objects whose components consist of three values. The value of the second component is . The example then calls the method, and it calls the method three times. The first time, it passes the default equality comparer that is returned by the property. The second time, it passes the default equality comparer that is returned by the property. The third time, it passes the custom `NanComparer` object. As the output from the example shows, the first three method calls return `true`, whereas the fourth call returns `false`. [!code-csharp[System.Collections.IStructuralEquatable#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.istructuralequatable/cs/nanexample1.cs#2)] [!code-vb[System.Collections.IStructuralEquatable#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.istructuralequatable/vb/nanexample1.vb#2)] @@ -101,7 +101,7 @@ method supports custom structural comparison of array and tuple objects. This method in turn calls the `comparer` object's method to compare individual array elements or tuple components, starting with the first element or component. The individual calls to end and the method returns a value either when a method call returns `false` or after all array elements or tuple components have been compared. + The method supports custom structural comparison of array and tuple objects. This method in turn calls the `comparer` object's method to compare individual array elements or tuple components, starting with the first element or component. The individual calls to end and the method returns a value either when a method call returns `false` or after all array elements or tuple components have been compared. @@ -111,7 +111,7 @@ [!code-csharp[System.Collections.IStructuralEquatable#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.istructuralequatable/cs/nanexample1.cs#1)] [!code-vb[System.Collections.IStructuralEquatable#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.istructuralequatable/vb/nanexample1.vb#1)] - The following example creates two identical 3-tuple objects whose components consist of three values. The value of the second component is . The example then calls the method, and it calls the method three times. The first time, it passes the default equality comparer that is returned by the property. The second time, it passes the default equality comparer that is returned by the property. The third time, it passes the custom `NanComparer` object. As the output from the example shows, the first three method calls return `true`, whereas the fourth call returns `false`. + The following example creates two identical 3-tuple objects whose components consist of three values. The value of the second component is . The example then calls the method, and it calls the method three times. The first time, it passes the default equality comparer that is returned by the property. The second time, it passes the default equality comparer that is returned by the property. The third time, it passes the custom `NanComparer` object. As the output from the example shows, the first three method calls return `true`, whereas the fourth call returns `false`. [!code-csharp[System.Collections.IStructuralEquatable#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.istructuralequatable/cs/nanexample1.cs#2)] [!code-vb[System.Collections.IStructuralEquatable#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.istructuralequatable/vb/nanexample1.vb#2)] diff --git a/xml/System.Collections/Queue.xml b/xml/System.Collections/Queue.xml index 8dbf9f7dabb27..3af6adb592116 100644 --- a/xml/System.Collections/Queue.xml +++ b/xml/System.Collections/Queue.xml @@ -62,7 +62,7 @@ accepts `null` as a valid value and allows duplicate elements. - For the generic version of this collection, see + For the generic version of this collection, see @@ -375,7 +375,7 @@ . + This method determines equality by calling . This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections/ReadOnlyCollectionBase.xml b/xml/System.Collections/ReadOnlyCollectionBase.xml index 464f8fb65c100..16f4be9b810f9 100644 --- a/xml/System.Collections/ReadOnlyCollectionBase.xml +++ b/xml/System.Collections/ReadOnlyCollectionBase.xml @@ -275,7 +275,7 @@ ## Remarks The specified array must be of a compatible type. - This method uses to copy the elements. + This method uses to copy the elements. This method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections/SortedList.xml b/xml/System.Collections/SortedList.xml index d0063adc4d766..681ac3f9af30e 100644 --- a/xml/System.Collections/SortedList.xml +++ b/xml/System.Collections/SortedList.xml @@ -44,7 +44,7 @@ . + For the generic version of this collection, see . A element can be accessed by its key, like an element in any implementation, or by its index, like an element in any implementation. @@ -663,7 +663,7 @@ ## Remarks The elements of a object are sorted by the keys either according to a specific implementation specified when the is created or according to the implementation provided by the keys themselves. - implements . It behaves exactly as . + implements . It behaves exactly as . This method uses a binary search algorithm; therefore, this method is an O(log `n`) operation, where `n` is . diff --git a/xml/System.Collections/Stack.xml b/xml/System.Collections/Stack.xml index 701eb6da2e19b..b80b309ed0cb1 100644 --- a/xml/System.Collections/Stack.xml +++ b/xml/System.Collections/Stack.xml @@ -44,7 +44,7 @@ . + For the generic version of this collection, see . The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. @@ -310,7 +310,7 @@ method. + This method determines equality by calling the method. This method performs a linear search; therefore, this method is an O(`n`) operation, where `n` is . diff --git a/xml/System.Collections/StructuralComparisons.xml b/xml/System.Collections/StructuralComparisons.xml index 1ae448f2c5e51..fe2e707683a14 100644 --- a/xml/System.Collections/StructuralComparisons.xml +++ b/xml/System.Collections/StructuralComparisons.xml @@ -29,9 +29,9 @@ ## Remarks The class returns the following two predefined comparison objects: -- An implementation that can be passed to a method such as or to perform a structural comparison of two objects. It is designed to indicate whether the first object precedes, follows, or occurs in the same position as the second object in the sort order. +- An implementation that can be passed to a method such as or to perform a structural comparison of two objects. It is designed to indicate whether the first object precedes, follows, or occurs in the same position as the second object in the sort order. -- An implementation that can be passed to a method such as or to perform a comparison for structural equality. +- An implementation that can be passed to a method such as or to perform a comparison for structural equality. The objects can be used to perform a structural comparison or a structural equality comparison of two collection objects, such as array or tuple objects. In structural comparison, two objects are compared based on their values. Objects can be ordered based on some criteria, and two objects are considered equal when they have equal values, not because they reference the same physical object @@ -69,7 +69,7 @@ object returned by this property is passed to the comparison method of a collection object, such as or , its method is called for each member of an array or for each component of a tuple. This implementation of the method behaves as follows when it compares each item of a collection object with the corresponding item of another collection object: + When the object returned by this property is passed to the comparison method of a collection object, such as or , its method is called for each member of an array or for each component of a tuple. This implementation of the method behaves as follows when it compares each item of a collection object with the corresponding item of another collection object: - It considers two items that are `null` to be equal, and considers a null item to be less than an item that is not null. @@ -111,13 +111,13 @@ object returned by this property is passed to the equality comparison method of a collection object, such as or , its method is called for each member of an array or for each component of a tuple. This implementation of the method behaves as follows when it compares each item of a collection object with the corresponding item of another collection object: + When the object returned by this property is passed to the equality comparison method of a collection object, such as or , its method is called for each member of an array or for each component of a tuple. This implementation of the method behaves as follows when it compares each item of a collection object with the corresponding item of another collection object: - If both items are `null`, it considers the two items to be equal. - If one item is null but the other item is not, it considers the two items to be unequal. -- If the first item in the comparison can be cast to an object (in other words, if it is a collection object that implements the interface), it calls the method. +- If the first item in the comparison can be cast to an object (in other words, if it is a collection object that implements the interface), it calls the method. - If the first item in the comparison cannot be cast to an object (in other words, if it is not a collection object that implements the interface), it calls the item's `Equals` method. diff --git a/xml/System.ComponentModel.Composition.Hosting/DirectoryCatalog.xml b/xml/System.ComponentModel.Composition.Hosting/DirectoryCatalog.xml index 7075a81418144..b14c34c1aa234 100644 --- a/xml/System.ComponentModel.Composition.Hosting/DirectoryCatalog.xml +++ b/xml/System.ComponentModel.Composition.Hosting/DirectoryCatalog.xml @@ -29,7 +29,7 @@ object to parse the contents of a designated directory. Any attributed parts contained in dynamic link library (DLL) files are extracted and made available through the catalog.To restrict parsing to specific DLLs, you can specify a search pattern by using the same syntax as the method. + You can use a object to parse the contents of a designated directory. Any attributed parts contained in dynamic link library (DLL) files are extracted and made available through the catalog.To restrict parsing to specific DLLs, you can specify a search pattern by using the same syntax as the method. > [!WARNING] > The designated directory should not allow access to non-administrators. For example, using a folder that contains temporary Internet files could create vulnerabilities in your application. diff --git a/xml/System.ComponentModel.Composition/ExportFactory`1.xml b/xml/System.ComponentModel.Composition/ExportFactory`1.xml index a4eefce6a8d0a..bf824c3000da7 100644 --- a/xml/System.ComponentModel.Composition/ExportFactory`1.xml +++ b/xml/System.ComponentModel.Composition/ExportFactory`1.xml @@ -41,7 +41,7 @@ Public myData As String = "Example Data." Public Property theData As ExportFactory(Of String) ``` - The method returns an object, which has two pieces. The property provides access to the created part. Calling the method of the object cleans up the created part and all of its dependencies, thereby allowing the part's lifetime to be managed without reference to the container that created it. + The method returns an object, which has two pieces. The property provides access to the created part. Calling the method of the object cleans up the created part and all of its dependencies, thereby allowing the part's lifetime to be managed without reference to the container that created it. ]]> diff --git a/xml/System.ComponentModel.DataAnnotations/DataTypeAttribute.xml b/xml/System.ComponentModel.DataAnnotations/DataTypeAttribute.xml index e57de7cb8adae..69b0d881c24f7 100644 --- a/xml/System.ComponentModel.DataAnnotations/DataTypeAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/DataTypeAttribute.xml @@ -104,7 +104,7 @@ enumeration. + The name is one of the values that are defined by the enumeration. diff --git a/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml b/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml index f0052eca037bf..487b33c605db9 100644 --- a/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml @@ -193,7 +193,7 @@ Use the property to specify a custom display format for the values that are displayed in the object. If the property is not set, the field's value is displayed without any special formatting. For more information, see [Formatting Types](~/docs/standard/base-types/formatting-types.md). > [!NOTE] -> When the property is `true`, the value of the field is HTML encoded to its string representation before the formatting string is applied. For some objects, such as dates, you might want to control how the object is displayed with a formatting string. In those cases, you must set the property to `false`. +> When the property is `true`, the value of the field is HTML encoded to its string representation before the formatting string is applied. For some objects, such as dates, you might want to control how the object is displayed with a formatting string. In those cases, you must set the property to `false`. By default, the formatting string is applied to the field value only when the data-bound control that contains the object is in read-only mode. To apply the formatting string to field values when they are in edit mode, set the property to `true`. diff --git a/xml/System.ComponentModel.DataAnnotations/RangeAttribute.xml b/xml/System.ComponentModel.DataAnnotations/RangeAttribute.xml index 3078099ebff18..e7ebb8f355f34 100644 --- a/xml/System.ComponentModel.DataAnnotations/RangeAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/RangeAttribute.xml @@ -193,7 +193,7 @@ creates the error message by using the name of the data field that caused the validation failure. You can override this method in a custom validation attribute to customize how errors are created, or to provide a more complex message that contains parameters that you evaluate at run time. For an example, see the constructor. + The creates the error message by using the name of the data field that caused the validation failure. You can override this method in a custom validation attribute to customize how errors are created, or to provide a more complex message that contains parameters that you evaluate at run time. For an example, see the constructor. ]]> diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataConnection.xml b/xml/System.ComponentModel.Design.Data/DesignerDataConnection.xml index e22106ba02db7..03f1ad41d2323 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataConnection.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataConnection.xml @@ -102,7 +102,7 @@ property contains the connection string used by the application for connecting to the data store. You must use the method to return a connection string suitable for use in the design environment. + The property contains the connection string used by the application for connecting to the data store. You must use the method to return a connection string suitable for use in the design environment. ]]> @@ -128,7 +128,7 @@ property will be `true` if the object was read from the application's configuration file, or if the object was written to the application's configuration file by the method. + The property will be `true` if the object was read from the application's configuration file, or if the object was written to the application's configuration file by the method. When the is `true`, the property is set to the name of the connection as defined in the [connectionStrings Element (ASP.NET Settings Schema)](http://msdn.microsoft.com/en-us/b6ffbb2e-a4d1-410e-8f7e-9755e92c65de) of the configuration file. diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataParameter.xml b/xml/System.ComponentModel.Design.Data/DesignerDataParameter.xml index adcdd2dd7a056..5251d28d963ed 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataParameter.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataParameter.xml @@ -18,7 +18,7 @@ ## Remarks The class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. - The class represents the parameters required to call a stored procedure in the data store. The property contains a collection of objects. + The class represents the parameters required to call a stored procedure in the data store. The property contains a collection of objects. ]]> diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataStoredProcedure.xml b/xml/System.ComponentModel.Design.Data/DesignerDataStoredProcedure.xml index d717c83e9b403..d7ad14308bb3c 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataStoredProcedure.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataStoredProcedure.xml @@ -18,7 +18,7 @@ ## Remarks The class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. - The class represents a single table in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . + The class represents a single table in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . ]]> diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataTable.xml b/xml/System.ComponentModel.Design.Data/DesignerDataTable.xml index 5f5292170e3a4..fcf5cca66801b 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataTable.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataTable.xml @@ -18,7 +18,7 @@ ## Remarks The class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. - The class represents a single table in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . + The class represents a single table in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . ]]> diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataView.xml b/xml/System.ComponentModel.Design.Data/DesignerDataView.xml index ae5f6d9ceac81..76137f63de203 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataView.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataView.xml @@ -18,7 +18,7 @@ ## Remarks The class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. - The class represents a single data view in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . + The class represents a single data view in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . ]]> diff --git a/xml/System.ComponentModel.Design.Data/QueryBuilderMode.xml b/xml/System.ComponentModel.Design.Data/QueryBuilderMode.xml index 89f508dee1e3f..928162ead9e67 100644 --- a/xml/System.ComponentModel.Design.Data/QueryBuilderMode.xml +++ b/xml/System.ComponentModel.Design.Data/QueryBuilderMode.xml @@ -15,7 +15,7 @@ enumeration is used when you call the method to indicate the type of query desired. + The enumeration is used when you call the method to indicate the type of query desired. ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/BasicDesignerLoader.xml b/xml/System.ComponentModel.Design.Serialization/BasicDesignerLoader.xml index ce15b09990ba9..181e6331d069d 100644 --- a/xml/System.ComponentModel.Design.Serialization/BasicDesignerLoader.xml +++ b/xml/System.ComponentModel.Design.Serialization/BasicDesignerLoader.xml @@ -84,7 +84,7 @@ method. You do not need to override this method in your own class. The method performs the following actions: + This is an implementation of the abstract method. You do not need to override this method in your own class. The method performs the following actions: - It verifies that the design surface has not already loaded. diff --git a/xml/System.ComponentModel.Design.Serialization/CodeDomDesignerLoader.xml b/xml/System.ComponentModel.Design.Serialization/CodeDomDesignerLoader.xml index ff7f14b07091c..b34cced8009fd 100644 --- a/xml/System.ComponentModel.Design.Serialization/CodeDomDesignerLoader.xml +++ b/xml/System.ComponentModel.Design.Serialization/CodeDomDesignerLoader.xml @@ -187,7 +187,7 @@ method, see . + For more information on the method, see . ]]> @@ -212,7 +212,7 @@ method, see . + For more information on the method, see . ]]> @@ -268,7 +268,7 @@ method, see . + For more information on the method, see . ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/CodeDomSerializerBase.xml b/xml/System.ComponentModel.Design.Serialization/CodeDomSerializerBase.xml index e12534264ea11..0b21561539ddb 100644 --- a/xml/System.ComponentModel.Design.Serialization/CodeDomSerializerBase.xml +++ b/xml/System.ComponentModel.Design.Serialization/CodeDomSerializerBase.xml @@ -412,7 +412,7 @@ method is an extension to the method. The method takes an object type, rather than an object value. If an external party had overridden metadata for a specific object through , that metadata override would not be seen by the method, which only takes a type. The method checks the metadata of the value and the value’s type. If the two differ, will look to see if there is a custom designer serializer attribute on the value. If so, will attempt to use it. Otherwise, it will defer to . + The method is an extension to the method. The method takes an object type, rather than an object value. If an external party had overridden metadata for a specific object through , that metadata override would not be seen by the method, which only takes a type. The method checks the metadata of the value and the value’s type. If the two differ, will look to see if there is a custom designer serializer attribute on the value. If so, will attempt to use it. Otherwise, it will defer to . ]]> @@ -445,7 +445,7 @@ method is an extension to the method. The method takes an object type, rather than an object value. + The method is an extension to the method. The method takes an object type, rather than an object value. ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/CollectionCodeDomSerializer.xml b/xml/System.ComponentModel.Design.Serialization/CollectionCodeDomSerializer.xml index 3f860286f4057..e91d3e759a547 100644 --- a/xml/System.ComponentModel.Design.Serialization/CollectionCodeDomSerializer.xml +++ b/xml/System.ComponentModel.Design.Serialization/CollectionCodeDomSerializer.xml @@ -104,7 +104,7 @@ 2. If the collection is an , the method will cast the collection to an and add through that interface. - 1. If the collection has no *Add* method, but is marked with , will enumerate the collection and serialize each element. + 1. If the collection has no *Add* method, but is marked with , will enumerate the collection and serialize each element. ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/DesignerSerializationManager.xml b/xml/System.ComponentModel.Design.Serialization/DesignerSerializationManager.xml index f4848d8f9c12e..e00c7b8122ad0 100644 --- a/xml/System.ComponentModel.Design.Serialization/DesignerSerializationManager.xml +++ b/xml/System.ComponentModel.Design.Serialization/DesignerSerializationManager.xml @@ -364,7 +364,7 @@ method will search the service provider for an and, if available, it will delegate to that service to resolve the type. If an is not available, will call the method. + The method will search the service provider for an and, if available, it will delegate to that service to resolve the type. If an is not available, will call the method. ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/INameCreationService.xml b/xml/System.ComponentModel.Design.Serialization/INameCreationService.xml index 8406b7598e4dc..b6276a89f88b3 100644 --- a/xml/System.ComponentModel.Design.Serialization/INameCreationService.xml +++ b/xml/System.ComponentModel.Design.Serialization/INameCreationService.xml @@ -76,7 +76,7 @@ ## Examples - The following code example provides an example method implementation. The method can create a name based on the name of a specified type that is unique to the names of the components within the specified container. + The following code example provides an example method implementation. The method can create a name based on the name of a specified type that is unique to the names of the components within the specified container. [!code-cpp[INameCreationServiceExample#2](~/samples/snippets/cpp/VS_Snippets_Winforms/INameCreationServiceExample/CPP/class1.cpp#2)] [!code-csharp[INameCreationServiceExample#2](~/samples/snippets/csharp/VS_Snippets_Winforms/INameCreationServiceExample/CS/class1.cs#2)] @@ -127,7 +127,7 @@ ## Examples - The following code example provides an example method implementation. The method uses a string validation scheme that examines each character of the specified string to determine whether the specified string is a valid name. The method returns `true` if the string is valid, or `false` otherwise. + The following code example provides an example method implementation. The method uses a string validation scheme that examines each character of the specified string to determine whether the specified string is a valid name. The method returns `true` if the string is valid, or `false` otherwise. [!code-cpp[INameCreationServiceExample#3](~/samples/snippets/cpp/VS_Snippets_Winforms/INameCreationServiceExample/CPP/class1.cpp#3)] [!code-csharp[INameCreationServiceExample#3](~/samples/snippets/csharp/VS_Snippets_Winforms/INameCreationServiceExample/CS/class1.cs#3)] @@ -175,7 +175,7 @@ ## Examples - The following code example provides an example method implementation that uses a string validation scheme that examines each character of the specified string to determine whether the specified string is a valid name. The method throws an exception if the string is not valid. + The following code example provides an example method implementation that uses a string validation scheme that examines each character of the specified string to determine whether the specified string is a valid name. The method throws an exception if the string is not valid. [!code-cpp[INameCreationServiceExample#4](~/samples/snippets/cpp/VS_Snippets_Winforms/INameCreationServiceExample/CPP/class1.cpp#4)] [!code-csharp[INameCreationServiceExample#4](~/samples/snippets/csharp/VS_Snippets_Winforms/INameCreationServiceExample/CS/class1.cs#4)] diff --git a/xml/System.ComponentModel.Design.Serialization/MemberRelationship.xml b/xml/System.ComponentModel.Design.Serialization/MemberRelationship.xml index 1d69d3442de7d..6a975c3fd340b 100644 --- a/xml/System.ComponentModel.Design.Serialization/MemberRelationship.xml +++ b/xml/System.ComponentModel.Design.Serialization/MemberRelationship.xml @@ -241,7 +241,7 @@ Tests whether two specified structures are equivalent. This operator returns if the two structures are equal; otherwise, . - .]]> + .]]> @@ -276,7 +276,7 @@ Tests whether two specified structures are different. This operator returns if the two structures are different; otherwise, . - .]]> + .]]> diff --git a/xml/System.ComponentModel.Design.Serialization/TypeCodeDomSerializer.xml b/xml/System.ComponentModel.Design.Serialization/TypeCodeDomSerializer.xml index 6aff7d09b9245..cd4746c790997 100644 --- a/xml/System.ComponentModel.Design.Serialization/TypeCodeDomSerializer.xml +++ b/xml/System.ComponentModel.Design.Serialization/TypeCodeDomSerializer.xml @@ -115,7 +115,7 @@ method returns the method to emit all of the initialization code for the given member. The default implementation returns an empty constructor. If the same method is to be returned for multiple values, the same instance of the method should be returned. You can use the dictionary to remember methods you have created. The `typeDecl` parameter can also be used to add infrastructure methods. For example, if you want to emit a separate method for each object, you need a single method that calls all of these methods in turn. This method can be added to the code type declaration as needed. + The method returns the method to emit all of the initialization code for the given member. The default implementation returns an empty constructor. If the same method is to be returned for multiple values, the same instance of the method should be returned. You can use the dictionary to remember methods you have created. The `typeDecl` parameter can also be used to add infrastructure methods. For example, if you want to emit a separate method for each object, you need a single method that calls all of these methods in turn. This method can be added to the code type declaration as needed. ]]> diff --git a/xml/System.ComponentModel.Design/ArrayEditor.xml b/xml/System.ComponentModel.Design/ArrayEditor.xml index fb6f87f7d810e..5c998c4cbdcbf 100644 --- a/xml/System.ComponentModel.Design/ArrayEditor.xml +++ b/xml/System.ComponentModel.Design/ArrayEditor.xml @@ -21,7 +21,7 @@ ## Examples - The following code example demonstrates applying the to a property. + The following code example demonstrates applying the to a property. [!code-cpp[ArrayEditorExample#1](~/samples/snippets/cpp/VS_Snippets_Winforms/ArrayEditorExample/CPP/class1.cpp#1)] [!code-csharp[ArrayEditorExample#1](~/samples/snippets/csharp/VS_Snippets_Winforms/ArrayEditorExample/CS/class1.cs#1)] diff --git a/xml/System.ComponentModel.Design/ComponentDesigner.xml b/xml/System.ComponentModel.Design/ComponentDesigner.xml index ad23ddcb92c96..086d809dfda86 100644 --- a/xml/System.ComponentModel.Design/ComponentDesigner.xml +++ b/xml/System.ComponentModel.Design/ComponentDesigner.xml @@ -37,7 +37,7 @@ The class implements a special behavior for the property descriptors of inherited components. An internal type named `InheritedPropertyDescriptor` is used by the default implementation to stand in for properties that are inherited from a base class. There are two cases in which these property descriptors are added. -1. To the root object itself, which is returned by the property, because you are inheriting from its base class. +1. To the root object itself, which is returned by the property, because you are inheriting from its base class. 2. To fields found in the base class of the root object. Public and protected fields from the base class are added to the designer so that they can be manipulated by the user. @@ -256,9 +256,9 @@ and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. + This method overrides and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. - Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). diff --git a/xml/System.ComponentModel.Design/DesignerActionItem.xml b/xml/System.ComponentModel.Design/DesignerActionItem.xml index a056904dee578..f6ae1975b6251 100644 --- a/xml/System.ComponentModel.Design/DesignerActionItem.xml +++ b/xml/System.ComponentModel.Design/DesignerActionItem.xml @@ -208,7 +208,7 @@ ## Remarks The property allows the programmer to store arbitrary data within an item. The standard properties for this class, such as and , are not stored in this collection. - The type of this property is actually . + The type of this property is actually . ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionList.xml b/xml/System.ComponentModel.Design/DesignerActionList.xml index f60c6647206ef..c47b1bc74b93e 100644 --- a/xml/System.ComponentModel.Design/DesignerActionList.xml +++ b/xml/System.ComponentModel.Design/DesignerActionList.xml @@ -100,7 +100,7 @@ ## Remarks If the property value is set to `true`, the component with which this is associated will automatically expand and display the smart tag panel when the component is created. - You can opt out of this behavior by setting the property to `false`. + You can opt out of this behavior by setting the property to `false`. diff --git a/xml/System.ComponentModel.Design/DesignerActionListCollection.xml b/xml/System.ComponentModel.Design/DesignerActionListCollection.xml index d8627912bc481..4ec76dcb1ba09 100644 --- a/xml/System.ComponentModel.Design/DesignerActionListCollection.xml +++ b/xml/System.ComponentModel.Design/DesignerActionListCollection.xml @@ -35,7 +35,7 @@ The designer infrastructure constructs a panel by creating a smart tag panel, whose constructor takes two parameters of type . The collections of lists, which contain the pulled and pushed items, are merged into one panel. - Because it derives from the class, uses an internal to store its collection of objects. + Because it derives from the class, uses an internal to store its collection of objects. @@ -298,7 +298,7 @@ class uses a to contain its collection of objects. + Internally, the class uses a to contain its collection of objects. ]]> @@ -331,7 +331,7 @@ ## Remarks If the `index` parameter is equal to the value of the property, the new element is added to the end of the collection. - Internally, the class uses a to contain its collection of objects. Because lists maintain contiguous elements, the elements that follow the insertion point move down to accommodate the new element. This rearrangement changes the index of the elements after the insertion point. + Internally, the class uses a to contain its collection of objects. Because lists maintain contiguous elements, the elements that follow the insertion point move down to accommodate the new element. This rearrangement changes the index of the elements after the insertion point. ]]> @@ -506,7 +506,7 @@ class uses a to contain its collection of objects. Since lists maintain contiguous elements, the elements that follow the removal point move up to occupy the vacated spot. This rearrangement changes the index of the elements after the removal point. + Internally, the class uses a to contain its collection of objects. Since lists maintain contiguous elements, the elements that follow the removal point move up to occupy the vacated spot. This rearrangement changes the index of the elements after the removal point. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionListsChangedEventArgs.xml b/xml/System.ComponentModel.Design/DesignerActionListsChangedEventArgs.xml index 2a8ce2545cba1..1878ed207605e 100644 --- a/xml/System.ComponentModel.Design/DesignerActionListsChangedEventArgs.xml +++ b/xml/System.ComponentModel.Design/DesignerActionListsChangedEventArgs.xml @@ -124,7 +124,7 @@ ## Remarks The property enables the programmer to associate an object to an instance of the class. - For the event, the property should always reference the that the is associated with. + For the event, the property should always reference the that the is associated with. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionListsChangedEventHandler.xml b/xml/System.ComponentModel.Design/DesignerActionListsChangedEventHandler.xml index a372056636461..ec1f49e52ea71 100644 --- a/xml/System.ComponentModel.Design/DesignerActionListsChangedEventHandler.xml +++ b/xml/System.ComponentModel.Design/DesignerActionListsChangedEventHandler.xml @@ -31,7 +31,7 @@ ## Remarks The event model in the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] is based on having an event delegate that connects an event with its handler. To raise a event, two elements are needed: -- The class, derived from , which holds the event data. +- The class, derived from , which holds the event data. - The delegate, which points to a method that provides the response to the event. diff --git a/xml/System.ComponentModel.Design/DesignerActionMethodItem.xml b/xml/System.ComponentModel.Design/DesignerActionMethodItem.xml index 8321f004b058f..270626b7aab70 100644 --- a/xml/System.ComponentModel.Design/DesignerActionMethodItem.xml +++ b/xml/System.ComponentModel.Design/DesignerActionMethodItem.xml @@ -352,7 +352,7 @@ ## Remarks The property allows another component to lend its smart tag panel items to the current list. For example, a user control might aggregate the items from one of its constituent standard controls. - This property works in conjunction with the property. + This property works in conjunction with the property. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionPropertyItem.xml b/xml/System.ComponentModel.Design/DesignerActionPropertyItem.xml index 3fe9c1c803924..86c6ef99cad65 100644 --- a/xml/System.ComponentModel.Design/DesignerActionPropertyItem.xml +++ b/xml/System.ComponentModel.Design/DesignerActionPropertyItem.xml @@ -29,7 +29,7 @@ |Boolean value|The item is displayed using a binary UI, such as a check mark.| |None of the above.|The item is displayed as a non-editable text string using the data type's method.| - All fundamental types, such as , and common [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] data types, such as , supply standard type converters and editors. For more information about type converters, see [How to: Implement a Type Converter](http://msdn.microsoft.com/library/90373a3f-d8c8-492d-841c-945d62393c56) or [Generalized Type Conversion](http://msdn.microsoft.com/library/49253ae6-7657-4810-82ab-1176a6feeada). For more information about type editors, see [How to: Implement a UI Type Editor](http://msdn.microsoft.com/library/ed961fb9-ee02-4666-b511-05f3204bb75c). + All fundamental types, such as , and common [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] data types, such as , supply standard type converters and editors. For more information about type converters, see [How to: Implement a Type Converter](http://msdn.microsoft.com/library/90373a3f-d8c8-492d-841c-945d62393c56) or [Generalized Type Conversion](http://msdn.microsoft.com/library/49253ae6-7657-4810-82ab-1176a6feeada). For more information about type editors, see [How to: Implement a UI Type Editor](http://msdn.microsoft.com/library/ed961fb9-ee02-4666-b511-05f3204bb75c). @@ -194,7 +194,7 @@ ## Remarks With the property, another component can lend its pull-model panel items to the current list. For example, a user control might aggregate the objects from one or more of its constituent controls. - This property works in conjunction with the property. + This property works in conjunction with the property. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionService.xml b/xml/System.ComponentModel.Design/DesignerActionService.xml index c07ef57678547..caa2f693dba58 100644 --- a/xml/System.ComponentModel.Design/DesignerActionService.xml +++ b/xml/System.ComponentModel.Design/DesignerActionService.xml @@ -78,7 +78,7 @@ ## Remarks A service provider is necessary for monitoring selection and component changes. It is expected to support the and types. The class uses an internal table to manage components and their associated smart tags. - Typically, component developers will not need to create an instance of this class; instead, they can acquire an existing instance through a call to the method. + Typically, component developers will not need to create an instance of this class; instead, they can acquire an existing instance through a call to the method. ]]> @@ -110,7 +110,7 @@ ## Remarks The method represents the push model of adding smart tag items. The alternate pull model relies on overriding the property in the designer for the corresponding component. - When this method is called, the lists to be added are scanned for any with the property set to `true`. These items are added to the list of designer verbs for this component, through a call to the method. + When this method is called, the lists to be added are scanned for any with the property set to `true`. These items are added to the list of designer verbs for this component, through a call to the method. Smart tags are managed on a component instance basis. The managed collection may contain duplicate entries. @@ -147,7 +147,7 @@ ## Remarks The method represents the push model of adding smart tag items. The alternate pull model relies on overriding the property in the designer for the corresponding component. - When this method is called, the lists to be added are scanned for any with the property set to `true`. These items are added to the list of designer verbs for this component, through a call to the method. + When this method is called, the lists to be added are scanned for any with the property set to `true`. These items are added to the list of designer verbs for this component, through a call to the method. Smart tags are managed on a component instance basis. The managed collection may contain duplicate entries. diff --git a/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventArgs.xml b/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventArgs.xml index 4caadc54b4048..60c930ce7c039 100644 --- a/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventArgs.xml +++ b/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventArgs.xml @@ -43,7 +43,7 @@ event, the `relatedObject` parameter always references the that the panel is associated with. + For the event, the `relatedObject` parameter always references the that the panel is associated with. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventHandler.xml b/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventHandler.xml index eb52731aa3088..52a1964f93ad9 100644 --- a/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventHandler.xml +++ b/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventHandler.xml @@ -26,7 +26,7 @@ ## Remarks The event model in the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] is based on having an event delegate that connects an event with its handler. To raise a event, two elements are needed: -- The class, derived from , which holds the event data. +- The class, derived from , which holds the event data. - The delegate, which points to a method that provides the response to the event. diff --git a/xml/System.ComponentModel.Design/DesignerCommandSet.xml b/xml/System.ComponentModel.Design/DesignerCommandSet.xml index 5a35906849edf..4cd6568f4768d 100644 --- a/xml/System.ComponentModel.Design/DesignerCommandSet.xml +++ b/xml/System.ComponentModel.Design/DesignerCommandSet.xml @@ -26,7 +26,7 @@ ||Gets the collection of all the smart tags associated with the designed component. The base implementation simply calls .| ||Gets the collection of all the designer verbs associated with the designed component. The base implementation simply calls .| - A should be added as a site-specific service. Externally, a service of this type should first be queried to discover smart tag and designer verb functionality. If this service is not found, then the property should be used instead. This procedure provides a path for backwards compatibility. + A should be added as a site-specific service. Externally, a service of this type should first be queried to discover smart tag and designer verb functionality. If this service is not found, then the property should be used instead. This procedure provides a path for backwards compatibility. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerTransaction.xml b/xml/System.ComponentModel.Design/DesignerTransaction.xml index 2a76d2f21cada..7139ea9db424b 100644 --- a/xml/System.ComponentModel.Design/DesignerTransaction.xml +++ b/xml/System.ComponentModel.Design/DesignerTransaction.xml @@ -387,9 +387,9 @@ using (host.CreateTransaction() { and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. + This method overrides and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. - Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). diff --git a/xml/System.ComponentModel.Design/HelpKeywordAttribute.xml b/xml/System.ComponentModel.Design/HelpKeywordAttribute.xml index 6fb01ce0ad275..b4b5c6d3a2b67 100644 --- a/xml/System.ComponentModel.Design/HelpKeywordAttribute.xml +++ b/xml/System.ComponentModel.Design/HelpKeywordAttribute.xml @@ -30,11 +30,11 @@ property value. For members, the Help keyword is given by the full name of the type that declared the property, plus the property name itself. + By default, the Help keyword for a class is given by the property value. For members, the Help keyword is given by the full name of the type that declared the property, plus the property name itself. - For example, consider the property on the control. The class keyword is "System.Windows.Forms.Button", but the property keyword is "System.Windows.Forms.Control.Text", because the property is declared on the class, rather than the class itself; the class inherits the property. + For example, consider the property on the control. The class keyword is "System.Windows.Forms.Button", but the property keyword is "System.Windows.Forms.Control.Text", because the property is declared on the class, rather than the class itself; the class inherits the property. - By contrast, the property is declared on the class, so its keyword is "System.Windows.Forms.Button.DialogResult". + By contrast, the property is declared on the class, so its keyword is "System.Windows.Forms.Button.DialogResult". When the Help system gets the keywords, it will first look at . At the class level, it will return the string specified by the . This will not be used for members of the type in question, which will still reflect the declaring type's actual full name, plus the member name. This attribute supports strongly typed classes that have associated common documentation but distinct Help IDs. diff --git a/xml/System.ComponentModel.Design/IComponentDiscoveryService.xml b/xml/System.ComponentModel.Design/IComponentDiscoveryService.xml index 679b899adf252..5a9735ae1766e 100644 --- a/xml/System.ComponentModel.Design/IComponentDiscoveryService.xml +++ b/xml/System.ComponentModel.Design/IComponentDiscoveryService.xml @@ -76,7 +76,7 @@ When you pass in a value for the `designerHost` parameter, type resolution is scoped to `designerHost`. This means that if there is a whose type is on disk, and not in the global assembly cache, its type will fail to load through `designerHost`. - If you pass in `null` for `designerHost`, it returns all types that can be queried from the global assembly cache or the method. + If you pass in `null` for `designerHost`, it returns all types that can be queried from the global assembly cache or the method. diff --git a/xml/System.ComponentModel.Design/IInheritanceService.xml b/xml/System.ComponentModel.Design/IInheritanceService.xml index 5f15e210507a2..e25a93dbf9031 100644 --- a/xml/System.ComponentModel.Design/IInheritanceService.xml +++ b/xml/System.ComponentModel.Design/IInheritanceService.xml @@ -101,7 +101,7 @@ method, this method returns the value . Otherwise, it returns the inheritance attribute for this component. + If the component has been profiled by the method, this method returns the value . Otherwise, it returns the inheritance attribute for this component. You should call on the specified component or a parent of the specified component before attempting to obtain an that reflects the inheritance level of the specified component. diff --git a/xml/System.ComponentModel.Design/IRootDesigner.xml b/xml/System.ComponentModel.Design/IRootDesigner.xml index d0b330e9ae9e1..c511e1fac53b1 100644 --- a/xml/System.ComponentModel.Design/IRootDesigner.xml +++ b/xml/System.ComponentModel.Design/IRootDesigner.xml @@ -86,7 +86,7 @@ This method returns a view object that can present a user interface to the user. The returned data type is an , because there can be a variety of different user interface technologies. Development environments typically support more than one technology. > [!NOTE] -> The and fields are obsolete. Use for new designer implementations. +> The and fields are obsolete. Use for new designer implementations. ]]> @@ -124,7 +124,7 @@ The enumeration indicates the supported view technologies. > [!NOTE] -> The and fields are obsolete. Use for new designer implementations. +> The and fields are obsolete. Use for new designer implementations. ]]> diff --git a/xml/System.ComponentModel.Design/ViewTechnology.xml b/xml/System.ComponentModel.Design/ViewTechnology.xml index 9e6909e673225..db18af977fe5d 100644 --- a/xml/System.ComponentModel.Design/ViewTechnology.xml +++ b/xml/System.ComponentModel.Design/ViewTechnology.xml @@ -81,7 +81,7 @@ instance. + The root designer may return any type of object, but the object must be compatible with an adapter for the technology of the host. Hosting environments such as [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] provide a way to plug in new view technology adapters. The default view object for the Windows Forms designer is a instance. diff --git a/xml/System.ComponentModel/AddingNewEventArgs.xml b/xml/System.ComponentModel/AddingNewEventArgs.xml index 33c06a5d1c0b3..c009610cbb8c2 100644 --- a/xml/System.ComponentModel/AddingNewEventArgs.xml +++ b/xml/System.ComponentModel/AddingNewEventArgs.xml @@ -25,18 +25,18 @@ class provides data for the event, which signals that an item is about to be added to a collection. The event gives the programmer, within the event handler , the option of supplying the new object by setting the property to this new item. If this property is not set, the collection will typically use the default constructor of the appropriate type to construct a new item. In either case, the new item will be added to the collection. + The class provides data for the event, which signals that an item is about to be added to a collection. The event gives the programmer, within the event handler , the option of supplying the new object by setting the property to this new item. If this property is not set, the collection will typically use the default constructor of the appropriate type to construct a new item. In either case, the new item will be added to the collection. If the collection also implements the interface, the item will be provisionally added, waiting a subsequent commit or rollback. - This event is commonly used in data-binding scenarios, within classes such as and . + This event is commonly used in data-binding scenarios, within classes such as and . For more information about handling events, see [NIB: Consuming Events](http://msdn.microsoft.com/en-us/01e4f1bc-e55e-413f-98c7-6588493e5f67). ## Examples - The following code example demonstrates how to use the class to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](~/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md). + The following code example demonstrates how to use the class to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](~/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md). [!code-cpp[System.Windows.Forms.DataConnector.AddingNew#8](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CPP/form1.cpp#8)] [!code-csharp[System.Windows.Forms.DataConnector.AddingNew#8](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CS/form1.cs#8)] @@ -144,7 +144,7 @@ ## Examples - The following code example demonstrates how to use the class to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](~/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md). + The following code example demonstrates how to use the class to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](~/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md). [!code-cpp[System.Windows.Forms.DataConnector.AddingNew#8](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CPP/form1.cpp#8)] [!code-csharp[System.Windows.Forms.DataConnector.AddingNew#8](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CS/form1.cs#8)] diff --git a/xml/System.ComponentModel/AddingNewEventHandler.xml b/xml/System.ComponentModel/AddingNewEventHandler.xml index f237a0d1c85d2..98b6aae5e2c5e 100644 --- a/xml/System.ComponentModel/AddingNewEventHandler.xml +++ b/xml/System.ComponentModel/AddingNewEventHandler.xml @@ -33,16 +33,16 @@ event occurs prior to adding a new item to a collection, typically in data-binding scenarios. The handler of this event can supply the new item to be added, overriding the standard action of the collection class. This is accomplished by setting the property of the parameter `e` to this new item. Typically this item must be of a type expected by the recipient collection, or the collection will throw an exception of type . + The event occurs prior to adding a new item to a collection, typically in data-binding scenarios. The handler of this event can supply the new item to be added, overriding the standard action of the collection class. This is accomplished by setting the property of the parameter `e` to this new item. Typically this item must be of a type expected by the recipient collection, or the collection will throw an exception of type . - This event is commonly used in data-binding scenarios, within classes such as and . + This event is commonly used in data-binding scenarios, within classes such as and . When you create an delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [NIB: Events and Delegates](http://msdn.microsoft.com/en-us/d98fd58b-fa4f-4598-8378-addf4355a115). ## Examples - The following code example demonstrates how to use the delegate to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](~/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md). + The following code example demonstrates how to use the delegate to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](~/docs/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource.md). [!code-cpp[System.Windows.Forms.DataConnector.AddingNew#8](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CPP/form1.cpp#8)] [!code-csharp[System.Windows.Forms.DataConnector.AddingNew#8](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CS/form1.cs#8)] diff --git a/xml/System.ComponentModel/AmbientValueAttribute.xml b/xml/System.ComponentModel/AmbientValueAttribute.xml index eeee6bf69591d..41ffbfb6cd083 100644 --- a/xml/System.ComponentModel/AmbientValueAttribute.xml +++ b/xml/System.ComponentModel/AmbientValueAttribute.xml @@ -30,9 +30,9 @@ property or a property. + If a property on a control has ambient behavior, this attribute must be present. Ambient properties query their parent for their value, for example, a property or a property. - Typically, a visual designer uses the attribute to decide which value to persist for a property. This is usually a value that causes the property to get its value from another source. An example of an ambient value is as the ambient value for the property. If you have a control on a form and the property of the control is set to a different color than the property of the form, you can reset the property of the control to that of the form by setting the of the control to . + Typically, a visual designer uses the attribute to decide which value to persist for a property. This is usually a value that causes the property to get its value from another source. An example of an ambient value is as the ambient value for the property. If you have a control on a form and the property of the control is set to a different color than the property of the form, you can reset the property of the control to that of the form by setting the of the control to . diff --git a/xml/System.ComponentModel/AsyncCompletedEventArgs.xml b/xml/System.ComponentModel/AsyncCompletedEventArgs.xml index 95bb63b4f2835..144d88681cbfe 100644 --- a/xml/System.ComponentModel/AsyncCompletedEventArgs.xml +++ b/xml/System.ComponentModel/AsyncCompletedEventArgs.xml @@ -26,7 +26,7 @@ delegate to the event, you will receive information about the outcome of asynchronous operations in the parameter of the corresponding event-handler method. + If you are using a class that implements the [Event-based Asynchronous Pattern Overview](~/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md), the class will provide a *MethodName*`Completed` event. If you add an instance of the delegate to the event, you will receive information about the outcome of asynchronous operations in the parameter of the corresponding event-handler method. The client application's event-handler delegate can check the property to determine if the asynchronous task was cancelled. @@ -37,7 +37,7 @@ ## Examples - The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. [!code-csharp[System.ComponentModel.AsyncOperationManager#11](~/samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#11)] [!code-vb[System.ComponentModel.AsyncOperationManager#11](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb#11)] @@ -146,7 +146,7 @@ ## Examples - The following code example demonstrates the using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + The following code example demonstrates the using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. [!code-csharp[System.ComponentModel.AsyncOperationManager#11](~/samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#11)] [!code-vb[System.ComponentModel.AsyncOperationManager#11](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb#11)] @@ -196,7 +196,7 @@ ## Examples - The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. [!code-csharp[System.ComponentModel.AsyncOperationManager#11](~/samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#11)] [!code-vb[System.ComponentModel.AsyncOperationManager#11](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb#11)] @@ -290,7 +290,7 @@ ## Examples - The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. [!code-csharp[System.ComponentModel.AsyncOperationManager#11](~/samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#11)] [!code-vb[System.ComponentModel.AsyncOperationManager#11](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb#11)] diff --git a/xml/System.ComponentModel/AsyncCompletedEventHandler.xml b/xml/System.ComponentModel/AsyncCompletedEventHandler.xml index 6e8580d268faf..f93be086f78f5 100644 --- a/xml/System.ComponentModel/AsyncCompletedEventHandler.xml +++ b/xml/System.ComponentModel/AsyncCompletedEventHandler.xml @@ -38,12 +38,12 @@ For an asynchronous method, called *MethodName*, in your component, you will have a corresponding *MethodName*`Completed` event, and an optional *MethodName*`CompletedEventArgs` class. - For a component that supports multiple concurrent invocations of its asynchronous methods, the client can supply a unique token, or task ID, to distinguish which asynchronous task is raising particular events. The client's can read the property to determine which task is reporting completion. Your implementation should use the to create an that associates the client's task IDs with pending asynchronous tasks. + For a component that supports multiple concurrent invocations of its asynchronous methods, the client can supply a unique token, or task ID, to distinguish which asynchronous task is raising particular events. The client's can read the property to determine which task is reporting completion. Your implementation should use the to create an that associates the client's task IDs with pending asynchronous tasks. ## Examples - For a code example of the delegate, see the example in the class. + For a code example of the delegate, see the example in the class. ]]> diff --git a/xml/System.ComponentModel/AsyncOperation.xml b/xml/System.ComponentModel/AsyncOperation.xml index ac513e5f5b812..2da10e227920d 100644 --- a/xml/System.ComponentModel/AsyncOperation.xml +++ b/xml/System.ComponentModel/AsyncOperation.xml @@ -34,12 +34,12 @@ - To indicate that an asynchronous task has completed, or to cancel a pending asynchronous task, call . - Your class should get an object for each asynchronous task by calling when each task starts. To allow the client to distinguish separate asynchronous tasks, takes a parameter for a unique client-provided token, which becomes the property. It can then be used by client code to identify the particular asynchronous task that is raising progress or completion events. + Your class should get an object for each asynchronous task by calling when each task starts. To allow the client to distinguish separate asynchronous tasks, takes a parameter for a unique client-provided token, which becomes the property. It can then be used by client code to identify the particular asynchronous task that is raising progress or completion events. ## Examples - The following code example demonstrates using an object to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + The following code example demonstrates using an object to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. For a full code listing, see [How to: Implement a Component That Supports the Event-based Asynchronous Pattern](http://msdn.microsoft.com/library/3c1aa4d4-da87-4a03-b812-3d167b8c57cf). For a full code listing of a client form, see [How to: Implement a Client of the Event-based Asynchronous Pattern](~/docs/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern.md). @@ -156,12 +156,12 @@ The `d` parameter wraps the delegate you want called when you want to post an update about the status of the asynchronous task. The object will ensure that your delegate is invoked on the thread or context appropriate for the application model. Your method can optionally raise an event that notifies clients of a status change, progress update, or newly available incremental results. - The `arg` parameter should be used to pass state to the delegate wrapped by the `d` parameter. It might be a reference to an , or it might be a object. It may be desirable to derive your own class from to provide additional state storage. + The `arg` parameter should be used to pass state to the delegate wrapped by the `d` parameter. It might be a reference to an , or it might be a object. It may be desirable to derive your own class from to provide additional state storage. ## Examples - The following code example demonstrates using the method for reporting progress and incremental results of an asynchronous operation. This code example is part of a larger example provided for the class. + The following code example demonstrates using the method for reporting progress and incremental results of an asynchronous operation. This code example is part of a larger example provided for the class. [!code-csharp[System.ComponentModel.AsyncOperationManager#5](~/samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#5)] @@ -222,12 +222,12 @@ The `d` parameter wraps the delegate you want your class to call when the task's lifetime ends due to completion, cancellation, or failure of the task. The object will ensure that your delegate is invoked on the thread or context appropriate for the application model. Your delegate can optionally raise an event that notifies clients that the asynchronous task's lifetime has ended. - The `arg` parameter is used to pass state information to the completion delegate `d`. You can use an object, or an object as the parameter value. Alternatively, if you want to provide additional state storage, you can use an instance of a class you derive from the class. + The `arg` parameter is used to pass state information to the completion delegate `d`. You can use an object, or an object as the parameter value. Alternatively, if you want to provide additional state storage, you can use an instance of a class you derive from the class. ## Examples - The following code example demonstrates using the method to end the lifetime of an asynchronous operation. This code example is part of a larger example provided for the class. + The following code example demonstrates using the method to end the lifetime of an asynchronous operation. This code example is part of a larger example provided for the class. [!code-csharp[System.ComponentModel.AsyncOperationManager#4](~/samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#4)] @@ -303,7 +303,7 @@ that will act as a task ID. You will use this task ID when you call the , method and this will associate the client's task ID with a particular invocation of your asynchronous operation. This task ID is made available to your implementation through the property. + If your class supports multiple asynchronous methods or multiple invocations of a single asynchronous method, clients will need a way to determine which asynchronous task is raising events. Your `MethodNameAsync` method should take a parameter of type that will act as a task ID. You will use this task ID when you call the , method and this will associate the client's task ID with a particular invocation of your asynchronous operation. This task ID is made available to your implementation through the property. > [!CAUTION] > Client code must be careful to provide a unique value for the property. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and raise an if one is detected. @@ -311,7 +311,7 @@ ## Examples - The following code example demonstrates using to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + The following code example demonstrates using to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. [!code-csharp[System.ComponentModel.AsyncOperationManager#4](~/samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#4)] diff --git a/xml/System.ComponentModel/AsyncOperationManager.xml b/xml/System.ComponentModel/AsyncOperationManager.xml index f47c1840c4414..ed0feee8194b6 100644 --- a/xml/System.ComponentModel/AsyncOperationManager.xml +++ b/xml/System.ComponentModel/AsyncOperationManager.xml @@ -28,7 +28,7 @@ ## Remarks If your class needs to provide asynchronous behavior according to the [Event-based Asynchronous Pattern Overview](~/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md), you will encounter a number of concurrency management issues. Among these is the requirement to ensure that event handlers are called on a thread or context that is appropriate for the application model (for example, Windows Forms applications, [!INCLUDE[vstecasp](~/includes/vstecasp-md.md)] applications, console applications, and so on). The provides a convenient way to create a class that runs properly under all application models supported by the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)]. - The class has one method, , which returns an that can be used to track the duration of a particular asynchronous task. The for a task can be used to alert clients when a task completes. It can also be used to post progress updates and incremental results without terminating the operation. + The class has one method, , which returns an that can be used to track the duration of a particular asynchronous task. The for a task can be used to alert clients when a task completes. It can also be used to post progress updates and incremental results without terminating the operation. For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](~/docs/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern.md). @@ -79,21 +79,21 @@ method returns an that you can use to track the duration of a particular asynchronous operation and to alert the application model when the operation completes. You can also use it to post progress updates and incremental results without terminating the operation. The will correctly marshal these calls to the appropriate thread or context for the application model. + The method returns an that you can use to track the duration of a particular asynchronous operation and to alert the application model when the operation completes. You can also use it to post progress updates and incremental results without terminating the operation. The will correctly marshal these calls to the appropriate thread or context for the application model. If you implement a class that supports the Event-based Asynchronous Pattern, your class should call each time your *MethodName*`Async` method is called. The client application that makes calls to the method can use the `userSuppliedState` parameter to uniquely identify each invocation, so as to distinguish events raised during the execution of the asynchronous operation. > [!CAUTION] -> Client code must provide a unique value for the `userSuppliedState` parameter. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and throw an if one is detected. +> Client code must provide a unique value for the `userSuppliedState` parameter. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and throw an if one is detected. - Your code should track every returned by and use the object in the corresponding underlying asynchronous operation to post updates and terminate the operation. This tracking can be as simple as passing the as a parameter among delegates. In more sophisticated designs, your class can maintain a collection of objects, adding objects when tasks are started and removing them when tasks are completed or canceled. This approach allows you to check for unique `userSuppliedState` parameter values, and is the method you should use when working with classes that support multiple concurrent invocations. + Your code should track every returned by and use the object in the corresponding underlying asynchronous operation to post updates and terminate the operation. This tracking can be as simple as passing the as a parameter among delegates. In more sophisticated designs, your class can maintain a collection of objects, adding objects when tasks are started and removing them when tasks are completed or canceled. This approach allows you to check for unique `userSuppliedState` parameter values, and is the method you should use when working with classes that support multiple concurrent invocations. For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](~/docs/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern.md). ## Examples - The following code example demonstrates using the method to create an for tracking the duration of asynchronous operations. This code example is part of a larger example provided for the class. + The following code example demonstrates using the method to create an for tracking the duration of asynchronous operations. This code example is part of a larger example provided for the class. [!code-csharp[System.ComponentModel.AsyncOperationManager#3](~/samples/snippets/csharp/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/CS/primenumbercalculatormain.cs#3)] [!code-vb[System.ComponentModel.AsyncOperationManager#3](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.ComponentModel.AsyncOperationManager/VB/primenumbercalculatormain.vb#3)] diff --git a/xml/System.ComponentModel/AttributeProviderAttribute.xml b/xml/System.ComponentModel/AttributeProviderAttribute.xml index 39047597d2a4e..a5ec468717bbf 100644 --- a/xml/System.ComponentModel/AttributeProviderAttribute.xml +++ b/xml/System.ComponentModel/AttributeProviderAttribute.xml @@ -31,9 +31,9 @@ property is typed as `object`. The reason for this is that this property can accept several types of input. Unfortunately, this provides no common place to add metadata to describe the characteristics of the property. Each `DataSource` property throughout the .NET Framework needs to have identical metadata for type converters, UI type editors, and other services that require metadata. The remedies this situation. + There are a few cases in the .NET Framework object model where a property is purposely typed to be vague. For example, the property is typed as `object`. The reason for this is that this property can accept several types of input. Unfortunately, this provides no common place to add metadata to describe the characteristics of the property. Each `DataSource` property throughout the .NET Framework needs to have identical metadata for type converters, UI type editors, and other services that require metadata. The remedies this situation. - Once this attribute is placed on a property, the rules for obtaining attributes for the property descriptor's collection differ. Typically, the property descriptor gathers local attributes, and then merges these with attributes from the property type. In this case, the attributes are taken from the type returned from the , not from the actual property type. This attribute is used on to point the object's specific type to , and the appropriate metadata is placed on to enable data binding. In so doing, external parties can easily add metadata to all data sources. + Once this attribute is placed on a property, the rules for obtaining attributes for the property descriptor's collection differ. Typically, the property descriptor gathers local attributes, and then merges these with attributes from the property type. In this case, the attributes are taken from the type returned from the , not from the actual property type. This attribute is used on to point the object's specific type to , and the appropriate metadata is placed on to enable data binding. In so doing, external parties can easily add metadata to all data sources. Attributes obtained from a type declared in the have a priority in between the attributes of the property’s type and the attributes on the property. The following list, in priority order, shows the full set of available merged attributes: diff --git a/xml/System.ComponentModel/BackgroundWorker.xml b/xml/System.ComponentModel/BackgroundWorker.xml index c71fb179a7320..486a068efa2e9 100644 --- a/xml/System.ComponentModel/BackgroundWorker.xml +++ b/xml/System.ComponentModel/BackgroundWorker.xml @@ -44,7 +44,7 @@ > > events are not marshaled across boundaries. Do not use a component to perform multithreaded operations in more than one . - If your background operation requires a parameter, call with your parameter. Inside the event handler, you can extract the parameter from the property. + If your background operation requires a parameter, call with your parameter. Inside the event handler, you can extract the parameter from the property. For more information about , see [How to: Run an Operation in the Background](~/docs/framework/winforms/controls/how-to-run-an-operation-in-the-background.md). @@ -140,7 +140,7 @@ When you call , your worker method has an opportunity to stop its execution and exit. The worker code should periodically check the property to see if it has been set to `true`. > [!CAUTION] -> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](~/docs/standard/threading/managed-threading-best-practices.md). +> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](~/docs/standard/threading/managed-threading-best-practices.md). @@ -278,14 +278,14 @@ ## Remarks This event is raised when you call the method. This is where you start the operation that performs the potentially time-consuming work. - Your code in the event handler should periodically check the property value and abort the operation if it is `true`. When this occurs, you can set the flag of to `true`, and the flag of in your event handler will be set to `true`. + Your code in the event handler should periodically check the property value and abort the operation if it is `true`. When this occurs, you can set the flag of to `true`, and the flag of in your event handler will be set to `true`. > [!CAUTION] -> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](~/docs/standard/threading/managed-threading-best-practices.md). +> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](~/docs/standard/threading/managed-threading-best-practices.md). - If your operation produces a result, you can assign the result to the property. This will be available to the event handler in the property. + If your operation produces a result, you can assign the result to the property. This will be available to the event handler in the property. - If the operation raises an exception that your code does not handle, the catches the exception and passes it into the event handler, where it is exposed as the property of . If you are running under the Visual Studio debugger, the debugger will break at the point in the event handler where the unhandled exception was raised. If you have more than one , you should not reference any of them directly, as this would couple your event handler to a specific instance of . Instead, you should access your by casting the `sender` parameter in your event handler. + If the operation raises an exception that your code does not handle, the catches the exception and passes it into the event handler, where it is exposed as the property of . If you are running under the Visual Studio debugger, the debugger will break at the point in the event handler where the unhandled exception was raised. If you have more than one , you should not reference any of them directly, as this would couple your event handler to a specific instance of . Instead, you should access your by casting the `sender` parameter in your event handler. You must be careful not to manipulate any user-interface objects in your event handler. Instead, communicate to the user interface through the events. @@ -756,16 +756,16 @@ ## Remarks This event is raised when the event handler returns. - If the operation completes successfully and its result is assigned in the event handler, you can access the result through the property. + If the operation completes successfully and its result is assigned in the event handler, you can access the result through the property. - The property of indicates that an exception was thrown by the operation. + The property of indicates that an exception was thrown by the operation. - The property of indicates whether a cancellation request was processed by the background operation. If your code in the event handler detects a cancellation request by checking the flag and setting the flag of to `true`, the flag of also will be set to `true`. + The property of indicates whether a cancellation request was processed by the background operation. If your code in the event handler detects a cancellation request by checking the flag and setting the flag of to `true`, the flag of also will be set to `true`. > [!CAUTION] -> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](~/docs/standard/threading/managed-threading-best-practices.md). +> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](~/docs/standard/threading/managed-threading-best-practices.md). - Your event handler should always check the and properties before accessing the property. If an exception was raised or if the operation was canceled, accessing the property raises an exception. + Your event handler should always check the and properties before accessing the property. If an exception was raised or if the operation was canceled, accessing the property raises an exception. diff --git a/xml/System.ComponentModel/BindableAttribute.xml b/xml/System.ComponentModel/BindableAttribute.xml index cf5aca3029746..a56db792ff35b 100644 --- a/xml/System.ComponentModel/BindableAttribute.xml +++ b/xml/System.ComponentModel/BindableAttribute.xml @@ -35,7 +35,7 @@ If a property has been marked with the set to `true`, then a property change notification should be raised for that property. This means that if the property is , then two-way data binding is supported. If is , you can still bind to the property, but it should not be shown in the default set of properties to bind to, because it might or might not raise a property change notification. > [!NOTE] -> When you mark a property with set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, to check the value of this attribute in your code, you must specify the attribute as or . +> When you mark a property with set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, to check the value of this attribute in your code, you must specify the attribute as or . > [!CAUTION] > You can use this attribute at design time only. Nothing prevents you from binding to any property during run time. @@ -96,12 +96,12 @@ set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, to check the value of this attribute in your code, you must specify the attribute as or . + When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, to check the value of this attribute in your code, you must specify the attribute as or . ## Examples - The following code example marks a property as appropriate to bind data to. This code example creates a new , sets its value to , and binds it to the property. + The following code example marks a property as appropriate to bind data to. This code example creates a new , sets its value to , and binds it to the property. [!code-cpp[Classic BindableAttribute.BindableAttribute Example#1](~/samples/snippets/cpp/VS_Snippets_Winforms/Classic BindableAttribute.BindableAttribute Example/CPP/source.cpp#1)] [!code-csharp[Classic BindableAttribute.BindableAttribute Example#1](~/samples/snippets/csharp/VS_Snippets_Winforms/Classic BindableAttribute.BindableAttribute Example/CS/source.cs#1)] @@ -139,12 +139,12 @@ set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, to check the value of this attribute in your code, you must specify the attribute as or . + When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, to check the value of this attribute in your code, you must specify the attribute as or . ## Examples - The following code example marks a property as appropriate to bind data to. This code example creates a new , sets its value to , and binds it to the property. + The following code example marks a property as appropriate to bind data to. This code example creates a new , sets its value to , and binds it to the property. [!code-cpp[Classic BindableAttribute.BindableAttribute1 Example#1](~/samples/snippets/cpp/VS_Snippets_Winforms/Classic BindableAttribute.BindableAttribute1 Example/CPP/source.cpp#1)] [!code-csharp[Classic BindableAttribute.BindableAttribute1 Example#1](~/samples/snippets/csharp/VS_Snippets_Winforms/Classic BindableAttribute.BindableAttribute1 Example/CS/source.cs#1)] @@ -291,7 +291,7 @@ is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with this value, the is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -442,7 +442,7 @@ ## Remarks The field is the default setting for the . - When you mark a property with the constructor of the value `false,` the value of this attribute is set to the constant member . Therefore, to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the constructor of the value `false,` the value of this attribute is set to the constant member . Therefore, to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -475,7 +475,7 @@ constructor of the value `true`, the value of the is set to the constant member . Therefore, to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the constructor of the value `true`, the value of the is set to the constant member . Therefore, to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> diff --git a/xml/System.ComponentModel/BindableSupport.xml b/xml/System.ComponentModel/BindableSupport.xml index cdfaf81c86682..207929d993f12 100644 --- a/xml/System.ComponentModel/BindableSupport.xml +++ b/xml/System.ComponentModel/BindableSupport.xml @@ -29,7 +29,7 @@ ## Examples - For an example on how to use the enumeration to indicate whether a property can be bound, see the sample code in . + For an example on how to use the enumeration to indicate whether a property can be bound, see the sample code in . ]]> diff --git a/xml/System.ComponentModel/BrowsableAttribute.xml b/xml/System.ComponentModel/BrowsableAttribute.xml index 11260add6922e..b15d3e94582c9 100644 --- a/xml/System.ComponentModel/BrowsableAttribute.xml +++ b/xml/System.ComponentModel/BrowsableAttribute.xml @@ -34,7 +34,7 @@ A visual designer typically displays in the Properties window those members that either have no browsable attribute or are marked with the constructor's `browsable` parameter set to `true`. These members can be modified at design time. Members marked with the constructor's `browsable` parameter set to `false` are not appropriate for design-time editing and therefore are not displayed in a visual designer. The default is `true`. > [!NOTE] -> When you mark a property with `Browsable(true)`, the value of this attribute is set to the constant member . For a property marked with `Browsable(false)`, the value is . Therefore, when you check the value of this attribute in your code, you must specify the attribute as or . +> When you mark a property with `Browsable(true)`, the value of this attribute is set to the constant member . For a property marked with `Browsable(false)`, the value is . Therefore, when you check the value of this attribute in your code, you must specify the attribute as or . For more information, see [Attributes](~/docs/standard/attributes/index.md). @@ -95,12 +95,12 @@ constructor of the value `true`, the value of this attribute is set to the constant member . For a property marked with the constructor of the value `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . + When you mark a property with the constructor of the value `true`, the value of this attribute is set to the constant member . For a property marked with the constructor of the value `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . ## Examples - The following example marks a property as browsable. This code creates a new , sets its value to , and binds it to the property. + The following example marks a property as browsable. This code creates a new , sets its value to , and binds it to the property. [!code-cpp[Classic BrowsableAttribute.BrowsableAttribute Example#1](~/samples/snippets/cpp/VS_Snippets_Winforms/Classic BrowsableAttribute.BrowsableAttribute Example/CPP/source.cpp#1)] [!code-csharp[Classic BrowsableAttribute.BrowsableAttribute Example#1](~/samples/snippets/csharp/VS_Snippets_Winforms/Classic BrowsableAttribute.BrowsableAttribute Example/CS/source.cs#1)] @@ -186,7 +186,7 @@ . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with this value, this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -311,7 +311,7 @@ constructor of the value `false`, this attribute is set to the constant member . Therefore, when you check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the constructor of the value `false`, this attribute is set to the constant member . Therefore, when you check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -347,7 +347,7 @@ ## Remarks This field is the default setting for this attribute. - When you mark a property with the constructor of the value `true`, this attribute is set to the constant member . Therefore, when you check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the constructor of the value `true`, this attribute is set to the constant member . Therefore, when you check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> diff --git a/xml/System.ComponentModel/CollectionChangeEventArgs.xml b/xml/System.ComponentModel/CollectionChangeEventArgs.xml index 59a37c35f95bc..fc916100702a2 100644 --- a/xml/System.ComponentModel/CollectionChangeEventArgs.xml +++ b/xml/System.ComponentModel/CollectionChangeEventArgs.xml @@ -31,9 +31,9 @@ ## Examples - The following code example demonstrates the use of this type. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this type. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `AutoCompleteStringCollection1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `AutoCompleteStringCollection1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#76](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#76)] [!code-vb[System.Windows.Forms.EventExamples#76](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#76)] @@ -112,9 +112,9 @@ ## Examples - The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `AutoCompleteStringCollection1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `AutoCompleteStringCollection1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#76](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#76)] [!code-vb[System.Windows.Forms.EventExamples#76](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#76)] @@ -152,9 +152,9 @@ event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `AutoCompleteStringCollection1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `AutoCompleteStringCollection1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#76](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#76)] [!code-vb[System.Windows.Forms.EventExamples#76](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#76)] diff --git a/xml/System.ComponentModel/ComplexBindingPropertiesAttribute.xml b/xml/System.ComponentModel/ComplexBindingPropertiesAttribute.xml index 03d27c6a848bc..3c7b70d4165e7 100644 --- a/xml/System.ComponentModel/ComplexBindingPropertiesAttribute.xml +++ b/xml/System.ComponentModel/ComplexBindingPropertiesAttribute.xml @@ -30,7 +30,7 @@ is used to specify the properties used with complex data binding, such as binding based on . + The is used to specify the properties used with complex data binding, such as binding based on . The attribute is specified at the class level. It is inheritable and does not allow multiple attributes on the same class. diff --git a/xml/System.ComponentModel/Container.xml b/xml/System.ComponentModel/Container.xml index 833604e9e8f45..5f932bde5a321 100644 --- a/xml/System.ComponentModel/Container.xml +++ b/xml/System.ComponentModel/Container.xml @@ -385,7 +385,7 @@ ; otherwise, it returns `null`. You can override this method to provide a custom implementation to return a service object. For more information, see the method. + The default implementation of this method returns the current instance of the class if `service` is an ; otherwise, it returns `null`. You can override this method to provide a custom implementation to return a service object. For more information, see the method. ]]> diff --git a/xml/System.ComponentModel/CustomTypeDescriptor.xml b/xml/System.ComponentModel/CustomTypeDescriptor.xml index 697e710b3be36..11210bfca8e2f 100644 --- a/xml/System.ComponentModel/CustomTypeDescriptor.xml +++ b/xml/System.ComponentModel/CustomTypeDescriptor.xml @@ -62,7 +62,7 @@ constructor with a parameter that is `null`. + This constructor is equivalent to calling the other constructor with a parameter that is `null`. All methods of a created with this constructor will return default values. @@ -105,10 +105,10 @@ |Method|Default return value| |------------|--------------------------| -||An empty attribute collection ().| +||An empty attribute collection ().| ||The default instance.| -||An empty events collection ().| -||An empty property collection ().| +||An empty events collection ().| +||An empty property collection ().| ]]> diff --git a/xml/System.ComponentModel/DependencyPropertyDescriptor.xml b/xml/System.ComponentModel/DependencyPropertyDescriptor.xml index 5b98a2e887b07..7fab0b5bb8f32 100644 --- a/xml/System.ComponentModel/DependencyPropertyDescriptor.xml +++ b/xml/System.ComponentModel/DependencyPropertyDescriptor.xml @@ -18,7 +18,7 @@ ## Remarks This class is primarily used by designer applications. These applications may need to report the dependency property characteristics through property windows or other tools used for editing property values. - In order to check a specific property to determine whether it has available to serve as a , call either , or . If either method returns `null`, then the property is not a dependency property. If the method returns a valid , then the property is a dependency property. + In order to check a specific property to determine whether it has available to serve as a , call either , or . If either method returns `null`, then the property is not a dependency property. If the method returns a valid , then the property is a dependency property. ]]> diff --git a/xml/System.ComponentModel/DesignTimeVisibleAttribute.xml b/xml/System.ComponentModel/DesignTimeVisibleAttribute.xml index 66d93ee1b0219..8bbdd23ff639e 100644 --- a/xml/System.ComponentModel/DesignTimeVisibleAttribute.xml +++ b/xml/System.ComponentModel/DesignTimeVisibleAttribute.xml @@ -33,7 +33,7 @@ ## Remarks The is a hint to the Designer. The Designer will ignore this attribute for components that have a UI presence. It can only be applied to classes. - The is most useful when you have a control that accepts child components. For example, the control's node items should not appear in the component tray because they are drawn by the control. + The is most useful when you have a control that accepts child components. For example, the control's node items should not appear in the component tray because they are drawn by the control. ]]> diff --git a/xml/System.ComponentModel/DesignerCategoryAttribute.xml b/xml/System.ComponentModel/DesignerCategoryAttribute.xml index ee78ad6a1a600..9dc01c52affc1 100644 --- a/xml/System.ComponentModel/DesignerCategoryAttribute.xml +++ b/xml/System.ComponentModel/DesignerCategoryAttribute.xml @@ -39,9 +39,9 @@ |Category|Description| |--------------|-----------------| -|Component|Designers that are used with components. The attribute is set to the constant member .| -|Form|Designers that are used with forms. The attribute is set to the constant member .| -|Designer|Designers that are used with designers. The attribute is set to the constant member .| +|Component|Designers that are used with components. The attribute is set to the constant member .| +|Form|Designers that are used with forms. The attribute is set to the constant member .| +|Designer|Designers that are used with designers. The attribute is set to the constant member .| |Empty String ("")|This is the default category.| For more information, see [Attributes](~/docs/standard/attributes/index.md). diff --git a/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml b/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml index e16e830fad84e..3a766f7cad5d1 100644 --- a/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml +++ b/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml @@ -83,7 +83,7 @@ and sets its value to . + The following code example specifies how a property on a component is saved by a designer. This code creates a new and sets its value to . [!code-cpp[Classic DesignerSerializationVisibilityAttribute.DesignerSerializationVisibilityAttribute Example#1](~/samples/snippets/cpp/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute.DesignerSerializationVisibilityAttribute Example/CPP/source.cpp#1)] [!code-csharp[Classic DesignerSerializationVisibilityAttribute.DesignerSerializationVisibilityAttribute Example#1](~/samples/snippets/csharp/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute.DesignerSerializationVisibilityAttribute Example/CS/source.cs#1)] @@ -155,7 +155,7 @@ . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with this value, this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> diff --git a/xml/System.ComponentModel/EditorAttribute.xml b/xml/System.ComponentModel/EditorAttribute.xml index 6ea1e5d0ca483..14d33f7276125 100644 --- a/xml/System.ComponentModel/EditorAttribute.xml +++ b/xml/System.ComponentModel/EditorAttribute.xml @@ -111,7 +111,7 @@ format. + The `typeName` parameter must be in the format. The represented by the `typeName` parameter must either derive from or implement the base class. @@ -151,7 +151,7 @@ format. + The `typeName` parameter must be in the format. The represented by the `typeName` must either derive from or implement the base class. diff --git a/xml/System.ComponentModel/EditorBrowsableAttribute.xml b/xml/System.ComponentModel/EditorBrowsableAttribute.xml index bb019305146a3..19d7b1c6e1891 100644 --- a/xml/System.ComponentModel/EditorBrowsableAttribute.xml +++ b/xml/System.ComponentModel/EditorBrowsableAttribute.xml @@ -81,7 +81,7 @@ . + The default for this property is . ]]> @@ -218,7 +218,7 @@ . + The default for this property is . ]]> diff --git a/xml/System.ComponentModel/HandledEventHandler.xml b/xml/System.ComponentModel/HandledEventHandler.xml index eba9f5a350122..5afca89fe9dbd 100644 --- a/xml/System.ComponentModel/HandledEventHandler.xml +++ b/xml/System.ComponentModel/HandledEventHandler.xml @@ -34,9 +34,9 @@ property provides sufficient event data. The event handler can set the property to `true` if all necessary processing has been completed in the handler. + This delegate is available for use with your own events when the property provides sufficient event data. The event handler can set the property to `true` if all necessary processing has been completed in the handler. - Typically, events that require this functionality will also require additional event data, and will use a class that derives from along with a corresponding, similarly-named delegate type. For example, the event uses the event-data type and the delegate type. Because delegates are not inherited, the is rarely used. + Typically, events that require this functionality will also require additional event data, and will use a class that derives from along with a corresponding, similarly-named delegate type. For example, the event uses the event-data type and the delegate type. Because delegates are not inherited, the is rarely used. ]]> diff --git a/xml/System.ComponentModel/IBindingList.xml b/xml/System.ComponentModel/IBindingList.xml index 63e1125557d98..af8c850af8b5f 100644 --- a/xml/System.ComponentModel/IBindingList.xml +++ b/xml/System.ComponentModel/IBindingList.xml @@ -118,7 +118,7 @@ Implementing this method means that the list must understand the type of objects to add to the list and must understand how to create a new instance of that type. For example, if you have a collection of `myCustomer` objects, the method should add a new `myCustomer` object to the list. > [!NOTE] -> If the objects in this list implement the interface, calling the method should discard an object, not add it to the list, when the object was created using the method. The object should only be added to the list when the method is called. Therefore, you must sychronize the object and the list carefully. +> If the objects in this list implement the interface, calling the method should discard an object, not add it to the list, when the object was created using the method. The object should only be added to the list when the method is called. Therefore, you must sychronize the object and the list carefully. When this method is called, you should raise a event with the enumeration carrying the appropriate index. The added row is in a state where hitting Esc on a control can remove the new row. Raising the event with the enumeration a second time on this row indicates that the item is now a normal row (not in new state). @@ -185,7 +185,7 @@ or is `true`, this property returns `false`. + If or is `true`, this property returns `false`. ]]> @@ -220,10 +220,10 @@ or is `true`, this property returns `false`. + If or is `true`, this property returns `false`. > [!NOTE] -> If returns `false`, and throw a . +> If returns `false`, and throw a . ]]> diff --git a/xml/System.ComponentModel/IBindingListView.xml b/xml/System.ComponentModel/IBindingListView.xml index 48bb89388e74e..ff0c68b649e2e 100644 --- a/xml/System.ComponentModel/IBindingListView.xml +++ b/xml/System.ComponentModel/IBindingListView.xml @@ -100,7 +100,7 @@ property should exhibit the following behavior when the property is set: The data source returns only the items that meet the filter criteria when the list is accessed by item index or when the list is enumerated. The definition of the filter string is dependent on the data-source implementation, but the behavior associated with setting the filter should be modeled on . + Your implementation of the property should exhibit the following behavior when the property is set: The data source returns only the items that meet the filter criteria when the list is accessed by item index or when the list is enumerated. The definition of the filter string is dependent on the data-source implementation, but the behavior associated with setting the filter should be modeled on . ]]> diff --git a/xml/System.ComponentModel/ICancelAddNew.xml b/xml/System.ComponentModel/ICancelAddNew.xml index e997b743e513b..eceee93cadb88 100644 --- a/xml/System.ComponentModel/ICancelAddNew.xml +++ b/xml/System.ComponentModel/ICancelAddNew.xml @@ -35,7 +35,7 @@ There are two models that allow transactional addition of an item to a data-bound collection: -- The older model relies directly on a collection that implements the interface and is data-bound directly using the class. The , , and methods of the class are responsible for transactional support for adding new items. However, this functionality depends upon the items supporting transactional behavior through the interface. If the items do not support this interface, the item will always be added to the list, regardless of subsequent calls to . +- The older model relies directly on a collection that implements the interface and is data-bound directly using the class. The , , and methods of the class are responsible for transactional support for adding new items. However, this functionality depends upon the items supporting transactional behavior through the interface. If the items do not support this interface, the item will always be added to the list, regardless of subsequent calls to . - The newer model supports a more robust data-binding scenario through the generic class, which implements the and interfaces. In this case, the transactional support is managed by the collection directly. diff --git a/xml/System.ComponentModel/IComponent.xml b/xml/System.ComponentModel/IComponent.xml index 6d3fa30785eaa..d59cc8fa44a0f 100644 --- a/xml/System.ComponentModel/IComponent.xml +++ b/xml/System.ComponentModel/IComponent.xml @@ -48,7 +48,7 @@ You can contain components in a container. In this context, containment refers to logical containment, not visual containment. You can use components and containers in a variety of scenarios, both visual and non visual. - inherits from , the default implementation of . + inherits from , the default implementation of . A component interacts with its container primarily through a container-provided , which is a repository of container-specific per-component information. diff --git a/xml/System.ComponentModel/ICustomTypeDescriptor.xml b/xml/System.ComponentModel/ICustomTypeDescriptor.xml index c5335fb50700d..66039d5ed0336 100644 --- a/xml/System.ComponentModel/ICustomTypeDescriptor.xml +++ b/xml/System.ComponentModel/ICustomTypeDescriptor.xml @@ -311,7 +311,7 @@ ## Remarks The events for this instance can differ from the set of events that the class provides. For example, if the component is site-based, the site can add or remove additional events. - Implementors can return if no properties are specified. This method should never return `null`. + Implementors can return if no properties are specified. This method should never return `null`. ]]> @@ -390,7 +390,7 @@ ## Remarks The properties for this instance can differ from the set of properties that the class provides. For example, if the component is sited, the site can add or remove additional properties. - Implementers can return if no properties are specified. This method should never return `null`. + Implementers can return if no properties are specified. This method should never return `null`. ]]> @@ -472,7 +472,7 @@ method retrieves the object that contains the property member that is described by parameter. Typically, this object is required for the and methods. + The method retrieves the object that contains the property member that is described by parameter. Typically, this object is required for the and methods. This method should return an object that you can use as follows: diff --git a/xml/System.ComponentModel/IEditableCollectionView.xml b/xml/System.ComponentModel/IEditableCollectionView.xml index 5ed21f66120a1..6a11d97bfd1d3 100644 --- a/xml/System.ComponentModel/IEditableCollectionView.xml +++ b/xml/System.ComponentModel/IEditableCollectionView.xml @@ -15,7 +15,7 @@ ## Remarks When a collection view implements the interface, you can directly change the underlying collection, if it allows changes to be made, by using the methods and properties that exposes, regardless of the collection's type. - The types , , and are the types that ship with [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] that inherit from . These types also implement the , so you can edit a collection that uses one of those types. , in particular, is often used because the property is an . + The types , , and are the types that ship with [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] that inherit from . These types also implement the , so you can edit a collection that uses one of those types. , in particular, is often used because the property is an . diff --git a/xml/System.ComponentModel/IEditableCollectionViewAddNewItem.xml b/xml/System.ComponentModel/IEditableCollectionViewAddNewItem.xml index d7c19007a8c76..35bde7ea0c87c 100644 --- a/xml/System.ComponentModel/IEditableCollectionViewAddNewItem.xml +++ b/xml/System.ComponentModel/IEditableCollectionViewAddNewItem.xml @@ -116,7 +116,7 @@ property is `true`, you can specify an object to add to the collection by calling the method. is `false` if items cannot be added to the collection by using . If is `false`, you may still be able to add an object by using the method. For example, you can add objects to an ADO.NET source by using , but not by using . + If the property is `true`, you can specify an object to add to the collection by calling the method. is `false` if items cannot be added to the collection by using . If is `false`, you may still be able to add an object by using the method. For example, you can add objects to an ADO.NET source by using , but not by using . ]]> diff --git a/xml/System.ComponentModel/IEditableObject.xml b/xml/System.ComponentModel/IEditableObject.xml index 6f014057f8eb2..9e4b257b6f3e9 100644 --- a/xml/System.ComponentModel/IEditableObject.xml +++ b/xml/System.ComponentModel/IEditableObject.xml @@ -112,7 +112,7 @@ This method will be ignored if called on an object that is not being edited. > [!NOTE] -> If the owning list implements , calling on an object created using discards the object. +> If the owning list implements , calling on an object created using discards the object. ]]> diff --git a/xml/System.ComponentModel/INotifyPropertyChanged.xml b/xml/System.ComponentModel/INotifyPropertyChanged.xml index fcd199d473394..76f9b108afbd9 100644 --- a/xml/System.ComponentModel/INotifyPropertyChanged.xml +++ b/xml/System.ComponentModel/INotifyPropertyChanged.xml @@ -376,7 +376,7 @@ End Class event can indicate all properties on the object have changed by using either `null` or as the property name in the . + The event can indicate all properties on the object have changed by using either `null` or as the property name in the . diff --git a/xml/System.ComponentModel/ITypedList.xml b/xml/System.ComponentModel/ITypedList.xml index b771bba7f57c2..bad4e8f281aab 100644 --- a/xml/System.ComponentModel/ITypedList.xml +++ b/xml/System.ComponentModel/ITypedList.xml @@ -37,7 +37,7 @@ In a designer, you can initialize binding to objects by following the same rules. - For more information on binding to a data source, see the class. + For more information on binding to a data source, see the class. diff --git a/xml/System.ComponentModel/InvalidEnumArgumentException.xml b/xml/System.ComponentModel/InvalidEnumArgumentException.xml index cbb75ada0ffcd..281c90a652f08 100644 --- a/xml/System.ComponentModel/InvalidEnumArgumentException.xml +++ b/xml/System.ComponentModel/InvalidEnumArgumentException.xml @@ -30,7 +30,7 @@ ## Examples - The following code example shows how to catch an exception and interpret its content. The example attempts to pass an invalid enumeration value (`MessageBoxButtons`) through casting, as the method's third argument. Upon catching the exception, the example fetches the respective error message, the invalid parameter, stack trace, and origin of the exception. + The following code example shows how to catch an exception and interpret its content. The example attempts to pass an invalid enumeration value (`MessageBoxButtons`) through casting, as the method's third argument. Upon catching the exception, the example fetches the respective error message, the invalid parameter, stack trace, and origin of the exception. [!code-cpp[enumException#1](~/samples/snippets/cpp/VS_Snippets_Winforms/enumException/CPP/enumexception.cpp#1)] [!code-csharp[enumException#1](~/samples/snippets/csharp/VS_Snippets_Winforms/enumException/CS/enumexception.cs#1)] diff --git a/xml/System.ComponentModel/LicenseException.xml b/xml/System.ComponentModel/LicenseException.xml index 7bef619bb6a61..c340a5730ffc5 100644 --- a/xml/System.ComponentModel/LicenseException.xml +++ b/xml/System.ComponentModel/LicenseException.xml @@ -25,16 +25,16 @@ method throws when a component cannot obtain a valid license. This occurs when a component is either not licensed, or is licensed but cannot be granted a valid license. + The method throws when a component cannot obtain a valid license. This occurs when a component is either not licensed, or is licensed but cannot be granted a valid license. For more information on licensing, see [How to: License Components and Controls](http://msdn.microsoft.com/library/8e66c1ed-a445-4b26-8185-990b6e2bbd57). ## Examples - The following code example shows how to catch a and interpret its content. In the sample, the application calls the method for a that is not licensed. Upon catching the exception, the sample fetches the respective error message, the type of component that was not granted a license, the stack trace, and the origin of the exception. + The following code example shows how to catch a and interpret its content. In the sample, the application calls the method for a that is not licensed. Upon catching the exception, the sample fetches the respective error message, the type of component that was not granted a license, the stack trace, and the origin of the exception. - This example requires that you have specified the by marking the with a attribute. For more information on how to do this, see the class. + This example requires that you have specified the by marking the with a attribute. For more information on how to do this, see the class. [!code-cpp[LicenseException#1](~/samples/snippets/cpp/VS_Snippets_Winforms/LicenseException/CPP/licenseex.cpp#1)] [!code-csharp[LicenseException#1](~/samples/snippets/csharp/VS_Snippets_Winforms/LicenseException/CS/licenseex.cs#1)] diff --git a/xml/System.ComponentModel/LicenseManager.xml b/xml/System.ComponentModel/LicenseManager.xml index 544521c90ee85..f1273d28b4991 100644 --- a/xml/System.ComponentModel/LicenseManager.xml +++ b/xml/System.ComponentModel/LicenseManager.xml @@ -161,7 +161,7 @@ , the user must give the context in which the is valid to the method. The returned by this property should be passed to all classes. + When the user requests a valid , the user must give the context in which the is valid to the method. The returned by this property should be passed to all classes. ]]> diff --git a/xml/System.ComponentModel/ListChangedEventArgs.xml b/xml/System.ComponentModel/ListChangedEventArgs.xml index 732506f86b48f..417f1d0558f9f 100644 --- a/xml/System.ComponentModel/ListChangedEventArgs.xml +++ b/xml/System.ComponentModel/ListChangedEventArgs.xml @@ -34,9 +34,9 @@ ## Examples - The following code example demonstrates the use of this type. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this type. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#134](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#134)] [!code-vb[System.Windows.Forms.EventExamples#134](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#134)] @@ -209,9 +209,9 @@ event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#134](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#134)] [!code-vb[System.Windows.Forms.EventExamples#134](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#134)] @@ -253,9 +253,9 @@ ## Examples - The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#134](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#134)] [!code-vb[System.Windows.Forms.EventExamples#134](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#134)] @@ -292,9 +292,9 @@ event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#134](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#134)] [!code-vb[System.Windows.Forms.EventExamples#134](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#134)] @@ -331,9 +331,9 @@ event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#134](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#134)] [!code-vb[System.Windows.Forms.EventExamples#134](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#134)] diff --git a/xml/System.ComponentModel/ListSortDescriptionCollection.xml b/xml/System.ComponentModel/ListSortDescriptionCollection.xml index fffc643ed4fab..a596cac60db53 100644 --- a/xml/System.ComponentModel/ListSortDescriptionCollection.xml +++ b/xml/System.ComponentModel/ListSortDescriptionCollection.xml @@ -330,7 +330,7 @@ ## Remarks This implementation returns the current instance of the , because this collection, once constructed, does not allow public access to the underlying list. - For more information on the method, see the property. + For more information on the method, see the property. ]]> @@ -396,7 +396,7 @@ class implements the interface, it must have an method. However, because the class represents a read-only collection, adding items to the collection is an invalid operation. + Because the class implements the interface, it must have an method. However, because the class represents a read-only collection, adding items to the collection is an invalid operation. ]]> @@ -431,7 +431,7 @@ class implements the interface, it must have a method. However, because the class represents a read-only collection, clearing items from the collection is an invalid operation. + Because the class implements the interface, it must have a method. However, because the class represents a read-only collection, clearing items from the collection is an invalid operation. ]]> @@ -471,7 +471,7 @@ class implements the interface, it must have a method. However, because the class represents a read-only collection, inserting items into the collection is an invalid operation. + Because the class implements the interface, it must have a method. However, because the class represents a read-only collection, inserting items into the collection is an invalid operation. ]]> @@ -610,7 +610,7 @@ class implements the interface, it must have a method. However, because the class represents a read-only collection, removing items from the collection is an invalid operation. + Because the class implements the interface, it must have a method. However, because the class represents a read-only collection, removing items from the collection is an invalid operation. ]]> @@ -648,7 +648,7 @@ class implements the interface, it must have a method. However, because the class represents a read-only collection, removing items from the collection is an invalid operation. + Because the class implements the interface, it must have a method. However, because the class represents a read-only collection, removing items from the collection is an invalid operation. ]]> diff --git a/xml/System.ComponentModel/ListSortDirection.xml b/xml/System.ComponentModel/ListSortDirection.xml index b41ebee305554..db94806a1a3cd 100644 --- a/xml/System.ComponentModel/ListSortDirection.xml +++ b/xml/System.ComponentModel/ListSortDirection.xml @@ -24,7 +24,7 @@ and use this enumeration. + and use this enumeration. ]]> diff --git a/xml/System.ComponentModel/LocalizableAttribute.xml b/xml/System.ComponentModel/LocalizableAttribute.xml index 1946d5c799583..2793cb748f00a 100644 --- a/xml/System.ComponentModel/LocalizableAttribute.xml +++ b/xml/System.ComponentModel/LocalizableAttribute.xml @@ -36,7 +36,7 @@ By default, members that have no localizable attribute or are marked with the set to `false` will have their property values persisted to code, if the data type allows. Otherwise, if the main component is set to `Localizable`, all properties will be persisted to the resource file. The default is `false`. > [!NOTE] -> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . +> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . For more information, see [Attributes](~/docs/standard/attributes/index.md). @@ -91,7 +91,7 @@ , sets its value to , and binds it to the property. + The following example marks a property as needing to be localized. This code creates a new , sets its value to , and binds it to the property. [!code-cpp[Classic LocalizableAttribute.LocalizableAttribute Example#1](~/samples/snippets/cpp/VS_Snippets_Winforms/Classic LocalizableAttribute.LocalizableAttribute Example/CPP/source.cpp#1)] [!code-csharp[Classic LocalizableAttribute.LocalizableAttribute Example#1](~/samples/snippets/csharp/VS_Snippets_Winforms/Classic LocalizableAttribute.LocalizableAttribute Example/CS/source.cs#1)] @@ -129,7 +129,7 @@ . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with this value, this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -298,7 +298,7 @@ ## Remarks This field is the default setting for this attribute. - When you mark a property with the set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -332,7 +332,7 @@ set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> diff --git a/xml/System.ComponentModel/MaskedTextProvider.xml b/xml/System.ComponentModel/MaskedTextProvider.xml index 2e6c6fb4df78e..78fe75eaaf06a 100644 --- a/xml/System.ComponentModel/MaskedTextProvider.xml +++ b/xml/System.ComponentModel/MaskedTextProvider.xml @@ -31,7 +31,7 @@ ## Remarks The control contains a mask, composed of literal characters and formatting elements, that it tests all user input against. Instead of permanently associating a specific mask-parsing engine with , Windows Forms provides it as a separate service, represented by the class, which defines the syntax of the masking language discussed in the documentation for the property. - Many of the members of the class refer their implementation to similarly named members of the associated . For example, the property of the class refers all access to the of the class. + Many of the members of the class refer their implementation to similarly named members of the associated . For example, the property of the class refers all access to the of the class. The mask-parsing engine used by is modeled after the Masked Edit control included in Microsoft Visual Basic version 6. Its masking language is described in the documentation for the property. @@ -78,7 +78,7 @@ constructor: + Use of this constructor is exactly equivalent to the following call to the constructor: `MaskedTextProvider(mask , null, true, '_', '\0', false)` @@ -117,7 +117,7 @@ constructor: + Use of this constructor is exactly equivalent to the following call to the constructor: `MaskedTextProvider(mask , null, true, '_', '\0', restrictToASCII)` @@ -155,7 +155,7 @@ constructor: + Use of this constructor is exactly equivalent to the following call to the constructor: `MaskedTextProvider(mask , culture, true, '_', '\0', false)` @@ -196,7 +196,7 @@ constructor: + Use of this constructor is exactly equivalent to the following call to the constructor: `MaskedTextProvider(mask , null, allowPromptAsInput, '_', passwordChar, false)` @@ -237,7 +237,7 @@ constructor: + Use of this constructor is exactly equivalent to the following call to the constructor: `MaskedTextProvider(mask , culture, true, '_', '\0', restrictToAscii)` @@ -280,7 +280,7 @@ constructor: + Use of this constructor is exactly equivalent to the following call to the constructor: `MaskedTextProvider(mask , culture, allowPromptAsInput, '_', passwordChar, false)` @@ -327,7 +327,7 @@ class, which is detailed in the property of the class. + This constructor represents the most general overloaded form. The `mask` parameter must conform to the masking language defined by the class, which is detailed in the property of the class. Because neutral cultures cannot be queried for culture-specific information, the constructor will use the method to search for the first non-neutral culture to use to determine the proper separator characters. @@ -2053,7 +2053,7 @@ property checks only required input elements. To determine whether all required and optional input elements have been entered, use the property of the class instead. + The property checks only required input elements. To determine whether all required and optional input elements have been entered, use the property of the class instead. The current value of the property determines which formatting elements are considered required and which are optional. diff --git a/xml/System.ComponentModel/MergablePropertyAttribute.xml b/xml/System.ComponentModel/MergablePropertyAttribute.xml index 819399c098399..70b9795ec1860 100644 --- a/xml/System.ComponentModel/MergablePropertyAttribute.xml +++ b/xml/System.ComponentModel/MergablePropertyAttribute.xml @@ -34,7 +34,7 @@ Properties that are marked with the set to `true` can be combined with properties belonging to other objects in a Properties window. Properties that are marked with the set to `false` must be displayed separately. The default is `true`. > [!NOTE] -> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the property set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . +> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the property set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . For more information, see [Attributes](~/docs/standard/attributes/index.md). @@ -95,7 +95,7 @@ , sets its value to , and binds it to the property. + The following example marks a property as appropriate to merge. This code creates a new , sets its value to , and binds it to the property. [!code-cpp[Classic MergablePropertyAttribute.MergablePropertyAttribute Example#1](~/samples/snippets/cpp/VS_Snippets_Winforms/Classic MergablePropertyAttribute.MergablePropertyAttribute Example/CPP/source.cpp#1)] [!code-csharp[Classic MergablePropertyAttribute.MergablePropertyAttribute Example#1](~/samples/snippets/csharp/VS_Snippets_Winforms/Classic MergablePropertyAttribute.MergablePropertyAttribute Example/CS/source.cs#1)] @@ -181,7 +181,7 @@ . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with this value, this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -306,7 +306,7 @@ set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -342,7 +342,7 @@ ## Remarks This field is the default setting for this attribute. - When you mark a property with the set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> diff --git a/xml/System.ComponentModel/NestedContainer.xml b/xml/System.ComponentModel/NestedContainer.xml index ea6cacebeaadd..482204befd622 100644 --- a/xml/System.ComponentModel/NestedContainer.xml +++ b/xml/System.ComponentModel/NestedContainer.xml @@ -206,7 +206,7 @@ method. This implementation only resolves requests for the and services. + This method overrides the method. This implementation only resolves requests for the and services. ]]> diff --git a/xml/System.ComponentModel/NotifyParentPropertyAttribute.xml b/xml/System.ComponentModel/NotifyParentPropertyAttribute.xml index dc77876917cbb..055b299f9b3c3 100644 --- a/xml/System.ComponentModel/NotifyParentPropertyAttribute.xml +++ b/xml/System.ComponentModel/NotifyParentPropertyAttribute.xml @@ -31,7 +31,7 @@ to a property if its parent property should receive notification of changes to the property's values. For example, in the Properties window, the property has nested properties such as and . These nested properties are marked with `NotifyParentPropertyAttribute(true)` so they notify the parent property to update its value and display when the property values change. + Apply to a property if its parent property should receive notification of changes to the property's values. For example, in the Properties window, the property has nested properties such as and . These nested properties are marked with `NotifyParentPropertyAttribute(true)` so they notify the parent property to update its value and display when the property values change. For more information about using attributes, see [Attributes](~/docs/standard/attributes/index.md). diff --git a/xml/System.ComponentModel/ProgressChangedEventArgs.xml b/xml/System.ComponentModel/ProgressChangedEventArgs.xml index b51c8df2a75a6..1e9694c06bf5e 100644 --- a/xml/System.ComponentModel/ProgressChangedEventArgs.xml +++ b/xml/System.ComponentModel/ProgressChangedEventArgs.xml @@ -100,9 +100,9 @@ ## Examples - The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `PictureBox1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `PictureBox1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#517](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#517)] [!code-vb[System.Windows.Forms.EventExamples#517](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#517)] @@ -140,9 +140,9 @@ event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - To run the example code, paste it into a project that contains an instance of type named `PictureBox1`. Then ensure that the event handler is associated with the event. + To run the example code, paste it into a project that contains an instance of type named `PictureBox1`. Then ensure that the event handler is associated with the event. [!code-csharp[System.Windows.Forms.EventExamples#517](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/CS/EventExamples.cs#517)] [!code-vb[System.Windows.Forms.EventExamples#517](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.EventExamples/VB/EventExamples.vb#517)] diff --git a/xml/System.ComponentModel/PropertyDescriptor.xml b/xml/System.ComponentModel/PropertyDescriptor.xml index fa9c5b984a55a..8a87d91d3b902 100644 --- a/xml/System.ComponentModel/PropertyDescriptor.xml +++ b/xml/System.ComponentModel/PropertyDescriptor.xml @@ -773,7 +773,7 @@ references. If it does not find the type in the assembly, it calls . + To find the appropriate type, this method first checks the assembly of the type that this references. If it does not find the type in the assembly, it calls . ]]> @@ -1074,15 +1074,15 @@ This method creates a automatically in the following order: -1. The method calls the method to create a new to represent the changes. +1. The method calls the method to create a new to represent the changes. -2. The method calls the method to indicate that the transaction has begun and the changes are about to occur. +2. The method calls the method to indicate that the transaction has begun and the changes are about to occur. 3. The method resets the property to the value determined by this method's checking order. -4. The method calls the method to indicate that the changes have occurred. +4. The method calls the method to indicate that the changes have occurred. -5. The method calls to indicate that the transaction is completed. +5. The method calls to indicate that the transaction is completed. The purpose of the transaction is to support `Undo` and `Redo` functionality. @@ -1159,15 +1159,15 @@ This method creates a automatically in the following order: -1. The method calls the method to create a new to represent the changes. +1. The method calls the method to create a new to represent the changes. -2. The method calls the method to indicate that the transaction has begun and the changes are about to occur. +2. The method calls the method to indicate that the transaction has begun and the changes are about to occur. 3. The method resets the property to the value determined by this method's checking order. -4. The method calls the method to indicate that the changes have occurred. +4. The method calls the method to indicate that the changes have occurred. -5. The method calls to indicate that the transaction is complete. +5. The method calls to indicate that the transaction is complete. The purpose of the transaction is to support `Undo` and `Redo` functionality. diff --git a/xml/System.ComponentModel/ReadOnlyAttribute.xml b/xml/System.ComponentModel/ReadOnlyAttribute.xml index 9c77a498862d1..6cb86d9e99b40 100644 --- a/xml/System.ComponentModel/ReadOnlyAttribute.xml +++ b/xml/System.ComponentModel/ReadOnlyAttribute.xml @@ -34,7 +34,7 @@ Members that are marked with the set to `true` or that do not have a `Set` method cannot be changed. Members that do not have this attribute or that are marked with the set to `false` are read/write, and they can be changed. The default is . > [!IMPORTANT] -> The class enforces the in the design environment and at run time. When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . +> The class enforces the in the design environment and at run time. When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . For more information, see [Attributes](~/docs/standard/attributes/index.md). @@ -98,12 +98,12 @@ Members that are marked with the set to `true` or that do not have a `Set` method cannot be changed. Members that do not have this attribute or that are marked with the set to `false` are read/write, and they can be changed. The default is . > [!NOTE] -> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . +> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . ## Examples - The following code example marks a property as read-only. This code creates a new , sets its value to , and binds it to the property. + The following code example marks a property as read-only. This code creates a new , sets its value to , and binds it to the property. [!code-cpp[Classic ReadOnlyAttribute.ReadOnlyAttribute Example#1](~/samples/snippets/cpp/VS_Snippets_Winforms/Classic ReadOnlyAttribute.ReadOnlyAttribute Example/CPP/source.cpp#1)] [!code-csharp[Classic ReadOnlyAttribute.ReadOnlyAttribute Example#1](~/samples/snippets/csharp/VS_Snippets_Winforms/Classic ReadOnlyAttribute.ReadOnlyAttribute Example/CS/source.cs#1)] @@ -141,7 +141,7 @@ . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with this value, this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -316,7 +316,7 @@ ## Remarks This field is the default setting for this attribute. - When you mark a property with the set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -350,7 +350,7 @@ set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> diff --git a/xml/System.ComponentModel/RecommendedAsConfigurableAttribute.xml b/xml/System.ComponentModel/RecommendedAsConfigurableAttribute.xml index edea7dc8fe3e6..6695ca66208ab 100644 --- a/xml/System.ComponentModel/RecommendedAsConfigurableAttribute.xml +++ b/xml/System.ComponentModel/RecommendedAsConfigurableAttribute.xml @@ -38,7 +38,7 @@ You can bind a property that does not have a to a setting in Visual Studio by clicking the ellipsis button (…) under **Settings** in the **Properties** window and selecting the appropriate property from the list. > [!NOTE] -> When you mark a property with set to `true`, the value of this attribute is set to the constant member . For a property marked with set to value `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . +> When you mark a property with set to `true`, the value of this attribute is set to the constant member . For a property marked with set to value `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . For more information, see [Attributes](~/docs/standard/attributes/index.md). @@ -100,7 +100,7 @@ , sets its value to , and binds it to the property. + The following example marks a property as usable as an application setting. This code creates a new , sets its value to , and binds it to the property. [!code-cpp[Classic RecommendedAsConfigurableAttribute.RecommendedAsConfigurableAttribute Example#1](~/samples/snippets/cpp/VS_Snippets_Winforms/Classic RecommendedAsConfigurableAttribute.RecommendedAsConfigurableAttribute Example/CPP/source.cpp#1)] [!code-csharp[Classic RecommendedAsConfigurableAttribute.RecommendedAsConfigurableAttribute Example#1](~/samples/snippets/csharp/VS_Snippets_Winforms/Classic RecommendedAsConfigurableAttribute.RecommendedAsConfigurableAttribute Example/CS/source.cs#1)] @@ -254,7 +254,7 @@ ## Remarks This field is the default setting for this attribute. - When you mark a property with set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute . + When you mark a property with set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute . ]]> @@ -336,7 +336,7 @@ ## Remarks When you mark a property with set to `true`, the value of this attribute is set to the constant member . - Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> diff --git a/xml/System.ComponentModel/RunInstallerAttribute.xml b/xml/System.ComponentModel/RunInstallerAttribute.xml index 73346785e5439..b1e147355696e 100644 --- a/xml/System.ComponentModel/RunInstallerAttribute.xml +++ b/xml/System.ComponentModel/RunInstallerAttribute.xml @@ -33,7 +33,7 @@ If a class that inherits from is marked with the set to `true`, Visual Studio's Custom Action Installer or the InstallUtil.exe will be invoked when the assembly is installed. Members marked with the set to `false` will not invoke an installer. The default is `true`. > [!NOTE] -> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . +> When you mark a property with the set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, when you want to check the value of this attribute in your code, you must specify the attribute as or . For more information, see [Attributes](~/docs/standard/attributes/index.md). @@ -111,7 +111,7 @@ . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with this value, this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -235,7 +235,7 @@ ## Remarks This field is the default setting for this attribute. - When you mark a property with the set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the set to `false`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> @@ -296,7 +296,7 @@ set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . + When you mark a property with the set to `true`, the value of this attribute is set to the constant member . Therefore, when you want to check whether the attribute is set to this value in your code, you must specify the attribute as . ]]> diff --git a/xml/System.ComponentModel/RunWorkerCompletedEventArgs.xml b/xml/System.ComponentModel/RunWorkerCompletedEventArgs.xml index f7877e605c66b..d3359a0e72723 100644 --- a/xml/System.ComponentModel/RunWorkerCompletedEventArgs.xml +++ b/xml/System.ComponentModel/RunWorkerCompletedEventArgs.xml @@ -26,7 +26,7 @@ is an example of the name of such a method. If you add an instance of the delegate to the event, you will receive information about the outcome of asynchronous operations in the parameter of the corresponding event handler. + If you are using a class that implements the [Event-based Asynchronous Pattern Overview](~/docs/standard/asynchronous-programming-patterns/event-based-asynchronous-pattern-overview.md), the class provides a *MethodName*`Completed` event. *MethodName* is a placeholder for the first part of the method's name. is an example of the name of such a method. If you add an instance of the delegate to the event, you will receive information about the outcome of asynchronous operations in the parameter of the corresponding event handler. > [!NOTE] > The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](~/docs/framework/performance/sql-server-programming-and-host-protection-attributes.md). diff --git a/xml/System.ComponentModel/SortDescription.xml b/xml/System.ComponentModel/SortDescription.xml index de1fec78ba680..82a9422ab0973 100644 --- a/xml/System.ComponentModel/SortDescription.xml +++ b/xml/System.ComponentModel/SortDescription.xml @@ -140,7 +140,7 @@ if the two objects are equal; otherwise, . - .]]> + .]]> @@ -167,7 +167,7 @@ if the values are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.ComponentModel/TypeDescriptionProvider.xml b/xml/System.ComponentModel/TypeDescriptionProvider.xml index 1afe4e99f9262..4118f5c5b45cf 100644 --- a/xml/System.ComponentModel/TypeDescriptionProvider.xml +++ b/xml/System.ComponentModel/TypeDescriptionProvider.xml @@ -163,9 +163,9 @@ specified by the `provider` parameter is passed in by the method of the class. If `provider` is not `null`, the service provider can be used by the type description provider to obtain additional context about the creation call. + The specified by the `provider` parameter is passed in by the method of the class. If `provider` is not `null`, the service provider can be used by the type description provider to obtain additional context about the creation call. - The method is `virtual` and, by default, returns the result of the method if `provider` is `null`. If `provider` is `null`, this method will invoke the method of the parent provider. + The method is `virtual` and, by default, returns the result of the method if `provider` is `null`. If `provider` is `null`, this method will invoke the method of the parent provider. ]]> diff --git a/xml/System.ComponentModel/TypeDescriptor.xml b/xml/System.ComponentModel/TypeDescriptor.xml index e0afc83929766..a73d9083f5736 100644 --- a/xml/System.ComponentModel/TypeDescriptor.xml +++ b/xml/System.ComponentModel/TypeDescriptor.xml @@ -26,7 +26,7 @@ namespace, and the class. Reflection is a general mechanism available to all types because its foundation is established in the method of the root class. The information it returns for a type is not extensible, in that it cannot be modified after compilation of the target type. For more information, see the topics in [Reflection](~/docs/framework/reflection-and-codedom/reflection.md). + The .NET Framework provides two ways to access metadata on a type: the reflection API provided in the namespace, and the class. Reflection is a general mechanism available to all types because its foundation is established in the method of the root class. The information it returns for a type is not extensible, in that it cannot be modified after compilation of the target type. For more information, see the topics in [Reflection](~/docs/framework/reflection-and-codedom/reflection.md). In contrast, is an extensible inspection mechanism for components: those classes that implement the interface. Unlike reflection, it does not inspect for methods. can be dynamically extended by several services available through the target component's . The following table shows these services. @@ -908,10 +908,10 @@ ## Remarks The attributes returned by the method may be dynamically modified from the original component's source listing by extender providers (), filter services (), and attribute filters. - When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. + When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. > [!NOTE] -> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. +> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. @@ -957,12 +957,12 @@ ## Remarks Call this version of this method only when you do not have an instance of the object. - For attributes with set to `true`, the attribute collection removes duplicate instances. These are instances in which the property returns equal values. + For attributes with set to `true`, the attribute collection removes duplicate instances. These are instances in which the property returns equal values. - When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. + When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. > [!NOTE] -> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. +> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. ]]> @@ -1011,10 +1011,10 @@ ## Remarks The attributes returned by the method may be dynamically modified from the original components source listing by extender providers (), filter services (), and attribute filters. - When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. + When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. > [!NOTE] -> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. +> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. ]]> diff --git a/xml/System.Configuration.Install/Installer.xml b/xml/System.Configuration.Install/Installer.xml index 96195e5dc0288..b3199fe3c174e 100644 --- a/xml/System.Configuration.Install/Installer.xml +++ b/xml/System.Configuration.Install/Installer.xml @@ -43,7 +43,7 @@ Two situations illustrate the need to save information in the state-saver . First, suppose that your installer sets a registry key. It should save the key's original value in the . If the installation is rolled back, the original value can be restored. Second, suppose the installer replaces an existing file. Save the existing file in a temporary directory and the location of the new location of the file in the . If the installation is rolled back, the newer file is deleted and replaced by the original from the temporary location. - The property contains information about the installation. For example, information about the location of the log file for the installation, the location of the file to save information required by the method, and the command line that was entered when the installation executable was run. + The property contains information about the installation. For example, information about the location of the log file for the installation, the location of the file to save information required by the method, and the command line that was entered when the installation executable was run. diff --git a/xml/System.Configuration.Install/InstallerCollection.xml b/xml/System.Configuration.Install/InstallerCollection.xml index b7376f07d56f3..d9e9ae8701cd0 100644 --- a/xml/System.Configuration.Install/InstallerCollection.xml +++ b/xml/System.Configuration.Install/InstallerCollection.xml @@ -28,7 +28,7 @@ Remove installers through the method. Check whether an installer is in the collection by using the method. Find where an installer is located in the collection by using the method. - The installers in a collection are run when the installer containing the collection, as specified by the property, calls their , , , or methods. + The installers in a collection are run when the installer containing the collection, as specified by the property, calls their , , , or methods. For examples of the usage of an installer collection, see the and classes. diff --git a/xml/System.Configuration.Provider/ProviderCollection.xml b/xml/System.Configuration.Provider/ProviderCollection.xml index a5a4bf2b54657..1b84645bebb2e 100644 --- a/xml/System.Configuration.Provider/ProviderCollection.xml +++ b/xml/System.Configuration.Provider/ProviderCollection.xml @@ -82,7 +82,7 @@ method first checks for any exceptions (as listed in the Exceptions section), and then calls the method. It passes in the object referenced by the `provider` parameter as well as the property of the provider to be used as the key in the object. + The method first checks for any exceptions (as listed in the Exceptions section), and then calls the method. It passes in the object referenced by the `provider` parameter as well as the property of the provider to be used as the key in the object. ]]> @@ -199,7 +199,7 @@ class stores its collection in a object. The method calls the method. + The class stores its collection in a object. The method calls the method. ]]> diff --git a/xml/System.Configuration/ApplicationSettingsBase.xml b/xml/System.Configuration/ApplicationSettingsBase.xml index eac6e300e3b97..c9f8b94df3c30 100644 --- a/xml/System.Configuration/ApplicationSettingsBase.xml +++ b/xml/System.Configuration/ApplicationSettingsBase.xml @@ -691,7 +691,7 @@ ## Remarks The method overwrites the user-scoped settings properties by restoring the currently persisted value of each application settings. This method performs the following actions: -- It calls the method on every settings provider that supports this optional method. +- It calls the method on every settings provider that supports this optional method. - It calls the method to force a refresh of the settings property values. @@ -933,7 +933,7 @@ ## Remarks The method performs two actions to assure smooth transition to a new version of an application: -- It notifies all of the corresponding settings providers of the existence of the upgraded application through a call to their method, assuming they have implemented the interface. This action is not performed if the settings wrapper class is marked with . +- It notifies all of the corresponding settings providers of the existence of the upgraded application through a call to their method, assuming they have implemented the interface. This action is not performed if the settings wrapper class is marked with . - It reloads the values for all of the application settings. diff --git a/xml/System.Configuration/CommaDelimitedStringCollection.xml b/xml/System.Configuration/CommaDelimitedStringCollection.xml index 2732e3c5f18bb..f58807eb015e3 100644 --- a/xml/System.Configuration/CommaDelimitedStringCollection.xml +++ b/xml/System.Configuration/CommaDelimitedStringCollection.xml @@ -291,7 +291,7 @@ method on the class. + This property returns `true` if the collection is marked as read-only. This is useful for protecting the element at run time, as opposed to design time. For more information, see the method on the class. diff --git a/xml/System.Configuration/ConfigurationPermission.xml b/xml/System.Configuration/ConfigurationPermission.xml index f505ff42368b8..063bf69b13209 100644 --- a/xml/System.Configuration/ConfigurationPermission.xml +++ b/xml/System.Configuration/ConfigurationPermission.xml @@ -111,7 +111,7 @@ interface, an exception will be thrown if calling the method on the object referenced by the `target` parameter does not return . + Although the method signature accepts any object that implements the interface, an exception will be thrown if calling the method on the object referenced by the `target` parameter does not return . ]]> @@ -143,7 +143,7 @@ interface, an exception will be thrown if calling the method on the object referenced by the `target` parameter does not return . + Although the method signature accepts any object that implements the interface, an exception will be thrown if calling the method on the object referenced by the `target` parameter does not return . If the object referenced by the `target` parameter is `null`, the comparison is done between the permission state of the object and the value of the enumeration. diff --git a/xml/System.Configuration/ConfigurationProperty.xml b/xml/System.Configuration/ConfigurationProperty.xml index 0645295f41a07..24c599ae9df47 100644 --- a/xml/System.Configuration/ConfigurationProperty.xml +++ b/xml/System.Configuration/ConfigurationProperty.xml @@ -119,7 +119,7 @@ ## Examples - The following code example shows how to use the constructor to instantiate a configuration-property object. + The following code example shows how to use the constructor to instantiate a configuration-property object. [!code-csharp[System.Configuration.ConfigurationProperty#2](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/CS/ConfigurationProperty.cs#2)] [!code-vb[System.Configuration.ConfigurationProperty#2](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/VB/ConfigurationProperty.vb#2)] @@ -158,7 +158,7 @@ constructor to instantiate a configuration-property object. + The following code example shows how to use constructor to instantiate a configuration-property object. [!code-csharp[System.Configuration.ConfigurationProperty#3](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/CS/ConfigurationProperty.cs#3)] [!code-vb[System.Configuration.ConfigurationProperty#3](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/VB/ConfigurationProperty.vb#3)] @@ -201,7 +201,7 @@ constructor. + The following code example shows the kind of parameters to use when calling the constructor. [!code-csharp[System.Configuration.ConfigurationProperty#4](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/CS/ConfigurationProperty.cs#4)] [!code-vb[System.Configuration.ConfigurationProperty#4](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/VB/ConfigurationProperty.vb#4)] @@ -246,7 +246,7 @@ constructor to instantiate a configuration-property object. + The following code example shows how to use the constructor to instantiate a configuration-property object. [!code-csharp[System.Configuration.ConfigurationProperty#4](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/CS/ConfigurationProperty.cs#4)] [!code-vb[System.Configuration.ConfigurationProperty#4](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/VB/ConfigurationProperty.vb#4)] diff --git a/xml/System.Configuration/ConfigurationUserLevel.xml b/xml/System.Configuration/ConfigurationUserLevel.xml index de8b9726559ea..f2630e4b483e3 100644 --- a/xml/System.Configuration/ConfigurationUserLevel.xml +++ b/xml/System.Configuration/ConfigurationUserLevel.xml @@ -19,7 +19,7 @@ to specify which configuration file is to be represented by the Configuration object returned by and . + Use to specify which configuration file is to be represented by the Configuration object returned by and . Application configuration files are in the same directory as the application and have the same name, but with a .config extension. For example, the configuration file for C:\System\Public.exe is C:\System\Public.exe.config. diff --git a/xml/System.Configuration/ExeConfigurationFileMap.xml b/xml/System.Configuration/ExeConfigurationFileMap.xml index 850c1bb987221..b93ff0014a5c8 100644 --- a/xml/System.Configuration/ExeConfigurationFileMap.xml +++ b/xml/System.Configuration/ExeConfigurationFileMap.xml @@ -25,7 +25,7 @@ ## Examples - For an example that shows how to use this class, see the method. + For an example that shows how to use this class, see the method. ]]> diff --git a/xml/System.Configuration/IPersistComponentSettings.xml b/xml/System.Configuration/IPersistComponentSettings.xml index 8765cd47b664c..c6e25bca297c8 100644 --- a/xml/System.Configuration/IPersistComponentSettings.xml +++ b/xml/System.Configuration/IPersistComponentSettings.xml @@ -203,13 +203,13 @@ The following general rules apply to the use of : -- A control, like any class, may contain zero or more application settings classes, derived from . Each settings class contains its own property, which helps disambiguate multiple instances of that class. +- A control, like any class, may contain zero or more application settings classes, derived from . Each settings class contains its own property, which helps disambiguate multiple instances of that class. - A control should separate its per-instance data and its shared data into different settings classes. - For a control with any per-instance configuration data, the `get` accessor of the property should default to the of the control. In most cases the name of the control will be unique within an application. If the control contains only shared configuration data, `get` should default to `null`. -- The `set` accessor for this property should be implemented to distinguish between settings classes containing per-instance and shared configuration data. For each settings class containing per-instance data, `set` should just pass-through to the property of the settings class. For settings classes containing shared data, `set` should perform no action for that settings class. +- The `set` accessor for this property should be implemented to distinguish between settings classes containing per-instance and shared configuration data. For each settings class containing per-instance data, `set` should just pass-through to the property of the settings class. For settings classes containing shared data, `set` should perform no action for that settings class. ]]> diff --git a/xml/System.Configuration/IdnElement.xml b/xml/System.Configuration/IdnElement.xml index b0568daba07e9..d681aae8b7f60 100644 --- a/xml/System.Configuration/IdnElement.xml +++ b/xml/System.Configuration/IdnElement.xml @@ -20,15 +20,15 @@ class has been extended to provide support for International Resource Identifiers (IRI) based on RFC 3987. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework. + The existing class has been extended to provide support for International Resource Identifiers (IRI) based on RFC 3987. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework. - The configuration setting for the is indirectly controlled by the configuration setting that controls IRI processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + The configuration setting for the is indirectly controlled by the configuration setting that controls IRI processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. The Internationalized Domain Name (IDN) attribute only controls IDN processing. All other IRI processing (character normalization, for example) is performed by default. - The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. + The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. - For more information on IRI support, see the Remarks section for the class. + For more information on IRI support, see the Remarks section for the class. ]]> @@ -90,11 +90,11 @@ ## Remarks The International Domain Name (IDN) attribute only controls IDN processing. All other International Resource Identifiers (IRI) processing (character normalization, for example) is performed by default. - The configuration setting for the is indirectly controlled by the configuration setting that controls IRI processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + The configuration setting for the is indirectly controlled by the configuration setting that controls IRI processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. - The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. + The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. - For more information on IRI support, see the Remarks section for the class. + For more information on IRI support, see the Remarks section for the class. ]]> diff --git a/xml/System.Configuration/IriParsingElement.xml b/xml/System.Configuration/IriParsingElement.xml index f9e6e899351fe..e1f679b179244 100644 --- a/xml/System.Configuration/IriParsingElement.xml +++ b/xml/System.Configuration/IriParsingElement.xml @@ -20,11 +20,11 @@ class has been extended to provide support for International Resource Identifiers (IRI) based on RFC 3987. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework. + The existing class has been extended to provide support for International Resource Identifiers (IRI) based on RFC 3987. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI. This ensures application compatibility with prior versions of the .NET Framework. - The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. + The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. - For more information on IRI support, see the Remarks section for the class. + For more information on IRI support, see the Remarks section for the class. ]]> @@ -84,11 +84,11 @@ configuration setting controls IRI processing in the class. This setting also indirectly controls International Domain Name (IDN) processing set with the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. + The configuration setting controls IRI processing in the class. This setting also indirectly controls International Domain Name (IDN) processing set with the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. - The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. + The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. - For more information on IRI support, see the Remarks section for the class. + For more information on IRI support, see the Remarks section for the class. ]]> diff --git a/xml/System.Configuration/PositiveTimeSpanValidatorAttribute.xml b/xml/System.Configuration/PositiveTimeSpanValidatorAttribute.xml index 4f3749547124a..d54a2e03bb54d 100644 --- a/xml/System.Configuration/PositiveTimeSpanValidatorAttribute.xml +++ b/xml/System.Configuration/PositiveTimeSpanValidatorAttribute.xml @@ -82,7 +82,7 @@ property to perform positive object validation by calling the method. + You use the property to perform positive object validation by calling the method. ]]> diff --git a/xml/System.Configuration/SchemeSettingElement.xml b/xml/System.Configuration/SchemeSettingElement.xml index 1ae9b3c263432..7829061ff9644 100644 --- a/xml/System.Configuration/SchemeSettingElement.xml +++ b/xml/System.Configuration/SchemeSettingElement.xml @@ -22,7 +22,7 @@ ## Remarks The class represents the \ element under the Uri section within a configuration file. The class represents an instance of an element in the class. - The class and the \ section in a configuration file looks generic, implying that an application can specify any enumeration value for any scheme. In fact, only the flag for HTTP and HTTPS schemes are supported. All other settings are ignored. + The class and the \ section in a configuration file looks generic, implying that an application can specify any enumeration value for any scheme. In fact, only the flag for HTTP and HTTPS schemes are supported. All other settings are ignored. ]]> @@ -75,7 +75,7 @@ property returns a enumeration value for the instance. + The property returns a enumeration value for the instance. ]]> @@ -109,7 +109,7 @@ property returns a enumeration value for the instance. + The property returns a enumeration value for the instance. The element is currently restricted to HTPP and HTTPS. diff --git a/xml/System.Configuration/SchemeSettingElementCollection.xml b/xml/System.Configuration/SchemeSettingElementCollection.xml index 63c008c3605ab..8786cca7654cb 100644 --- a/xml/System.Configuration/SchemeSettingElementCollection.xml +++ b/xml/System.Configuration/SchemeSettingElementCollection.xml @@ -27,9 +27,9 @@ ## Remarks The class represents the \ element under the Uri section within a configuration file. - The class and the \ section in a configuration file looks generic, implying that an application can specify any enumeration value for any scheme. In fact, only the flag for HTTP and HTTPS schemes are supported. All other settings are ignored. + The class and the \ section in a configuration file looks generic, implying that an application can specify any enumeration value for any scheme. In fact, only the flag for HTTP and HTTPS schemes are supported. All other settings are ignored. - By default, the class un-escapes percent encoded path delimiters before executing path compression. This was implemented as a security mechanism against attacks like the following: + By default, the class un-escapes percent encoded path delimiters before executing path compression. This was implemented as a security mechanism against attacks like the following: `http://www.contoso.com/..%2F..%2F/Windows/System32/cmd.exe?/c+dir+c:\` @@ -37,7 +37,7 @@ `c:\Windows\System32\cmd.exe /c dir c:\` - For this reason, class first un-escapes path delimiters and then applies path compression. The result of passing the malicious URL above to class constructor results in the following URI: + For this reason, class first un-escapes path delimiters and then applies path compression. The result of passing the malicious URL above to class constructor results in the following URI: `http://www.microsoft.com/Windows/System32/cmd.exe?/c+dir+c:\` diff --git a/xml/System.Configuration/SpecialSettingAttribute.xml b/xml/System.Configuration/SpecialSettingAttribute.xml index ccd5bb4f7fe76..66c1e11cc578f 100644 --- a/xml/System.Configuration/SpecialSettingAttribute.xml +++ b/xml/System.Configuration/SpecialSettingAttribute.xml @@ -25,7 +25,7 @@ is used to identify such properties. This class uses the enumeration to indicate what special category the property belongs to. + Certain application settings properties have a special significance that alters the way in which their associated settings provider should process them. The is used to identify such properties. This class uses the enumeration to indicate what special category the property belongs to. can only be applied to the settings class or to the individual settings property. diff --git a/xml/System.Configuration/StringValidator.xml b/xml/System.Configuration/StringValidator.xml index 6b9ef337d1338..9506c1579800b 100644 --- a/xml/System.Configuration/StringValidator.xml +++ b/xml/System.Configuration/StringValidator.xml @@ -20,7 +20,7 @@ class is used to ensure that a string meets specific criteria. The criteria for validation is established when an instance of the class is created. There are three constructor overloads for the class. The constructor with one parameter verifies the minimum acceptable length of the string being validated. The constructor with two parameters ensures that the string being verified adheres to both a minimum and a maximum length. The constructor with three parameters checks both the minimum and the maximum length values of the string being verified, as well as whether specific characters are present in the string being validated. + The class is used to ensure that a string meets specific criteria. The criteria for validation is established when an instance of the class is created. There are three constructor overloads for the class. The constructor with one parameter verifies the minimum acceptable length of the string being validated. The constructor with two parameters ensures that the string being verified adheres to both a minimum and a maximum length. The constructor with three parameters checks both the minimum and the maximum length values of the string being verified, as well as whether specific characters are present in the string being validated. The method determines whether the object type being validated matches the expected type. The object being validated is passed as a parameter of the method. diff --git a/xml/System.Configuration/UriSection.xml b/xml/System.Configuration/UriSection.xml index 19409bc071147..f78f25b7579cd 100644 --- a/xml/System.Configuration/UriSection.xml +++ b/xml/System.Configuration/UriSection.xml @@ -20,7 +20,7 @@ class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. + The existing class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. The configuration settings for IRI and IDN can be retrieved using the class. @@ -48,11 +48,11 @@ class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. + The existing class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. The configuration settings for IRI and IDN can be retrieved using the class. - For more information on IRI support, see the Remarks section for the class. + For more information on IRI support, see the Remarks section for the class. ]]> @@ -86,17 +86,17 @@ class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. + The existing class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. - The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IDN processing in the class. + The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IDN processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. The Internationalized Domain Name (IDN) attribute only controls IDN processing. All other IRI processing (character normalization, for example) is performed by default. - The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. + The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. - For more information on IRI support, see the Remarks section for the class. + For more information on IRI support, see the Remarks section for the class. ]]> @@ -130,17 +130,17 @@ class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. + The existing class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Current users will not see any change from the .NET Framework 2.0 behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. - The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IRI parsing in the class. + The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IRI parsing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. The Internationalized Domain Name (IDN) attribute only controls IDN processing. All other IRI processing (character normalization, for example) is performed by default. - The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. + The configuration setting for the will be read once when the first class is constructed. Changes to configuration settings after that time are ignored. - For more information on IRI support, see the Remarks section for the class. + For more information on IRI support, see the Remarks section for the class. ]]> diff --git a/xml/System.Data.Common/DataAdapter.xml b/xml/System.Data.Common/DataAdapter.xml index 2b02f2b4df4b4..a9dfdf61fa287 100644 --- a/xml/System.Data.Common/DataAdapter.xml +++ b/xml/System.Data.Common/DataAdapter.xml @@ -1251,7 +1251,7 @@ 6. The event is raised. -7. is called. This will raise both the and events for the updated . +7. is called. This will raise both the and events for the updated . Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. diff --git a/xml/System.Data.Common/DataTableMapping.xml b/xml/System.Data.Common/DataTableMapping.xml index 62f8831d4fe08..7d2427ca47e41 100644 --- a/xml/System.Data.Common/DataTableMapping.xml +++ b/xml/System.Data.Common/DataTableMapping.xml @@ -472,7 +472,7 @@ ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> diff --git a/xml/System.Data.Common/DataTableMappingCollection.xml b/xml/System.Data.Common/DataTableMappingCollection.xml index d7f9fedcb6133..e17d1a4de9e0f 100644 --- a/xml/System.Data.Common/DataTableMappingCollection.xml +++ b/xml/System.Data.Common/DataTableMappingCollection.xml @@ -1295,7 +1295,7 @@ ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> diff --git a/xml/System.Data.Common/DbConnection.xml b/xml/System.Data.Common/DbConnection.xml index 94a79c0e262bd..91cda8e19ed06 100644 --- a/xml/System.Data.Common/DbConnection.xml +++ b/xml/System.Data.Common/DbConnection.xml @@ -790,7 +790,7 @@ will throw an exception if called again without first being closed. + This method must be overridden with user-defined behavior. will throw an exception if called again without first being closed. ]]> diff --git a/xml/System.Data.Common/DbDataAdapter.xml b/xml/System.Data.Common/DbDataAdapter.xml index a9397c5a5484c..d27bb22c18e09 100644 --- a/xml/System.Data.Common/DbDataAdapter.xml +++ b/xml/System.Data.Common/DbDataAdapter.xml @@ -2102,7 +2102,7 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> diff --git a/xml/System.Data.Common/DbParameter.xml b/xml/System.Data.Common/DbParameter.xml index b9fcff17abb05..bd9acc01f821c 100644 --- a/xml/System.Data.Common/DbParameter.xml +++ b/xml/System.Data.Common/DbParameter.xml @@ -554,7 +554,7 @@ FieldName = @OriginalFieldName ## Remarks This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - For more information, see . + For more information, see . ]]> diff --git a/xml/System.Data.EntityClient/EntityDataReader.xml b/xml/System.Data.EntityClient/EntityDataReader.xml index 9f9823a183d11..d5e7308a9b9c5 100644 --- a/xml/System.Data.EntityClient/EntityDataReader.xml +++ b/xml/System.Data.EntityClient/EntityDataReader.xml @@ -28,7 +28,7 @@ does not implicitly consume result sets to make output parameters available. Therefore, note the following: -- calls the only when is explicitly called. If throws an exeption, the will wrap it in an (or a derived exception). +- calls the only when is explicitly called. If throws an exeption, the will wrap it in an (or a derived exception). - only closes the , without consuming any pending records or result sets. @@ -63,7 +63,7 @@ does not implicitly consume result sets to make output parameters available. Therefore, note the following: -- calls the only when is explicitly called. If throws an exception, will wrap it in (or a derived exception). +- calls the only when is explicitly called. If throws an exception, will wrap it in (or a derived exception). - only closes the , without consuming any pending records or result sets. @@ -143,7 +143,7 @@ does not implicitly consume result sets to make output parameters available. Therefore, note the following: -- calls the only when is explicitly called. If throws an exception, the will wrap it in an (or a derived exception). +- calls the only when is explicitly called. If throws an exception, the will wrap it in an (or a derived exception). - only closes the , without consuming any pending records or result sets. diff --git a/xml/System.Data.Linq.Mapping/ResultTypeAttribute.xml b/xml/System.Data.Linq.Mapping/ResultTypeAttribute.xml index b8921ff6033ce..eafb1b5a64978 100644 --- a/xml/System.Data.Linq.Mapping/ResultTypeAttribute.xml +++ b/xml/System.Data.Linq.Mapping/ResultTypeAttribute.xml @@ -23,7 +23,7 @@ ## Remarks This attribute applies to functions returning various result types. It is used to declare the possible result types returned from the function. For inheritance types, only the root type of the inheritance hierarchy needs to be specified. - See . + See . ]]> diff --git a/xml/System.Data.Linq/Binary.xml b/xml/System.Data.Linq/Binary.xml index 3f5d9eecf68d3..c0b414da1907b 100644 --- a/xml/System.Data.Linq/Binary.xml +++ b/xml/System.Data.Linq/Binary.xml @@ -43,7 +43,7 @@ exception is thrown. Do not rely on this behavior because it may change in the future. + When`null` is passed to this constructor instead of the required array of bytes, a exception is thrown. Do not rely on this behavior because it may change in the future. ]]> diff --git a/xml/System.Data.Linq/EntitySet`1.xml b/xml/System.Data.Linq/EntitySet`1.xml index 83b9359a53e3e..dce48685ba89b 100644 --- a/xml/System.Data.Linq/EntitySet`1.xml +++ b/xml/System.Data.Linq/EntitySet`1.xml @@ -682,7 +682,7 @@ customer.Orders.CopyTo(orderArray, 0) instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -711,7 +711,7 @@ customer.Orders.CopyTo(orderArray, 0) instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -759,7 +759,7 @@ customer.Orders.CopyTo(orderArray, 0) instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -788,7 +788,7 @@ customer.Orders.CopyTo(orderArray, 0) instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -1000,7 +1000,7 @@ customer.Orders.CopyTo(orderArray, 0) instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> diff --git a/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml b/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml index 981ece847136b..77dffd3f4fd25 100644 --- a/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml +++ b/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml @@ -284,7 +284,7 @@ method to compare the specified object with the objects already in the collection. + Uses the method to compare the specified object with the objects already in the collection. @@ -479,7 +479,7 @@ This method calls the internal `RelatedEnd.ValidateLoad` method before loading t > [!NOTE] > When you call the method during a `foreach` (C#) or `For Each` (Visual Basic) enumeration, Object Services tries to open a new data reader. This operation will fail unless you have enabled multiple active results sets by specifying `multipleactiveresultsets=true` in the connection string. You can also load the result of the query into a collection. This closes the data reader and enables you to enumerate over the collection to load referenced objects. - The method is synchronized with the method. + The method is synchronized with the method. diff --git a/xml/System.Data.Objects.DataClasses/RelatedEnd.xml b/xml/System.Data.Objects.DataClasses/RelatedEnd.xml index d486615a7c2eb..9225142f2aba2 100644 --- a/xml/System.Data.Objects.DataClasses/RelatedEnd.xml +++ b/xml/System.Data.Objects.DataClasses/RelatedEnd.xml @@ -55,17 +55,17 @@ ## Remarks The event is raised by the following methods: -- +- -- +- -- +- -- +- -- +- -- +- Events may be suppressed during bulk operations, such as `Load`, , and . diff --git a/xml/System.Data.Objects/ObjectContext.xml b/xml/System.Data.Objects/ObjectContext.xml index 276f3fbc23255..f23c8cb434c20 100644 --- a/xml/System.Data.Objects/ObjectContext.xml +++ b/xml/System.Data.Objects/ObjectContext.xml @@ -1638,7 +1638,7 @@ or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -1672,7 +1672,7 @@ After calling , the related object can be accessed through the navigation properties of the source entity. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . When the method is called, objects are loaded into the by using the default value of . @@ -1715,7 +1715,7 @@ After calling , the related object can be accessed through the navigation properties of the source entity. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -1760,7 +1760,7 @@ The property to load is specified by a LINQ expression, which must be in the form of a simple property member access, as in `(entity) => entity.PropertyName`, where *PropertyName* is the navigation property that returns the related objects to be loaded. An exception will occur if other forms of the LINQ expression are used. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -1811,7 +1811,7 @@ The property to load is specified by a LINQ expression, which must be in the form of a simple property member access, as in `(entity) => entity.PropertyName` where *PropertyName* is the navigation property that returns the related objects to be loaded. An exception will occur if other forms of the LINQ expression are used. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> diff --git a/xml/System.Data.Objects/ObjectResult`1.xml b/xml/System.Data.Objects/ObjectResult`1.xml index d97aa035f9892..98a6123a62127 100644 --- a/xml/System.Data.Objects/ObjectResult`1.xml +++ b/xml/System.Data.Objects/ObjectResult`1.xml @@ -24,7 +24,7 @@ and . Instances of this class are returned from the method and from the method. + This class implements and . Instances of this class are returned from the method and from the method. diff --git a/xml/System.Data.Odbc/OdbcCommand.xml b/xml/System.Data.Odbc/OdbcCommand.xml index 9c3832da63b75..e21e27542aee8 100644 --- a/xml/System.Data.Odbc/OdbcCommand.xml +++ b/xml/System.Data.Odbc/OdbcCommand.xml @@ -755,7 +755,7 @@ SELECT * FROM Customers WHERE CustomerID = ? > [!NOTE] > The `SequentialAccess` value of is not a limiting setting; it just means that you will have at least sequential access to the . For example, when you use the SQL Server ODBC Driver in `SequentialAccess` mode, you can still move to the first column of an row after having read through all the other columns sequentially. - While the is used, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until you call the method. If the is created with set to `CloseConnection`, closing the closes the connection automatically. + While the is used, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until you call the method. If the is created with set to `CloseConnection`, closing the closes the connection automatically. ]]> diff --git a/xml/System.Data.Odbc/OdbcParameter.xml b/xml/System.Data.Odbc/OdbcParameter.xml index 73b157d638067..6afe6ab139760 100644 --- a/xml/System.Data.Odbc/OdbcParameter.xml +++ b/xml/System.Data.Odbc/OdbcParameter.xml @@ -163,7 +163,7 @@ OleDbDataReader reader = command.ExecuteReader(); Parameter = new OdbcParameter("@pname", Convert.ToInt32(0)); ``` - If you do not perform this conversion, the compiler assumes that you are trying to call the constructor overload. + If you do not perform this conversion, the compiler assumes that you are trying to call the constructor overload. ]]> diff --git a/xml/System.Data.Odbc/OdbcParameterCollection.xml b/xml/System.Data.Odbc/OdbcParameterCollection.xml index e290d526d5958..37bdcf5dd2588 100644 --- a/xml/System.Data.Odbc/OdbcParameterCollection.xml +++ b/xml/System.Data.Odbc/OdbcParameterCollection.xml @@ -193,7 +193,7 @@ INSERT INTO MyTable VALUES (@p1, @p2, @p3); parameters.Add("@pname", Convert.ToInt32(0)); ``` - If you do not perform this conversion, the compiler will assume you are attempting to call the overload. + If you do not perform this conversion, the compiler will assume you are attempting to call the overload. ]]> diff --git a/xml/System.Data.OracleClient/OracleBinary.xml b/xml/System.Data.OracleClient/OracleBinary.xml index f28c7d5b1b77e..e32fea1654f73 100644 --- a/xml/System.Data.OracleClient/OracleBinary.xml +++ b/xml/System.Data.OracleClient/OracleBinary.xml @@ -429,7 +429,7 @@ In Visual Basic, you can use the operators defined by a class, but you cannot override them or create your own. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -455,7 +455,7 @@ Compares two structures to determine if they are equal. An that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -503,7 +503,7 @@ Compares two structures to determine if the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -529,7 +529,7 @@ Compares two structures to determine if the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -577,7 +577,7 @@ Compares two structures to determine if they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -603,7 +603,7 @@ Compares two structures to determine if the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -629,7 +629,7 @@ Compares two structures to determine if the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleBoolean.xml b/xml/System.Data.OracleClient/OracleBoolean.xml index 7cb1ef5fece89..d7d04225fed52 100644 --- a/xml/System.Data.OracleClient/OracleBoolean.xml +++ b/xml/System.Data.OracleClient/OracleBoolean.xml @@ -431,7 +431,7 @@ - ]]> + ]]> @@ -461,7 +461,7 @@ - ]]> + ]]> @@ -487,7 +487,7 @@ Compares two instances of an for equality. An that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -517,7 +517,7 @@ - ]]> + ]]> @@ -608,7 +608,7 @@ if the supplied parameter is false; otherwise . - ]]> + ]]> @@ -656,7 +656,7 @@ Compares two instances of for inequality. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -702,7 +702,7 @@ Performs a one's complement operation on the specified . The one's complement of the specified . - ]]> + ]]> @@ -727,7 +727,7 @@ if the supplied parameter is true; otherwise . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleConnection.xml b/xml/System.Data.OracleClient/OracleConnection.xml index 76c23856d8064..5fbcd848e70cb 100644 --- a/xml/System.Data.OracleClient/OracleConnection.xml +++ b/xml/System.Data.OracleClient/OracleConnection.xml @@ -45,7 +45,7 @@ ## Examples - The following example creates an and an . The is opened and set as the property. The example then calls , and closes the connection. To accomplish this, the is passed a connection string and a query string that is an SQL INSERT statement. + The following example creates an and an . The is opened and set as the property. The example then calls , and closes the connection. To accomplish this, the is passed a connection string and a query string that is an SQL INSERT statement. [!code-csharp[Classic WebData OracleConnection#1](~/samples/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleConnection/CS/source.cs#1)] [!code-vb[Classic WebData OracleConnection#1](~/samples/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData OracleConnection/VB/source.vb#1)] diff --git a/xml/System.Data.OracleClient/OracleDateTime.xml b/xml/System.Data.OracleClient/OracleDateTime.xml index 6584345a92ddb..9fcbe05a37793 100644 --- a/xml/System.Data.OracleClient/OracleDateTime.xml +++ b/xml/System.Data.OracleClient/OracleDateTime.xml @@ -684,7 +684,7 @@ if the two values are equal, otherwise . - ]]> + ]]> @@ -754,7 +754,7 @@ Compares two instances of to determine if the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -780,7 +780,7 @@ Compares two instances of to determine if the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -806,7 +806,7 @@ Performs a logical comparison of two instances of to determine if they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -832,7 +832,7 @@ Compares two instances of to determine if the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -858,7 +858,7 @@ Compares two instances of to determine if the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleMonthSpan.xml b/xml/System.Data.OracleClient/OracleMonthSpan.xml index d78d87af1bc5f..6ea9714ae0cc3 100644 --- a/xml/System.Data.OracleClient/OracleMonthSpan.xml +++ b/xml/System.Data.OracleClient/OracleMonthSpan.xml @@ -433,7 +433,7 @@ if the two values are equal, otherwise . - ]]> + ]]> @@ -503,7 +503,7 @@ Compares two instances of to determine if the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -529,7 +529,7 @@ Compares two instances of to determine if the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -555,7 +555,7 @@ Performs a logical comparison of two instances of to determine if they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -581,7 +581,7 @@ Compares two instances of to determine if the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -607,7 +607,7 @@ Compares two instances of to determine if the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleNumber.xml b/xml/System.Data.OracleClient/OracleNumber.xml index 0c68fea375f21..216b9164cd93a 100644 --- a/xml/System.Data.OracleClient/OracleNumber.xml +++ b/xml/System.Data.OracleClient/OracleNumber.xml @@ -1077,7 +1077,7 @@ Calculates the sum of the two structures. A new structure whose property contains the sum. - ]]> + ]]> @@ -1103,7 +1103,7 @@ Calculates the results of dividing the first structure by the second. A new structure whose property contains the results of the division. - ]]> + ]]> @@ -1129,7 +1129,7 @@ Performs a logical comparison of the two structures to determine whether they are equal. An that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -1353,7 +1353,7 @@ Performs a logical comparison of two structures to determine whether the first is greater than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -1379,7 +1379,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -1405,7 +1405,7 @@ Performs a logical comparison of the two parameters to determine whether they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -1431,7 +1431,7 @@ Performs a logical comparison of two structures to determine whether the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -1457,7 +1457,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -1483,7 +1483,7 @@ Calculates the remainder left over from dividing an structure by a second structure. A new structure whose property contains the modulus of the division. - ]]> + ]]> @@ -1509,7 +1509,7 @@ Calculates the product of two structures. A new structure whose property contains the product of the multiplication. - ]]> + ]]> @@ -1535,7 +1535,7 @@ Calculates the result of subtracting the second structure from the first. A new structure whose property contains the results of the subtraction. - ]]> + ]]> @@ -1559,7 +1559,7 @@ Negates the structure. A new structure whose value contains the results of the negation. - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleParameter.xml b/xml/System.Data.OracleClient/OracleParameter.xml index 361a72de8ff62..e117af88a932a 100644 --- a/xml/System.Data.OracleClient/OracleParameter.xml +++ b/xml/System.Data.OracleClient/OracleParameter.xml @@ -877,7 +877,7 @@ FieldName = @OriginalFieldName during the to determine whether the original or current value is used for a parameter value. This lets primary keys be updated. This property is set to the version of the used by the property ( indexer), or the method of the object. + This property is used by the during the to determine whether the original or current value is used for a parameter value. This lets primary keys be updated. This property is set to the version of the used by the property ( indexer), or the method of the object. diff --git a/xml/System.Data.OracleClient/OracleString.xml b/xml/System.Data.OracleClient/OracleString.xml index dc178dc8c1efa..343456cb3455b 100644 --- a/xml/System.Data.OracleClient/OracleString.xml +++ b/xml/System.Data.OracleClient/OracleString.xml @@ -480,7 +480,7 @@ public class Class1 { Concatenates the two specified structures. An containing the newly concatenated value representing the contents of the two parameters. - ]]> + ]]> @@ -506,7 +506,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if they are equal. An that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -554,7 +554,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -580,7 +580,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -628,7 +628,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -654,7 +654,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -680,7 +680,7 @@ public class Class1 { Performs a logical comparison of the two operands to determine if the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the will be . - ]]> + ]]> diff --git a/xml/System.Data.OracleClient/OracleTimeSpan.xml b/xml/System.Data.OracleClient/OracleTimeSpan.xml index b33dc0e5e04ac..ef80c57da36e8 100644 --- a/xml/System.Data.OracleClient/OracleTimeSpan.xml +++ b/xml/System.Data.OracleClient/OracleTimeSpan.xml @@ -573,7 +573,7 @@ if the two values are equal, otherwise . - ]]> + ]]> @@ -643,7 +643,7 @@ Compares two instances of to determine whether the first is greater than the second. An that is if the first instance is greater than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -669,7 +669,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. An that is if the first instance is greater than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -695,7 +695,7 @@ Performs a logical comparison of two instances of to determine whether they are equal. An that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the is . - ]]> + ]]> @@ -721,7 +721,7 @@ Compares two instances of to determine whether the first is less than the second. An that is if the first instance is less than the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> @@ -747,7 +747,7 @@ Compares two instances of to determine whether the first is less than or equal to the second. An that is if the first instance is less than or equal to the second instance, otherwise . If either instance of is null, the of the is . - ]]> + ]]> diff --git a/xml/System.Data.SqlClient/SqlConnection.xml b/xml/System.Data.SqlClient/SqlConnection.xml index 2c91b581bd5f2..142f43c158ef6 100644 --- a/xml/System.Data.SqlClient/SqlConnection.xml +++ b/xml/System.Data.SqlClient/SqlConnection.xml @@ -368,7 +368,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) You must explicitly commit or roll back the transaction using the or method. To make sure that the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] Data Provider for [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] transaction management model performs correctly, avoid using other transaction management models, such as the one provided by [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)]. > [!NOTE] -> After a transaction is committed or rolled back, the isolation level of the transaction persists for all subsequent commands that are in autocommit mode (the [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] default). This can produce unexpected results, such as an isolation level of REPEATABLE READ persisting and locking other users out of a row. To reset the isolation level to the default (READ COMMITTED), execute the [!INCLUDE[tsql](~/includes/tsql-md.md)] SET TRANSACTION ISOLATION LEVEL READ COMMITTED statement, or call followed immediately by . For more information on [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] isolation levels, see "Isolation Levels in the Database Engine" in [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] Books Online. +> After a transaction is committed or rolled back, the isolation level of the transaction persists for all subsequent commands that are in autocommit mode (the [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] default). This can produce unexpected results, such as an isolation level of REPEATABLE READ persisting and locking other users out of a row. To reset the isolation level to the default (READ COMMITTED), execute the [!INCLUDE[tsql](~/includes/tsql-md.md)] SET TRANSACTION ISOLATION LEVEL READ COMMITTED statement, or call followed immediately by . For more information on [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] isolation levels, see "Isolation Levels in the Database Engine" in [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] Books Online. For more information on [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] transactions, see "Explicit Transactions" and "Coding Efficient Transactions" in [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] Books Online. @@ -491,7 +491,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) You must explicitly commit or roll back the transaction using the or method. To make sure that the [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] transaction management model performs correctly, avoid using other transaction management models, such as the one provided by [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)]. > [!NOTE] -> After a transaction is committed or rolled back, the isolation level of the transaction persists for all subsequent commands that are in autocommit mode (the [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] default). This can produce unexpected results, such as an isolation level of REPEATABLE READ persisting and locking other users out of a row. To reset the isolation level to the default (READ COMMITTED), execute the [!INCLUDE[tsql](~/includes/tsql-md.md)] SET TRANSACTION ISOLATION LEVEL READ COMMITTED statement, or call followed immediately by . For more information on [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] isolation levels, see "Isolation Levels in the Database Engine" in [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] Books Online. +> After a transaction is committed or rolled back, the isolation level of the transaction persists for all subsequent commands that are in autocommit mode (the [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] default). This can produce unexpected results, such as an isolation level of REPEATABLE READ persisting and locking other users out of a row. To reset the isolation level to the default (READ COMMITTED), execute the [!INCLUDE[tsql](~/includes/tsql-md.md)] SET TRANSACTION ISOLATION LEVEL READ COMMITTED statement, or call followed immediately by . For more information on [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] isolation levels, see "Isolation Levels in the Database Engine" in [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] Books Online. For more information on [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] transactions, see "Explicit Transactions" and "Coding Efficient Transactions" in [!INCLUDE[ssNoVersion](~/includes/ssnoversion-md.md)] Books Online. diff --git a/xml/System.Data.SqlClient/SqlDataReader.xml b/xml/System.Data.SqlClient/SqlDataReader.xml index 090e12a57502d..80993945986b4 100644 --- a/xml/System.Data.SqlClient/SqlDataReader.xml +++ b/xml/System.Data.SqlClient/SqlDataReader.xml @@ -38,7 +38,7 @@ and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. - When using sequential access (), an will be raised if the position is advanced and another read operation is attempted on the previous column. + When using sequential access (), an will be raised if the position is advanced and another read operation is attempted on the previous column. > [!NOTE] > For optimal performance, avoids creating unnecessary objects or making unnecessary copies of data. Therefore, multiple calls to methods such as return a reference to the same object. Use caution if you are modifying the underlying value of the objects returned by methods such as . diff --git a/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml b/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml index 7ee3532735a5a..878dd69c5f1af 100644 --- a/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml +++ b/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml @@ -94,7 +94,7 @@ If you call the **Close** method from , an exception is generated, and the object state does not change. - If an application specifically creates a object in the constructor, the transaction is not rolled back. The application is responsible for determining whether it is required to rollback the operation, and if so, it must call the method. If the application does not create a transaction, the internal transaction corresponding to the current batch is automatically rolled back. However, changes related to previous batches within the bulk copy operation are retained, because the transactions for them already have been committed. + If an application specifically creates a object in the constructor, the transaction is not rolled back. The application is responsible for determining whether it is required to rollback the operation, and if so, it must call the method. If the application does not create a transaction, the internal transaction corresponding to the current batch is automatically rolled back. However, changes related to previous batches within the bulk copy operation are retained, because the transactions for them already have been committed. ]]> diff --git a/xml/System.Data.SqlTypes/SqlBinary.xml b/xml/System.Data.SqlTypes/SqlBinary.xml index 39a9c24edfdfd..91f985ebd4a77 100644 --- a/xml/System.Data.SqlTypes/SqlBinary.xml +++ b/xml/System.Data.SqlTypes/SqlBinary.xml @@ -810,7 +810,7 @@ ## Remarks `x` will appear first in the resulting , followed by `y`. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -849,7 +849,7 @@ Compares two structures to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -958,7 +958,7 @@ Compares two structures to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -997,7 +997,7 @@ Compares two structues to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1071,7 +1071,7 @@ Compares two structures to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1110,7 +1110,7 @@ Compares two structures to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1149,7 +1149,7 @@ Compares two structures to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise . If either instance of is null, the of the will be . - ]]> + ]]> diff --git a/xml/System.Data.SqlTypes/SqlBoolean.xml b/xml/System.Data.SqlTypes/SqlBoolean.xml index 378bb1d691eed..edb74a7d04288 100644 --- a/xml/System.Data.SqlTypes/SqlBoolean.xml +++ b/xml/System.Data.SqlTypes/SqlBoolean.xml @@ -1020,7 +1020,7 @@ Computes the bitwise OR of its operands. The results of the logical OR operation. - .]]> + .]]> @@ -1059,7 +1059,7 @@ Compares two instances of for equality. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -1098,7 +1098,7 @@ Performs a bitwise exclusive-OR (XOR) operation on the supplied parameters. The result of the logical XOR operation. - .]]> + .]]> @@ -1485,7 +1485,7 @@ The false operator can be used to test the of the to determine whether it is false. Returns if the supplied parameter is is false, otherwise. - .]]> + .]]> @@ -1529,7 +1529,7 @@ ## Remarks If either instance of `x` or `y` is null, the value of the will be null. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -1573,7 +1573,7 @@ ## Remarks If either instance of `x` or `y` is null, the value of the will be null. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -1647,7 +1647,7 @@ Compares two instances of to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -1691,7 +1691,7 @@ ## Remarks If either instance of `x` or `y` is null, the value of the will be null. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -1735,7 +1735,7 @@ ## Remarks If either instance of `x` or `y` is null, the value of the will be null. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -1807,7 +1807,7 @@ Performs a one's complement operation on the supplied structures. The one's complement of the supplied . - .]]> + .]]> @@ -1844,7 +1844,7 @@ The true operator can be used to test the of the to determine whether it is true. Returns if the supplied parameter is is true, otherwise. - .]]> + .]]> diff --git a/xml/System.Data.SqlTypes/SqlByte.xml b/xml/System.Data.SqlTypes/SqlByte.xml index 89ba59045439c..3765fd92f2837 100644 --- a/xml/System.Data.SqlTypes/SqlByte.xml +++ b/xml/System.Data.SqlTypes/SqlByte.xml @@ -996,7 +996,7 @@ Computes the sum of the two specified structures. A whose property contains the sum of the two operands. - ]]> + ]]> @@ -1035,7 +1035,7 @@ Computes the bitwise AND of its operands. The results of the bitwise AND operation. - ]]> + ]]> @@ -1074,7 +1074,7 @@ Computes the bitwise OR of its two operands. The results of the bitwise OR operation. - ]]> + ]]> @@ -1113,7 +1113,7 @@ Divides its first operand by its second. A new structure whose property contains the results of the division. - ]]> + ]]> @@ -1152,7 +1152,7 @@ Performs a logical comparison of two structures to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1580,7 +1580,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1619,7 +1619,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1732,7 +1732,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1810,7 +1810,7 @@ Computes the remainder after dividing its first operand by its second. A structure whose contains the remainder. - ]]> + ]]> @@ -1849,7 +1849,7 @@ Computes the product of the two operands. A new structure whose property contains the product of the multiplication. - ]]> + ]]> @@ -1886,7 +1886,7 @@ The ones complement operator performs a bitwise one's complement operation on its operand. A structure whose property contains the ones complement of the parameter. - ]]> + ]]> diff --git a/xml/System.Data.SqlTypes/SqlDateTime.xml b/xml/System.Data.SqlTypes/SqlDateTime.xml index e3becc0af5ae1..a4ea0eb8deb9b 100644 --- a/xml/System.Data.SqlTypes/SqlDateTime.xml +++ b/xml/System.Data.SqlTypes/SqlDateTime.xml @@ -997,7 +997,7 @@ if the two values are equal. Otherwise, . - ]]> + ]]> @@ -1106,7 +1106,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1145,7 +1145,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1256,7 +1256,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1295,7 +1295,7 @@ Compares two instances of to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> diff --git a/xml/System.Data.SqlTypes/SqlDecimal.xml b/xml/System.Data.SqlTypes/SqlDecimal.xml index 48895e7b0155e..5f7cfa4aef0e8 100644 --- a/xml/System.Data.SqlTypes/SqlDecimal.xml +++ b/xml/System.Data.SqlTypes/SqlDecimal.xml @@ -1333,7 +1333,7 @@ Calculates the sum of the two operators. A new structure whose property contains the sum. - .]]> + .]]> @@ -1372,7 +1372,7 @@ The division operator calculates the results of dividing the first operand by the second. A new structure whose property contains the results of the division. - .]]> + .]]> @@ -1411,7 +1411,7 @@ Performs a logical comparison of the two operands to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -1660,7 +1660,7 @@ Performs a logical comparison of two structures to determine whether the first is greater than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1699,7 +1699,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1983,7 +1983,7 @@ Performs a logical comparison of the two parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -2022,7 +2022,7 @@ Performs a logical comparison of two structures to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -2061,7 +2061,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -2100,7 +2100,7 @@ The multiplication operator computes the product of the two parameters. A new structure whose property contains the product of the multiplication. - .]]> + .]]> @@ -2139,7 +2139,7 @@ Calculates the results of subtracting the second operand from the first. A new structure whose Value property contains the results of the subtraction. - .]]> + .]]> diff --git a/xml/System.Data.SqlTypes/SqlDouble.xml b/xml/System.Data.SqlTypes/SqlDouble.xml index 2f265a74b7ec0..e0b17683b4a64 100644 --- a/xml/System.Data.SqlTypes/SqlDouble.xml +++ b/xml/System.Data.SqlTypes/SqlDouble.xml @@ -260,7 +260,7 @@ The division operator divides the first operand by the second. A structure that contains the results of the division operation. - ]]> + ]]> @@ -697,7 +697,7 @@ The multiplication operator computes the product of the two operands. The product of the two operands. - ]]> + ]]> @@ -810,7 +810,7 @@ The addition operator computes the sum of the two operands. The sum of the two operands. - ]]> + ]]> @@ -849,7 +849,7 @@ The division operator divides the first operand by the second. A structure that contains the results of the division operation. - ]]> + ]]> @@ -889,7 +889,7 @@ if the two values are equal. Otherwise, . - ]]> + ]]> @@ -1033,7 +1033,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1072,7 +1072,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1391,7 +1391,7 @@ Compares two instances of to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1430,7 +1430,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1469,7 +1469,7 @@ Compares two instances of to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1508,7 +1508,7 @@ The multiplication operator computes the product of the two operands. The product of the two operands. - ]]> + ]]> @@ -1547,7 +1547,7 @@ The subtraction operator the second operand from the first. The results of the subtraction operation. - ]]> + ]]> diff --git a/xml/System.Data.SqlTypes/SqlGuid.xml b/xml/System.Data.SqlTypes/SqlGuid.xml index bc25612e4bebd..65c45aedcb5b5 100644 --- a/xml/System.Data.SqlTypes/SqlGuid.xml +++ b/xml/System.Data.SqlTypes/SqlGuid.xml @@ -758,7 +758,7 @@ Performs a logical comparison of two structures to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -902,7 +902,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -941,7 +941,7 @@ Compares two instances of to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1015,7 +1015,7 @@ Performs a logical comparison on two structures to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -1054,7 +1054,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1093,7 +1093,7 @@ Compares two instances of to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> diff --git a/xml/System.Data.SqlTypes/SqlInt16.xml b/xml/System.Data.SqlTypes/SqlInt16.xml index 97830ef5f8aff..a7712b40ce0ae 100644 --- a/xml/System.Data.SqlTypes/SqlInt16.xml +++ b/xml/System.Data.SqlTypes/SqlInt16.xml @@ -989,7 +989,7 @@ Computes the sum of the two operands. A structure whose property contains the sum of the two operands. - .]]> + .]]> @@ -1028,7 +1028,7 @@ Computes the bitwise AND of its operands. A structure whose property contains the results of the bitwise AND. - .]]> + .]]> @@ -1067,7 +1067,7 @@ Computes the bitwise OR of its two operands. A structure whose property contains the results of the bitwise OR. - .]]> + .]]> @@ -1106,7 +1106,7 @@ Divides the first operand by the second. A whose property contains the results of the division. - .]]> + .]]> @@ -1145,7 +1145,7 @@ Performs a logical comparison of two structures to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -1184,7 +1184,7 @@ Performs a bitwise exclusive-OR operation on the supplied parameters. A structure whose property contains the results of the bitwise XOR. - .]]> + .]]> @@ -1538,7 +1538,7 @@ Compares two instances of to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1577,7 +1577,7 @@ Compares two structures to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1686,7 +1686,7 @@ Performs a logical comparison of two structures to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -1725,7 +1725,7 @@ Compares two instances of to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1764,7 +1764,7 @@ Compares two structures to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1803,7 +1803,7 @@ Computes the remainder after dividing its first operand by its second. A structure whose contains the remainder. - .]]> + .]]> @@ -1842,7 +1842,7 @@ Computes the product of the two parameters. A structure whose contains the product of the two parameters. - .]]> + .]]> @@ -1879,7 +1879,7 @@ The ~ operator performs a bitwise one's complement operation on its operand. A structure whose property contains the complement of the specified structure. - .]]> + .]]> @@ -1918,7 +1918,7 @@ Subtracts the second parameter from the first. A structure whose property contains the results of the subtraction. - .]]> + .]]> diff --git a/xml/System.Data.SqlTypes/SqlInt32.xml b/xml/System.Data.SqlTypes/SqlInt32.xml index ad038db40de2a..78daee9d389be 100644 --- a/xml/System.Data.SqlTypes/SqlInt32.xml +++ b/xml/System.Data.SqlTypes/SqlInt32.xml @@ -995,7 +995,7 @@ Computes the sum of the two specified structures. A structure whose property contains the sum of the specified structures. - ]]> + ]]> @@ -1034,7 +1034,7 @@ Computes the bitwise AND of its operands. A structure that contains the results of the bitwise AND operation. - ]]> + ]]> @@ -1073,7 +1073,7 @@ Computes the bitwise OR of the specified structures. A structure that contains the results of the bitwise OR operation. - ]]> + ]]> @@ -1112,7 +1112,7 @@ Divides the first parameter from the second. A whose property contains the results of the division. - ]]> + ]]> @@ -1151,7 +1151,7 @@ Performs a logical comparison of the two parameters to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1190,7 +1190,7 @@ Performs a bitwise exclusive-OR operation on the specified structures. A structure that contains the results of the bitwise XOR operation. - ]]> + ]]> @@ -1509,7 +1509,7 @@ Compares the two parameters to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1548,7 +1548,7 @@ Compares the two parameters to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1692,7 +1692,7 @@ Performa a logical comparison of the two parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1731,7 +1731,7 @@ Compares the two parameters to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1770,7 +1770,7 @@ Compares the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1809,7 +1809,7 @@ Computes the remainder after dividing the first parameter by the second. A structure whose contains the remainder. - ]]> + ]]> @@ -1848,7 +1848,7 @@ Computes the product of the two parameters. A structure whose contains the product of the two parameters. - ]]> + ]]> @@ -1885,7 +1885,7 @@ Performs a bitwise one's complement operation on the specified structure. A structure that contains the results of the one's complement operation. - ]]> + ]]> @@ -1924,7 +1924,7 @@ Subtracts the second parameter from the first. A structure whose property contains the results of the subtraction. - ]]> + ]]> diff --git a/xml/System.Data.SqlTypes/SqlInt64.xml b/xml/System.Data.SqlTypes/SqlInt64.xml index d76da162f7310..882a1fcf73c2b 100644 --- a/xml/System.Data.SqlTypes/SqlInt64.xml +++ b/xml/System.Data.SqlTypes/SqlInt64.xml @@ -996,7 +996,7 @@ Computes the sum of the two parameters. A new structure whose is equal to the sum of the two parameters. - ]]> + ]]> @@ -1035,7 +1035,7 @@ Computes the bitwise AND of its operands. A structure that contains the results of the bitwise AND operation. - ]]> + ]]> @@ -1074,7 +1074,7 @@ Computes the bitwise OR of its two operands. A structure that contains the results of the bitwise OR operation. - ]]> + ]]> @@ -1113,7 +1113,7 @@ Divides the first parameter by the second. A new structure whose property contains the results of the division operation. - ]]> + ]]> @@ -1152,7 +1152,7 @@ Performs a logical comparison of the two parameters to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1191,7 +1191,7 @@ Performs a bitwise exclusive-OR operation on the supplied parameters. A structure that contains the results of the bitwise XOR operation. - ]]> + ]]> @@ -1475,7 +1475,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1514,7 +1514,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1693,7 +1693,7 @@ Performs a logical comparison on the two SqlInt64 parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1732,7 +1732,7 @@ Performs a logical comparison on the two parameters to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1771,7 +1771,7 @@ Performs a logical comparison on the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1810,7 +1810,7 @@ Computes the remainder after dividing the first parameter by the second. A new structure whose property contains the remainder. - ]]> + ]]> @@ -1849,7 +1849,7 @@ Computes the product of the two parameters. A new structure whose is equal to the product of the two parameters. - ]]> + ]]> @@ -1886,7 +1886,7 @@ Performs a bitwise one's complement operation on its operand. A new structure whose is equal to the ones complement of the parameter. - ]]> + ]]> @@ -1925,7 +1925,7 @@ Subtracts the second parameter from the first. A new structure whose property equals the results of the subtraction operation. - ]]> + ]]> diff --git a/xml/System.Data.SqlTypes/SqlMoney.xml b/xml/System.Data.SqlTypes/SqlMoney.xml index 630b578e89681..f54c47585492e 100644 --- a/xml/System.Data.SqlTypes/SqlMoney.xml +++ b/xml/System.Data.SqlTypes/SqlMoney.xml @@ -905,7 +905,7 @@ Calculates the sum of the two parameters. A new stucture whose contains the sum of the two parameters. - ]]> + ]]> @@ -944,7 +944,7 @@ The division operator divides the first parameter by the second. A new structure whose contains the results of the division. - ]]> + ]]> @@ -983,7 +983,7 @@ Performs a logical comparison of the two parameters to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1267,7 +1267,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1306,7 +1306,7 @@ Performs a logical comparison of the two parameters to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1555,7 +1555,7 @@ Performs a logical comparison of the two parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1594,7 +1594,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1633,7 +1633,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1672,7 +1672,7 @@ The multiplicaion operator calculates the product of the two parameters. A new structure whose contains the product of the multiplication. - ]]> + ]]> @@ -1711,7 +1711,7 @@ The subtraction operator subtracts the second parameter from the first. A new structure that contains the results of the subtraction. - ]]> + ]]> diff --git a/xml/System.Data.SqlTypes/SqlSingle.xml b/xml/System.Data.SqlTypes/SqlSingle.xml index e50bac5bab1e5..bf35f8c7fb62c 100644 --- a/xml/System.Data.SqlTypes/SqlSingle.xml +++ b/xml/System.Data.SqlTypes/SqlSingle.xml @@ -844,7 +844,7 @@ Computes the sum of the two specified structures. A structure that contains the sum of the two specified structures. - .]]> + .]]> @@ -883,7 +883,7 @@ Divides the first structure by the second. A structure that contains the results of the division. - .]]> + .]]> @@ -922,7 +922,7 @@ Performs a logical comparison of the two SqlSingle parameters to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -1101,7 +1101,7 @@ Performs a logical comparison of the two operands to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1140,7 +1140,7 @@ Performs a logical comparison of two structures to determine whether the first is greater than or equl to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1424,7 +1424,7 @@ Performs a logical comparison of the two parameters to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - .]]> + .]]> @@ -1463,7 +1463,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1502,7 +1502,7 @@ Performs a logical comparison of the two parameters to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - .]]> + .]]> @@ -1541,7 +1541,7 @@ Computes the product of the two specified structures. A structure that contains the product of the multiplication. - .]]> + .]]> @@ -1580,7 +1580,7 @@ Subtracts the second structure from the first. A structure that contains the results of the subtraction. - .]]> + .]]> diff --git a/xml/System.Data.SqlTypes/SqlString.xml b/xml/System.Data.SqlTypes/SqlString.xml index e69978ad497e1..f1861d6475008 100644 --- a/xml/System.Data.SqlTypes/SqlString.xml +++ b/xml/System.Data.SqlTypes/SqlString.xml @@ -1387,7 +1387,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Concatenates the two specified structures. A that contains the newly concatenated value representing the contents of the two parameters. - ]]> + ]]> @@ -1426,7 +1426,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether they are equal. A that is if the two instances are equal or if the two instances are not equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -1885,7 +1885,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether the first is greater than the second. A that is if the first instance is greater than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1924,7 +1924,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether the first is greater than or equal to the second. A that is if the first instance is greater than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -1998,7 +1998,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether they are not equal. A that is if the two instances are not equal or if the two instances are equal. If either instance of is null, the of the will be . - ]]> + ]]> @@ -2037,7 +2037,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether the first is less than the second. A that is if the first instance is less than the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> @@ -2076,7 +2076,7 @@ SqlString mySqlString = new SqlString("abc", CultureInfo.CurrentCulture.LCID); Performs a logical comparison of the two operands to determine whether the first is less than or equal to the second. A that is if the first instance is less than or equal to the second instance. Otherwise, . If either instance of is null, the of the will be . - ]]> + ]]> diff --git a/xml/System.Data/ConstraintCollection.xml b/xml/System.Data/ConstraintCollection.xml index 9d3fa8f208643..df504a1b0185f 100644 --- a/xml/System.Data/ConstraintCollection.xml +++ b/xml/System.Data/ConstraintCollection.xml @@ -33,7 +33,7 @@ is accessed through the property. + The is accessed through the property. The can contain both and objects for the . A object makes sure that data in a specific column is always unique to preserve the data integrity. The determines what will occur in related tables when data in the is either updated or deleted. For example, if a row is deleted, the will determine whether the related rows are also deleted (a cascade), or some other course of action. diff --git a/xml/System.Data/DataRow.xml b/xml/System.Data/DataRow.xml index e97f17262ce73..c88fd1d117950 100644 --- a/xml/System.Data/DataRow.xml +++ b/xml/System.Data/DataRow.xml @@ -1212,7 +1212,7 @@ ## Remarks `HasErrors` returns `true` if any object in the row contains an error, or if the property of the is not an empty string. - When validating data, you can set an error on any column in a row. Such a column, when displayed in the control, is marked with a red exclamation point to signal to the user that the column is in error. + When validating data, you can set an error on any column in a row. Such a column, when displayed in the control, is marked with a red exclamation point to signal to the user that the column is in error. Use to set an error on any column. diff --git a/xml/System.Data/DataRowView.xml b/xml/System.Data/DataRowView.xml index 3103b803dcf86..58d8ac9b1f529 100644 --- a/xml/System.Data/DataRowView.xml +++ b/xml/System.Data/DataRowView.xml @@ -87,7 +87,7 @@ ## Remarks Use to add a . - The method is identical to the method of the . After calling , any changes made to the can be rolled back by calling . Call the method before allowing users to change row values. After values have been changed, you retrieve the new values by setting the to `DataRowVersion.Proposed`. Check the values with a business rule, and roll back the changes if needed by calling , or call to accept the changes. + The method is identical to the method of the . After calling , any changes made to the can be rolled back by calling . Call the method before allowing users to change row values. After values have been changed, you retrieve the new values by setting the to `DataRowVersion.Proposed`. Check the values with a business rule, and roll back the changes if needed by calling , or call to accept the changes. diff --git a/xml/System.Data/DataSet.xml b/xml/System.Data/DataSet.xml index a369910fa5032..8f6178f0ddfae 100644 --- a/xml/System.Data/DataSet.xml +++ b/xml/System.Data/DataSet.xml @@ -397,7 +397,7 @@ is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. + If the is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. @@ -3245,7 +3245,7 @@ class Program { ``` - inherits from . + inherits from . > [!NOTE] > If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is thrown when you attempt to read the schema into the with by specifying `XmlReadMode.ReadSchema`. This exception does not occur if you are using .NET Framework version 1.0. @@ -3746,7 +3746,7 @@ class Program { The method is generally invoked before invoking the method which is used to fill the . - The class is abstract. A class that inherits from the `XmlReader` is the class. + The class is abstract. A class that inherits from the `XmlReader` is the class. > [!NOTE] > If the schema for your contains elements of the same name, but different type, in the same namespace, an exception is be thrown when you attempt to read the schema into the with . This exception does not occur if you are using .NET Framework version 1.0. @@ -3754,7 +3754,7 @@ class Program { ## Examples - The following example creates a new and object. The object, created with a file path and file name, is used to create an that is passed as an argument to the method. + The following example creates a new and object. The object, created with a file path and file name, is used to create an that is passed as an argument to the method. [!code-csharp[Classic WebData DataSet.ReadXmlSchema Example#1](~/samples/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema Example/CS/source.cs#1)] [!code-vb[Classic WebData DataSet.ReadXmlSchema Example#1](~/samples/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.ReadXmlSchema Example/VB/source.vb#1)] @@ -3821,11 +3821,11 @@ class Program { to call the method on all objects contained by the . + Invoke the to call the method on all objects contained by the . - objects contained by the can each be set into edit mode by invoking the method. After invoking the method, changes can be rejected by calling the on the to which the objects belong. + objects contained by the can each be set into edit mode by invoking the method. After invoking the method, changes can be rejected by calling the on the to which the objects belong. - When the method is called, any rows still in edit-mode cancel their edits. New rows are removed. Modified and deleted rows return back to their original state (`DataRowState.Unchanged`). + When the method is called, any rows still in edit-mode cancel their edits. New rows are removed. Modified and deleted rows return back to their original state (`DataRowState.Unchanged`). AcceptChanges and RejectChanges only apply to related changes (that is, `Add`, `Remove`, `Delete`, and `Modify`). They are not applicable to schema or structural changes. @@ -4387,7 +4387,7 @@ class Program { ## Examples - The following example creates a object. The object is then used with the method to write an XML document. + The following example creates a object. The object is then used with the method to write an XML document. [!code-csharp[Classic WebData DataSet.WriteXml Example#1](~/samples/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml Example/CS/source.cs#1)] [!code-vb[Classic WebData DataSet.WriteXml Example#1](~/samples/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml Example/VB/source.vb#1)] @@ -4719,7 +4719,7 @@ class Program { ## Examples - The following example creates a object that is used to create a new . The object is used with the method to write an XML document. + The following example creates a object that is used to create a new . The object is used with the method to write an XML document. [!code-csharp[Classic WebData DataSet.WriteXml6 Example#1](~/samples/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml6 Example/CS/source.cs#1)] [!code-vb[Classic WebData DataSet.WriteXml6 Example#1](~/samples/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXml6 Example/VB/source.vb#1)] @@ -4816,12 +4816,12 @@ class Program { To write the data to an XML document, use the method. - Classes the derive from the class include the , , , , and . + Classes the derive from the class include the , , , , and . ## Examples - The following example creates a object to that is used to create a new . The is passed to the method, and the resulting string is printed to the console window. + The following example creates a object to that is used to create a new . The is passed to the method, and the resulting string is printed to the console window. [!code-csharp[Classic WebData DataSet.WriteXmlSchema1 Example#1](~/samples/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema1 Example/CS/source.cs#1)] [!code-vb[Classic WebData DataSet.WriteXmlSchema1 Example#1](~/samples/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema1 Example/VB/source.vb#1)] @@ -4917,12 +4917,12 @@ class Program { To write the data to an XML document, use the method. - One class that inherits from the class is the class. + One class that inherits from the class is the class. ## Examples - The following example creates a new object with the specified path. The object is used to create an object. The method is then invoked with the object to write the schema to the disk. + The following example creates a new object with the specified path. The object is used to create an object. The method is then invoked with the object to write the schema to the disk. [!code-csharp[Classic WebData DataSet.WriteXmlSchema2 Example#1](~/samples/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema2 Example/CS/source.cs#1)] [!code-vb[Classic WebData DataSet.WriteXmlSchema2 Example#1](~/samples/snippets/visualbasic/VS_Snippets_ADO.NET/Classic WebData DataSet.WriteXmlSchema2 Example/VB/source.vb#1)] diff --git a/xml/System.Data/DataTable.xml b/xml/System.Data/DataTable.xml index ac76f6bf6a14f..c748766365202 100644 --- a/xml/System.Data/DataTable.xml +++ b/xml/System.Data/DataTable.xml @@ -72,7 +72,7 @@ There are many events that can be used to determine when changes are made to a table. These include , , , and . For more information about the events that can be used with a , see [Handling DataTable Events](~/docs/framework/data/adonet/dataset-datatable-dataview/handling-datatable-events.md). - When an instance of is created, some of the read/write properties are set to initial values. For a list of these values, see the constructor topic. + When an instance of is created, some of the read/write properties are set to initial values. For a list of these values, see the constructor topic. > [!NOTE] > The and objects inherit from , and support the interface for .NET Framework remoting. These are the only ADO.NET objects that you can use for .NET Framework remoting. @@ -285,7 +285,7 @@ ## Remarks When is called, any object still in edit mode successfully ends its edits. The also changes: all `Added` and `Modified` rows become `Unchanged`, and `Deleted` rows are removed. - The method is generally called on a after you attempt to update the using the method. + The method is generally called on a after you attempt to update the using the method. @@ -490,7 +490,7 @@ ## Remarks All rows in all tables are removed. An exception is generated if the table has any enforced child relations that would cause child rows to be orphaned. - If the is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. When you use to create new rows, the rows must be processed before you call . + If the is bound to an , calling or raises the . To avoid this situation, traverse each table, removing each row one at a time. When you use to create new rows, the rows must be processed before you call . @@ -1235,7 +1235,7 @@ class Program { `colDate > 1/1/99 AND colDate < 17/1/99` - For rules on creating expressions for both parameters, see the property. + For rules on creating expressions for both parameters, see the property. @@ -2194,7 +2194,7 @@ class Program { method consumes the first result set from the loaded , and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. + The method consumes the first result set from the loaded , and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. The method must take into account three specific issues when loading the data from an instance: schema, data, and event operations. When working with the schema, the method may encounter conditions as described in the following table. The schema operations take place for all imported result sets, even those containing no data. @@ -2207,7 +2207,7 @@ class Program { Before considering the behavior of the `Load` method in terms of data operations, consider that each row within a maintains both the current value and the original value for each column. These values may be equivalent, or may be different if the data in the row has been changed since filling the `DataTable`. For more information, see [Row States and Row Versions](~/docs/framework/data/adonet/dataset-datatable-dataview/row-states-and-row-versions.md). - This version of the `Load` method attempts to preserve the current values in each row, leaving the original value intact. (If you want finer control over the behavior of incoming data, see .) If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row. + This version of the `Load` method attempts to preserve the current values in each row, leaving the original value intact. (If you want finer control over the behavior of incoming data, see .) If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row. In terms of event operations, the event occurs before each row is changed, and the event occurs after each row has been changed. In each case, the property of the instance passed to the event handler contains information about the particular action associated with the event. This action value depends on the state of the row before the load operation. In each case, both events occur, and the action is the same for each. The action may be applied to either the current or original version of each row, or both, depending on the current row state. @@ -2356,7 +2356,7 @@ Not present)|Current = \

Original = \
, and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. + The `Load` method consumes the first result set from the loaded , and after successful completion, sets the reader's position to the next result set, if any. When converting data, the `Load` method uses the same conversion rules as the method. The `Load` method must take into account three specific issues when loading the data from an instance: schema, data, and event operations. When working with the schema, the `Load` method may encounter conditions as described in the following table. The schema operations take place for all imported result sets, even those containing no data. @@ -3570,7 +3570,7 @@ Not present)|Current = \

Original = \
and its descendents are loaded with the data from the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. + The current and its descendents are loaded with the data from the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. @@ -3630,7 +3630,7 @@ Not present)|Current = \

Original = \
and its descendents are loaded with the data from the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. + The current and its descendents are loaded with the data from the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. @@ -3690,7 +3690,7 @@ Not present)|Current = \

Original = \
and its descendents are loaded with the data from the file named in the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. + The current and its descendents are loaded with the data from the file named in the supplied . The behavior of this method is identical to that of the method, except that in this case, data is loaded only for the current table and its descendants. The method provides a way to read either data only, or both data and schema into a from an XML document, whereas the method reads only the schema. diff --git a/xml/System.Data/EntityKey.xml b/xml/System.Data/EntityKey.xml index 293f041e42396..55c0fc029b5d8 100644 --- a/xml/System.Data/EntityKey.xml +++ b/xml/System.Data/EntityKey.xml @@ -544,7 +544,7 @@ In addition, temporary keys have no or key values, but permanent keys do. - The equivalent method for this operator is + The equivalent method for this operator is @@ -582,7 +582,7 @@ In addition, temporary keys have no or key values, but regular keys do. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> diff --git a/xml/System.Data/IDataReader.xml b/xml/System.Data/IDataReader.xml index 7c468e4461c99..f52c4929e7956 100644 --- a/xml/System.Data/IDataReader.xml +++ b/xml/System.Data/IDataReader.xml @@ -159,10 +159,10 @@ |Data Provider|Member| |-------------------|------------| -|.NET Data Provider for ODBC|.| -|.NET Data Provider for OLE DB|.| -|.NET Data Provider for Oracle|.| -|.NET Data Provider for SQL Server|.| +|.NET Data Provider for ODBC|.| +|.NET Data Provider for OLE DB|.| +|.NET Data Provider for Oracle|.| +|.NET Data Provider for SQL Server|.| ]]> diff --git a/xml/System.Data/InvalidConstraintException.xml b/xml/System.Data/InvalidConstraintException.xml index f415dcb1fc6ea..281e0d214b7cb 100644 --- a/xml/System.Data/InvalidConstraintException.xml +++ b/xml/System.Data/InvalidConstraintException.xml @@ -27,11 +27,11 @@ ## Remarks The is thrown when incorrectly invoking the following methods while trying to create or access a relation. -- +- -- +- -- +- If you call , the may be thrown if a relation cannot be created based on the values supplied in the parameters. If you call , the may be thrown if a is enforced on the . If you call , the may be thrown if the columns have different data types or the tables do not belong to the same . diff --git a/xml/System.Data/MissingPrimaryKeyException.xml b/xml/System.Data/MissingPrimaryKeyException.xml index 14c6eb2b3166f..662a980d75237 100644 --- a/xml/System.Data/MissingPrimaryKeyException.xml +++ b/xml/System.Data/MissingPrimaryKeyException.xml @@ -27,9 +27,9 @@ ## Remarks The is thrown when invoking the following methods to access a row in a table that has no primary key. -- +- -- +- ]]> diff --git a/xml/System.Data/NoNullAllowedException.xml b/xml/System.Data/NoNullAllowedException.xml index a528ed7ee2f07..cde22e7268620 100644 --- a/xml/System.Data/NoNullAllowedException.xml +++ b/xml/System.Data/NoNullAllowedException.xml @@ -27,13 +27,13 @@ ## Remarks The is thrown when invoking the following methods or properties when you try to insert a null value into a column where is set to `false`. -- +- -- +- -- +- -- +- ]]> diff --git a/xml/System.Data/ReadOnlyException.xml b/xml/System.Data/ReadOnlyException.xml index e06fd07638c6d..17b84605da248 100644 --- a/xml/System.Data/ReadOnlyException.xml +++ b/xml/System.Data/ReadOnlyException.xml @@ -27,9 +27,9 @@ ## Remarks The is thrown when you invoke the following methods or properties when you are trying to change the value of a read-only column. -- +- -- +- ]]> diff --git a/xml/System.Data/RowNotInTableException.xml b/xml/System.Data/RowNotInTableException.xml index bdc1cb5ec4d8b..6bf6bee931625 100644 --- a/xml/System.Data/RowNotInTableException.xml +++ b/xml/System.Data/RowNotInTableException.xml @@ -25,19 +25,19 @@ is thrown when invoking the following methods on a row that has been deleted with either the or the method. + The is thrown when invoking the following methods on a row that has been deleted with either the or the method. -- +- -- +- -- +- -- +- -- +- -- +- diff --git a/xml/System.Diagnostics.Contracts/Contract.xml b/xml/System.Diagnostics.Contracts/Contract.xml index 13ab1a0359b04..56e4014cfd3a0 100644 --- a/xml/System.Diagnostics.Contracts/Contract.xml +++ b/xml/System.Diagnostics.Contracts/Contract.xml @@ -31,7 +31,7 @@ For tools and detailed instructions for using code contracts, see [Code Contracts](http://go.microsoft.com/fwlink/?LinkId=152461) on the MSDN DevLabs Web site. > [!IMPORTANT] -> You must use a binary rewriter to insert run-time enforcement of contracts. Otherwise, contracts such as the method can only be tested statically and will not throw exceptions during run time if a contract is violated. You can download the binary rewriter CCRewrite from [Code Contracts](http://go.microsoft.com/fwlink/?LinkId=152461) on the MSDN DevLabs Web site. CCRewrite comes with a Visual Studio add-in that enables you to activate run-time contract enforcement from the project **Properties** page. The binary rewriter and the Visual Studio add-in do not ship with [!INCLUDE[vs_dev10_long](~/includes/vs-dev10-long-md.md)] or the Windows SDK. +> You must use a binary rewriter to insert run-time enforcement of contracts. Otherwise, contracts such as the method can only be tested statically and will not throw exceptions during run time if a contract is violated. You can download the binary rewriter CCRewrite from [Code Contracts](http://go.microsoft.com/fwlink/?LinkId=152461) on the MSDN DevLabs Web site. CCRewrite comes with a Visual Studio add-in that enables you to activate run-time contract enforcement from the project **Properties** page. The binary rewriter and the Visual Studio add-in do not ship with [!INCLUDE[vs_dev10_long](~/includes/vs-dev10-long-md.md)] or the Windows SDK. ]]> @@ -275,7 +275,7 @@ object that is passed to the event handler. This event notifies a managed application environment such as an interactive interpreter or a Web browser host that a contract has failed. Before doing so, it will raise an event that an application can handle as it sees fit. For example, if code is being run in a testing framework, you can log a test failure and then end the test. + The event information for this event is supplied by the object that is passed to the event handler. This event notifies a managed application environment such as an interactive interpreter or a Web browser host that a contract has failed. Before doing so, it will raise an event that an application can handle as it sees fit. For example, if code is being run in a testing framework, you can log a test failure and then end the test. The default implementation of the method in the .NET Framework class library is to call each handler that is registered with the event. Exceptions thrown by handlers are ignored, but each handler can indicate whether the failure is handled by calling the method for the event arguments. If any handler sets the failure as handled, the method returns `null` and no further action is taken. Alternatively, handlers can call the method to instruct the code to unwind. In that case, an exception is thrown after all handlers have executed. @@ -994,7 +994,7 @@ - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. -- Use this method instead of the method when backward compatibility does not force you to throw a particular exception. +- Use this method instead of the method when backward compatibility does not force you to throw a particular exception. ]]> @@ -1047,7 +1047,7 @@ - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. -- Use this method instead of the method when backward compatibility does not force you to throw a particular exception. +- Use this method instead of the method when backward compatibility does not force you to throw a particular exception. ]]> @@ -1106,7 +1106,7 @@ - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. -- Use this method instead of the method when you want to throw an exception if the precondition fails. +- Use this method instead of the method when you want to throw an exception if the precondition fails. ]]> @@ -1167,7 +1167,7 @@ - This contract is exposed to clients; therefore, it must only reference members that are at least as visible as the enclosing method. -- Use this method instead of the method when you want to throw an exception if the precondition fails. +- Use this method instead of the method when you want to throw an exception if the precondition fails. ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute.xml b/xml/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute.xml index 186bc63a0e253..938b9fcb373b3 100644 --- a/xml/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute.xml +++ b/xml/System.Diagnostics.Contracts/ContractArgumentValidatorAttribute.xml @@ -39,12 +39,12 @@ [!code-csharp[System.Diagnostics.Contracts.ContractArgumentValidatorAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.diagnostics.contracts.contractargumentvalidatorattribute/cs/ifthenthrow1.cs#1)] [!code-vb[System.Diagnostics.Contracts.ContractArgumentValidatorAttribute#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.diagnostics.contracts.contractargumentvalidatorattribute/vb/ifthenthrow1.vb#1)] - In this example, `Execute` has an elective precondition specifying that the parameter value should not be `null`. To enable the contract tools to recognize that the call to `ValidationHelper.NotNull` represents a contract, you can mark the called method with the attribute. The method call should be used to enable the tools to extract the proper specifications for document generation and static checking, as follows. + In this example, `Execute` has an elective precondition specifying that the parameter value should not be `null`. To enable the contract tools to recognize that the call to `ValidationHelper.NotNull` represents a contract, you can mark the called method with the attribute. The method call should be used to enable the tools to extract the proper specifications for document generation and static checking, as follows. [!code-csharp[System.Diagnostics.Contracts.ContractArgumentValidatorAttribute#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.diagnostics.contracts.contractargumentvalidatorattribute/cs/ifthenthrow2.cs#2)] [!code-vb[System.Diagnostics.Contracts.ContractArgumentValidatorAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.diagnostics.contracts.contractargumentvalidatorattribute/vb/ifthenthrow2.vb#2)] - In addition to `if-then-throw` statements, the contract section of contract validator methods may contain calls to other contract validator methods. However, no other contracts (such as , or ) are allowed. Code that follows the call is ignored by all contract tools. + In addition to `if-then-throw` statements, the contract section of contract validator methods may contain calls to other contract validator methods. However, no other contracts (such as , or ) are allowed. Code that follows the call is ignored by all contract tools. The following example shows a range argument validator written in terms of an existing `NotNull` validator method. @@ -60,7 +60,7 @@ Contract.Requires(position < data.Length); ``` - In standard methods, calls to contract validator methods can be freely mixed with other contracts such as or . + In standard methods, calls to contract validator methods can be freely mixed with other contracts such as or . ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml b/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml index be2b88bf66564..cf3bd74b0e202 100644 --- a/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml +++ b/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml @@ -26,7 +26,7 @@ object is passed to the event when a contract fails. The event enables a managed application environment such as an interactive interpreter, a Web browser host, a test harness, or a logging infrastructure to be notified of contract failures. The event requires full trust. + A object is passed to the event when a contract fails. The event enables a managed application environment such as an interactive interpreter, a Web browser host, a test harness, or a logging infrastructure to be notified of contract failures. The event requires full trust. ]]> @@ -157,7 +157,7 @@ event has not been handled, the debugger is notified. If no debugger is attached, an **Assert** dialog box is displayed. + If the event has not been handled, the debugger is notified. If no debugger is attached, an **Assert** dialog box is displayed. ]]> @@ -253,7 +253,7 @@ method provides a way for the runtime analysis checker to indicate that a contract exception has been handled. See the property for more information. + The method provides a way for the runtime analysis checker to indicate that a contract exception has been handled. See the property for more information. ]]> @@ -294,7 +294,7 @@ method provides a way to indicate that the escalation policy for the code contract should be applied. See the property for more information. + The method provides a way to indicate that the escalation policy for the code contract should be applied. See the property for more information. ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractFailureKind.xml b/xml/System.Diagnostics.Contracts/ContractFailureKind.xml index 31ee7681367bc..2592e37098dd8 100644 --- a/xml/System.Diagnostics.Contracts/ContractFailureKind.xml +++ b/xml/System.Diagnostics.Contracts/ContractFailureKind.xml @@ -25,7 +25,7 @@ enumeration is used by the class. + The enumeration is used by the class. ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractInvariantMethodAttribute.xml b/xml/System.Diagnostics.Contracts/ContractInvariantMethodAttribute.xml index 70367f261d5c2..7d6a8b01d053e 100644 --- a/xml/System.Diagnostics.Contracts/ContractInvariantMethodAttribute.xml +++ b/xml/System.Diagnostics.Contracts/ContractInvariantMethodAttribute.xml @@ -34,7 +34,7 @@ method. A type can have more than one contract invariant method, which can be public or private. + The invariant method can have any name, but it must return `void` and take no parameters. A suggested name for the method is `ObjectInvariant`. The body of the invariant method must consist solely of one or more calls to the method. A type can have more than one contract invariant method, which can be public or private. ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractRuntimeIgnoredAttribute.xml b/xml/System.Diagnostics.Contracts/ContractRuntimeIgnoredAttribute.xml index aee7685a8b720..905942bea6d81 100644 --- a/xml/System.Diagnostics.Contracts/ContractRuntimeIgnoredAttribute.xml +++ b/xml/System.Diagnostics.Contracts/ContractRuntimeIgnoredAttribute.xml @@ -34,7 +34,7 @@ methods, but they have no run-time behavior. + Methods and properties that are marked with this attribute can be used within calls to methods, but they have no run-time behavior. ]]> diff --git a/xml/System.Diagnostics.Contracts/PureAttribute.xml b/xml/System.Diagnostics.Contracts/PureAttribute.xml index 802dec29409b1..28e553cd52349 100644 --- a/xml/System.Diagnostics.Contracts/PureAttribute.xml +++ b/xml/System.Diagnostics.Contracts/PureAttribute.xml @@ -34,7 +34,7 @@ methods. Pure methods do not make any visible state changes. This attribute is not enforced by the current analysis tools; you should use this attribute only if you are sure that the methods are pure. + Methods and types that are marked with this attribute can be used in calls to methods. Pure methods do not make any visible state changes. This attribute is not enforced by the current analysis tools; you should use this attribute only if you are sure that the methods are pure. ]]> diff --git a/xml/System.Diagnostics.Eventing/EventDescriptor.xml b/xml/System.Diagnostics.Eventing/EventDescriptor.xml index 0390c192969c7..22d730ef6cb9a 100644 --- a/xml/System.Diagnostics.Eventing/EventDescriptor.xml +++ b/xml/System.Diagnostics.Eventing/EventDescriptor.xml @@ -31,7 +31,7 @@ unchecked } ``` - You use the descriptor when calling the or method. + You use the descriptor when calling the or method. For more information on writing the manifest and using the message compiler, see [Developing Event Publishers](https://msdn.microsoft.com/en-us/library/windows/desktop/aa964766\(v=vs.85\).aspx) diff --git a/xml/System.Diagnostics.Eventing/EventProvider+WriteEventErrorCode.xml b/xml/System.Diagnostics.Eventing/EventProvider+WriteEventErrorCode.xml index 3edebc4d29a81..17a0e2e6991df 100644 --- a/xml/System.Diagnostics.Eventing/EventProvider+WriteEventErrorCode.xml +++ b/xml/System.Diagnostics.Eventing/EventProvider+WriteEventErrorCode.xml @@ -15,9 +15,9 @@ method. + To get an instance of this enumeration, call the method. - The , , and methods set this value if they fail to write the event. + The , , and methods set this value if they fail to write the event. ]]> diff --git a/xml/System.Diagnostics.Eventing/EventProvider.xml b/xml/System.Diagnostics.Eventing/EventProvider.xml index 420a3a0f40bbc..385a344e47ab3 100644 --- a/xml/System.Diagnostics.Eventing/EventProvider.xml +++ b/xml/System.Diagnostics.Eventing/EventProvider.xml @@ -389,7 +389,7 @@ ## Remarks If you call the method to specify an activity identifier for the event, this method retrieves the identifier from the thread context and includes it with the event. - If the object type is not supported, the method writes the value of the object's method in the payload. For a list of supported object types, see the Remarks for the class. + If the object type is not supported, the method writes the value of the object's method in the payload. For a list of supported object types, see the Remarks for the class. diff --git a/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml b/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml index e880b325bbe17..91801b3ad7e43 100644 --- a/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml +++ b/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml @@ -18,11 +18,11 @@ ## Remarks All event data (trace or debug) from the source event is written to the ETW subsystem as a string. The data elements are delimited using a comma. To specify a different delimiter, use the property. - Adding the listener to registers the provider with the ETW subsystem. You must create an ETW trace session using the Logman.exe executable program (or something similar) to write the events to a log file. + Adding the listener to registers the provider with the ETW subsystem. You must create an ETW trace session using the Logman.exe executable program (or something similar) to write the events to a log file. You do not need a manifest to consume events from the listener because the event data is a single string. - When you call the methods to write events, you pass a enumeration value. The enumeration contains both level and keyword values. When you enable a trace listener provider from an ETW session, the level value that you specify can be the value associated with one of the following enumeration values: + When you call the methods to write events, you pass a enumeration value. The enumeration contains both level and keyword values. When you enable a trace listener provider from an ETW session, the level value that you specify can be the value associated with one of the following enumeration values: - Critical (value is 1) @@ -34,7 +34,7 @@ - Warning (value is 4) - The keyword value that you specify for the session can be the value associated with one of the following enumeration values: + The keyword value that you specify for the session can be the value associated with one of the following enumeration values: - Resume (value is 2,048) @@ -186,7 +186,7 @@ private static Guid providerId = new Guid("{B3F0C8FC-E8A8-4868-8901-1465E8A2F41B You do not need a manifest to consume events from the listener because the event data is a single string. - The delimiter applies to event data written using the method. + The delimiter applies to event data written using the method. ]]> diff --git a/xml/System.Diagnostics.PerformanceData/CounterData.xml b/xml/System.Diagnostics.PerformanceData/CounterData.xml index 7c54a104e1a78..fb51fd54e102f 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterData.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterData.xml @@ -16,7 +16,7 @@ property returns an instance of this class. + The property returns an instance of this class. This class provides thread-safe methods for reading and writing counter data. diff --git a/xml/System.Diagnostics.PerformanceData/CounterSetInstance.xml b/xml/System.Diagnostics.PerformanceData/CounterSetInstance.xml index 605a5de18c40e..318a9e1abe5be 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterSetInstance.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterSetInstance.xml @@ -20,7 +20,7 @@ method returns an instance of this class. + The method returns an instance of this class. diff --git a/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml b/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml index f23e4f73d4122..568d774f3efb0 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml @@ -20,7 +20,7 @@ property returns an instance of this class. + The property returns an instance of this class. ]]> @@ -126,7 +126,7 @@ ## Remarks Implemented as an indexer in C#. - To use this overload, you must use the method to add the counter to the counter set. + To use this overload, you must use the method to add the counter to the counter set. ]]> diff --git a/xml/System.Diagnostics.SymbolStore/SymbolToken.xml b/xml/System.Diagnostics.SymbolStore/SymbolToken.xml index 5a827c4a0a826..dafae91e607fb 100644 --- a/xml/System.Diagnostics.SymbolStore/SymbolToken.xml +++ b/xml/System.Diagnostics.SymbolStore/SymbolToken.xml @@ -208,7 +208,7 @@ if and are equal; otherwise, . - .]]> + .]]> @@ -244,7 +244,7 @@ if and are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Diagnostics.Tracing/EventSource.xml b/xml/System.Diagnostics.Tracing/EventSource.xml index 03b28967cbd47..a07e1aafc350b 100644 --- a/xml/System.Diagnostics.Tracing/EventSource.xml +++ b/xml/System.Diagnostics.Tracing/EventSource.xml @@ -33,7 +33,7 @@ methods are called to log the events. + This class is intended to be inherited by a user class that provides specific events to be used for ETW. The methods are called to log the events. > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. @@ -366,7 +366,7 @@ constructors do not throw exceptions. Instead, any exception that is thrown is assigned to the property and logged by the method. + constructors do not throw exceptions. Instead, any exception that is thrown is assigned to the property and logged by the method. ]]> @@ -1473,7 +1473,7 @@ overload, which is considerably slower than the other overloads. See the overload page for details. + The `WriteEvent` method provides overloads with combinations of string and integer arguments. If none of these combinations match the parameters for the call, the compiler uses the overload, which is considerably slower than the other overloads. See the overload page for details. In all cases, the `eventid` parameter should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. @@ -1770,7 +1770,7 @@ public void Info1(string arg1) 4. It calls the function, which then determines the type of each argument so it can be serialized for ETW. - The high overhead for this overload is not significant when tracing low-volume events, because the method is used only when the provider is enabled. However, for high-volume events, the performance overhead can be significant. You can avoid using for high-volume payloads by creating a new, faster overload with the method. + The high overhead for this overload is not significant when tracing low-volume events, because the method is used only when the provider is enabled. However, for high-volume events, the performance overhead can be significant. You can avoid using for high-volume payloads by creating a new, faster overload with the method. `eventid` should be greater than 0 or less than 65535 or errors can occur in the operation. If errors do occur, you can get more information about the source of the error by checking the output stream of the debugger, if you have a debugger attached to the process firing events. You can also look for errors reported in the ETW event stream, if you have an ETW listener on the event source where the error occurs. @@ -2642,7 +2642,7 @@ class AnotherEventSource : EventSource { 1. Specify the first parameter as a named `relatedActivityId`. -2. Specify either or as the property. +2. Specify either or as the property. 3. Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. @@ -2714,7 +2714,7 @@ class AnotherEventSource : EventSource { 1. Specify the first parameter as a named `relatedActivityId`. -2. Specify either or as the property. +2. Specify either or as the property. 3. Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. diff --git a/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml b/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml index d954ee363ae66..0e709ec9e4e91 100644 --- a/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml +++ b/xml/System.Diagnostics.Tracing/EventWrittenEventArgs.xml @@ -63,7 +63,7 @@ ## Remarks Retrieving the value of the property accesses thread local storage. This has the following implications: -- The field is valid only for the duration of the callback. +- The field is valid only for the duration of the callback. - If the activity ID is changed during the callback, the activity ID returned by the property is invalid. diff --git a/xml/System.Diagnostics/BooleanSwitch.xml b/xml/System.Diagnostics/BooleanSwitch.xml index d2763a3b15760..be92787212b29 100644 --- a/xml/System.Diagnostics/BooleanSwitch.xml +++ b/xml/System.Diagnostics/BooleanSwitch.xml @@ -218,7 +218,7 @@ By default, this field is set to `false` (disabled). To enable the switch, assign this field the value of `true`. To disable the switch, assign the value to `false`. The value of this property is determined by the value of the base class property . > [!NOTE] -> This method uses the flag to prevent being called from untrusted code; only the immediate caller is required to have permission. If your code can be called from partially trusted code, do not pass the user input to class methods without validation. +> This method uses the flag to prevent being called from untrusted code; only the immediate caller is required to have permission. If your code can be called from partially trusted code, do not pass the user input to class methods without validation. diff --git a/xml/System.Diagnostics/ConsoleTraceListener.xml b/xml/System.Diagnostics/ConsoleTraceListener.xml index 5c2d64c9d34bb..fe677bca19f20 100644 --- a/xml/System.Diagnostics/ConsoleTraceListener.xml +++ b/xml/System.Diagnostics/ConsoleTraceListener.xml @@ -16,22 +16,22 @@ class to write trace and debugging messages to the console. You can initialize a object to write trace messages to the stream or to the stream. + Use the class to write trace and debugging messages to the console. You can initialize a object to write trace messages to the stream or to the stream. > [!IMPORTANT] > interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - When trace and debugging output is enabled, the messages are written to the specified stream, which is similar to the way messages are written with the or methods. In a console application, the output and error streams write messages to the existing console window, or you can redirect the streams to write to a instance. + When trace and debugging output is enabled, the messages are written to the specified stream, which is similar to the way messages are written with the or methods. In a console application, the output and error streams write messages to the existing console window, or you can redirect the streams to write to a instance. > [!NOTE] > If the console does not exist, as in a Windows-based application, messages written to the console are not displayed. - Add a object to the appropriate collection if you want messages written through , , or to be written to the console. In addition, you can write messages directly to the console using the or methods. + Add a object to the appropriate collection if you want messages written through , , or to be written to the console. In addition, you can write messages directly to the console using the or methods. > [!NOTE] > The and classes share the same collection, accessed through their respective `Listeners` properties. If you add a object to the collection using one of these classes, the other class automatically uses the same listener. - Most compilers enable trace and debug output through conditional compilation flags. If you do not enable tracing or debugging, the messages written through the and classes are effectively ignored. The syntax to enable trace and debug output is compiler specific; if you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. + Most compilers enable trace and debug output through conditional compilation flags. If you do not enable tracing or debugging, the messages written through the and classes are effectively ignored. The syntax to enable trace and debug output is compiler specific; if you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. - To enable debugging in C#, add the **/d:DEBUG**flag to the compiler command line when you compile your code, or you can add **#define DEBUG** to the top of your file. In Visual Basic, add the **/d:DEBUG=True** flag to the compiler command line. @@ -91,7 +91,7 @@ object to write messages to the stream. Its property is initialized to an empty string (""). + This constructor initializes a object to write messages to the stream. Its property is initialized to an empty string (""). @@ -125,7 +125,7 @@ object to write messages to either the or the stream. Its property is initialized to an empty string (""). + This constructor initializes a object to write messages to either the or the stream. Its property is initialized to an empty string (""). @@ -158,7 +158,7 @@ instance (either the stream or the stream) is closed. + The stream specified for this instance (either the stream or the stream) is closed. ]]> diff --git a/xml/System.Diagnostics/CounterSample.xml b/xml/System.Diagnostics/CounterSample.xml index aba7b737b8efc..f08aea96528db 100644 --- a/xml/System.Diagnostics/CounterSample.xml +++ b/xml/System.Diagnostics/CounterSample.xml @@ -445,7 +445,7 @@ ## Remarks Two structures are equal if they have identical property values. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -481,7 +481,7 @@ ## Remarks Two structures are not equal if any of their property values are different. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> diff --git a/xml/System.Diagnostics/DataReceivedEventArgs.xml b/xml/System.Diagnostics/DataReceivedEventArgs.xml index 9bcc21a24ec0b..fa2239576187a 100644 --- a/xml/System.Diagnostics/DataReceivedEventArgs.xml +++ b/xml/System.Diagnostics/DataReceivedEventArgs.xml @@ -76,7 +76,7 @@ A line is defined as a sequence of characters followed by a line feed ("\n") or a carriage return immediately followed by a line feed ("\r\n"). The line characters are encoded using the default system ANSI code page. The property does not include the terminating carriage return or line feed. - When the redirected stream is closed, a null line is sent to the event handler. Ensure your event handler checks the property appropriately before accessing it. For example, you can use the static method to validate the property in your event handler. + When the redirected stream is closed, a null line is sent to the event handler. Ensure your event handler checks the property appropriately before accessing it. For example, you can use the static method to validate the property in your event handler. diff --git a/xml/System.Diagnostics/DataReceivedEventHandler.xml b/xml/System.Diagnostics/DataReceivedEventHandler.xml index 337eff3c622ce..af3650391b8d9 100644 --- a/xml/System.Diagnostics/DataReceivedEventHandler.xml +++ b/xml/System.Diagnostics/DataReceivedEventHandler.xml @@ -36,7 +36,7 @@ ## Remarks When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events](http://msdn.microsoft.com/library/b6f65241-e0ad-4590-a99f-200ce741bb1f). - To asynchronously collect the redirected or stream output of a process, add your event handler to the or event. These events are raised each time the process writes a line to the corresponding redirected stream. When the redirected stream is closed, a null line is sent to the event handler. Ensure that your event handler checks for this condition before accessing the property. For example, you can use the `static` method to validate the property in your event handler. + To asynchronously collect the redirected or stream output of a process, add your event handler to the or event. These events are raised each time the process writes a line to the corresponding redirected stream. When the redirected stream is closed, a null line is sent to the event handler. Ensure that your event handler checks for this condition before accessing the property. For example, you can use the `static` method to validate the property in your event handler. diff --git a/xml/System.Diagnostics/Debug.xml b/xml/System.Diagnostics/Debug.xml index 43e4ff5a74115..476d262d3e2c4 100644 --- a/xml/System.Diagnostics/Debug.xml +++ b/xml/System.Diagnostics/Debug.xml @@ -109,7 +109,7 @@ method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). > [!IMPORTANT] > The `Assert` methods are not available for [!INCLUDE[win8_appstore_long](~/includes/win8-appstore-long-md.md)] apps. @@ -124,7 +124,7 @@ > [!NOTE] > The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](~/docs/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace.md), the [<remove>](~/docs/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace.md), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: + You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ``` @@ -187,7 +187,7 @@ method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. @@ -196,7 +196,7 @@ > [!NOTE] > The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](~/docs/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace.md), the [<remove>](~/docs/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace.md), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: + You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ``` @@ -260,7 +260,7 @@ method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message and detailed message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. @@ -269,7 +269,7 @@ > [!NOTE] > The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](~/docs/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace.md), the [<remove>](~/docs/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace.md), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: + You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ``` @@ -343,16 +343,16 @@ ## Remarks This method uses the of the .NET Framework to convert the value of an object to its text representation and embed that representation in a string. The resulting string is sent to the collection. - By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). + By default, the method works only in debug builds. Use the method if you want to do assertions in release builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). - Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, The method is called and the `detailMessageFormat` string and `args` array are passed in as parameters. then sends the specified text message and the formatted text message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. + Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, The method is called and the `detailMessageFormat` string and `args` array are passed in as parameters. then sends the specified text message and the formatted text message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] > The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](~/docs/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace.md), the [<remove>](~/docs/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace.md), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: + You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ``` @@ -1503,7 +1503,7 @@ Debug.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. @@ -1766,11 +1766,11 @@ Debug.WriteIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range"); ## Remarks This method uses the of the .NET Framework to convert the value of an object to its text representation and embed that representation in a string. - The keyword in the syntax for this method implies that the object array can be a single value. The exception to this is the object. Explicit overloads take precedence, so an `arg` value of a single string will default to the overload. + The keyword in the syntax for this method implies that the object array can be a single value. The exception to this is the object. Explicit overloads take precedence, so an `arg` value of a single string will default to the overload. By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. ]]> @@ -1956,7 +1956,7 @@ Debug.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") ## Remarks By default, the output is written to an instance of . - This method calls the method of the trace listener. + This method calls the method of the trace listener. @@ -2117,7 +2117,7 @@ Debug.WriteLineIf(mySwitch.TraceError, "aNumber = " + aNumber + " out of range") The `category` parameter can be used to group output messages. - This method calls the method of the trace listener. + This method calls the method of the trace listener. diff --git a/xml/System.Diagnostics/DefaultTraceListener.xml b/xml/System.Diagnostics/DefaultTraceListener.xml index da3a595676bed..083b81d6ee496 100644 --- a/xml/System.Diagnostics/DefaultTraceListener.xml +++ b/xml/System.Diagnostics/DefaultTraceListener.xml @@ -26,9 +26,9 @@ and collections. Explicitly adding a second causes duplicate messages in the debugger output window and duplicate message boxes for asserts. + An instance of this class is automatically added to the and collections. Explicitly adding a second causes duplicate messages in the debugger output window and duplicate message boxes for asserts. - By default, the and methods emit the message to the Win32 `OutputDebugString` function and to the method. For information about the `OutputDebugString` function, see the Platform SDK or MSDN. + By default, the and methods emit the message to the Win32 `OutputDebugString` function and to the method. For information about the `OutputDebugString` function, see the Platform SDK or MSDN. The method, by default, displays a message box when the application is running in a user interface mode; it also emits the message using . @@ -59,11 +59,11 @@ ## Examples - The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a to trace results and log errors. It creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. + The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a to trace results and log errors. It creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. If an error is detected while processing the input parameter, or if the `CalcBinomial` function throws an exception, the method logs and displays an error message. If the property is `false`, the error message is also written to the console. When the result is calculated successfully, the and methods write the results to the log file. - The , , and methods cause trace information to be written only to the . To write trace information to all listeners in the collection, use the , , and methods of the class. + The , , and methods cause trace information to be written only to the . To write trace information to all listeners in the collection, use the , , and methods of the class. [!code-csharp[System.Diagnostics.DefaultTraceListener#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.DefaultTraceListener/CS/binomial.cs#11)] [!code-vb[System.Diagnostics.DefaultTraceListener#11](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.DefaultTraceListener/VB/binomial.vb#11)] @@ -99,7 +99,7 @@ provided by the application from the collection and then creates a new and adds it to the collection. + The following code example removes the provided by the application from the collection and then creates a new and adds it to the collection. [!code-csharp[System.Diagnostics.DefaultTraceListener#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.DefaultTraceListener/CS/binomial.cs#3)] [!code-vb[System.Diagnostics.DefaultTraceListener#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.DefaultTraceListener/VB/binomial.vb#3)] @@ -278,7 +278,7 @@ , adds it to the collection, and sets the property to the log file specified in the command-line arguments. + The following code example creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. [!code-csharp[System.Diagnostics.DefaultTraceListener#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.DefaultTraceListener/CS/binomial.cs#4)] [!code-vb[System.Diagnostics.DefaultTraceListener#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.DefaultTraceListener/VB/binomial.vb#4)] diff --git a/xml/System.Diagnostics/DelimitedListTraceListener.xml b/xml/System.Diagnostics/DelimitedListTraceListener.xml index 33a5b49324f8e..d5f48b5521804 100644 --- a/xml/System.Diagnostics/DelimitedListTraceListener.xml +++ b/xml/System.Diagnostics/DelimitedListTraceListener.xml @@ -34,7 +34,7 @@ You can enable or disable a through the application configuration file and then use the configured in your application. Alternately, you can create a in your code. > [!NOTE] -> The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. +> The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. To configure a , edit the configuration file that corresponds to the name of your application. In this file, you can add a listener, set the properties for a listener, or remove a listener. The configuration file should be formatted as shown in the following example: @@ -617,7 +617,7 @@ method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. + The values of the `source`, `eventType`, and `id` parameters are written as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. > [!IMPORTANT] > The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. diff --git a/xml/System.Diagnostics/EventLogEntry.xml b/xml/System.Diagnostics/EventLogEntry.xml index b2ee39e64176c..79f477a9ea941 100644 --- a/xml/System.Diagnostics/EventLogEntry.xml +++ b/xml/System.Diagnostics/EventLogEntry.xml @@ -28,7 +28,7 @@ directly when working with the class. The member of the class contains a collection of instances, which you iterate over when reading by using the class index member. + You usually will not create instances of directly when working with the class. The member of the class contains a collection of instances, which you iterate over when reading by using the class index member. > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. @@ -101,7 +101,7 @@ property. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. For more information, see . + Each application (event source) can define its own numbered categories and the text strings to which they are mapped. The Event Viewer can use the category to filter events in the log. The categories must be numbered consecutively beginning with the number 1. The category number is specified by the property. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. For more information, see . ]]> diff --git a/xml/System.Diagnostics/EventLogInstaller.xml b/xml/System.Diagnostics/EventLogInstaller.xml index 6e134535bb9b7..258af343d9d67 100644 --- a/xml/System.Diagnostics/EventLogInstaller.xml +++ b/xml/System.Diagnostics/EventLogInstaller.xml @@ -456,7 +456,7 @@ SVC_UPDATE.EXE Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method skips registering the source if the property matches a source name that is already registered for the same event log specified in the property. - An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the tool installs each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the tool installs each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -915,7 +915,7 @@ SVC_UPDATE.EXE Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](~/docs/framework/tools/installutil-exe-installer-tool.md). The tool calls the method, when this or another component has failed to install, to undo any changes that the installation process has already made. - An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool rolls back each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool rolls back each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -985,7 +985,7 @@ SVC_UPDATE.EXE Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](~/docs/framework/tools/installutil-exe-installer-tool.md) in uninstall mode. The tool automatically calls the method to restore the parts of the system that were affected by the installation to their pre-installation states. This includes deleting registry information that is associated with the event log being uninstalled. - An application's uninstall routine uses the project installer's property to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool uninstalls each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's uninstall routine uses the project installer's property to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool uninstalls each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> diff --git a/xml/System.Diagnostics/EventLogPermission.xml b/xml/System.Diagnostics/EventLogPermission.xml index 064b5c17248fd..d646c83b445cb 100644 --- a/xml/System.Diagnostics/EventLogPermission.xml +++ b/xml/System.Diagnostics/EventLogPermission.xml @@ -23,7 +23,7 @@ Do not grant to partially trusted code. The ability to read and write the event log enables code to perform actions such as issuing event log messages in the name of another application. > [!NOTE] -> If the event source that is specified by the property for the event log does not exist, a new event source is created. To create an event source in Windows Vista and later versions of Windows, or Windows Server 2003, you must have administrative privileges. +> If the event source that is specified by the property for the event log does not exist, a new event source is created. To create an event source in Windows Vista and later versions of Windows, or Windows Server 2003, you must have administrative privileges. > > The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. > diff --git a/xml/System.Diagnostics/EventLogTraceListener.xml b/xml/System.Diagnostics/EventLogTraceListener.xml index c49d1074659b7..53ff375814a7a 100644 --- a/xml/System.Diagnostics/EventLogTraceListener.xml +++ b/xml/System.Diagnostics/EventLogTraceListener.xml @@ -16,9 +16,9 @@ can be added to the , , or collections to send output from tracing or debugging to an . You can add the instance in your code or specify it in the application configuration file. To add an using an application configuration file, edit the file that corresponds to the name of your application or the app.config file in a [!INCLUDE[vsprvslong](~/includes/vsprvslong-md.md)] project. In this file, insert an element for a type. + An instance of this can be added to the , , or collections to send output from tracing or debugging to an . You can add the instance in your code or specify it in the application configuration file. To add an using an application configuration file, edit the file that corresponds to the name of your application or the app.config file in a [!INCLUDE[vsprvslong](~/includes/vsprvslong-md.md)] project. In this file, insert an element for a type. - The following example adds a object named `myListener` to the collection. The `initializeData` parameter specifies the name of the event log source that is to be passed to the constructor. + The following example adds a object named `myListener` to the collection. The `initializeData` parameter specifies the name of the event log source that is to be passed to the constructor. ``` @@ -53,7 +53,7 @@ ## Examples - The following example creates a trace listener that sends output to an event log. First, the code creates a new that uses the source `myEventLogSource`. Next, `myTraceListener` is added to the collection. Finally, the example sends a line of output to the object. + The following example creates a trace listener that sends output to an event log. First, the code creates a new that uses the source `myEventLogSource`. Next, `myTraceListener` is added to the collection. Finally, the example sends a line of output to the object. [!code-cpp[Classic EventLogTraceListener Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic EventLogTraceListener Example/CPP/source.cpp#1)] [!code-csharp[Classic EventLogTraceListener Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic EventLogTraceListener Example/CS/source.cs#1)] diff --git a/xml/System.Diagnostics/EventSchemaTraceListener.xml b/xml/System.Diagnostics/EventSchemaTraceListener.xml index 48b594874064f..25ce2a091be05 100644 --- a/xml/System.Diagnostics/EventSchemaTraceListener.xml +++ b/xml/System.Diagnostics/EventSchemaTraceListener.xml @@ -72,13 +72,13 @@ |`EventID`|None|Always present.|This element represents parameter input (`id`).| |`Execution`|`ProcessID`|Depends on the presence of the flag in the property.|The `ProcessID` attribute is specified in the . On the Microsoft Windows 98 and Windows Millenium Edition operating systems, if `ProcessID` is larger than 2,147,483,647, it is a positive representation of a negative number and should be converted to obtain the correct process identifier.| ||`ThreadID`|Present when `ProcessID` is present.|The `ThreadID` attribute is specified in the .| -|`Level`|None|Always present.|This element represents parameter input (the numeric value of `eventType`). Parameter values that are larger than 255 are output as a level 8, which represents . Trace event types , , , , and are output as levels 1, 2, 4, 8, and 10, respectively.| +|`Level`|None|Always present.|This element represents parameter input (the numeric value of `eventType`). Parameter values that are larger than 255 are output as a level 8, which represents . Trace event types , , , , and are output as levels 1, 2, 4, 8, and 10, respectively.| |`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|Only one logical operation can exist. Therefore, the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| |`OpCode`|None|Present when `Level` is greater than 255.|This element represents Trace event types that have numeric values greater than 255. , , , , or are output as levels 1, 2, 4, 8, and 10, respectively.| |`Provider`|`GUID`|Always present.|Always empty.| |`RenderingInfo`|`Culture`|Always present.|This attribute represents a resource string for the event type. It is always "en-EN\\".| |`System`|`Name`|Always present.|| -|`TimeCreated`|`SystemTime`|Depends on the presence of the flag in the property.|The time is the value of the property. This property is expressed as Coordinated Universal Time| +|`TimeCreated`|`SystemTime`|Depends on the presence of the flag in the property.|The time is the value of the property. This property is expressed as Coordinated Universal Time| |`TimeStamp`|None|Depends on the presence of the flag in the property.|This element is specified in the .| |`UserData`|None|Present for data logs.|This element contains `Data` elements with unescaped, user-provided data from a method.| @@ -131,7 +131,7 @@ ## Examples - The following code example demonstrates how to use the constructor. + The following code example demonstrates how to use the constructor. [!code-csharp[System.Diagnostics.EventSchemaTraceListener.Ctors#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/CS/program.cs#1)] [!code-vb[System.Diagnostics.EventSchemaTraceListener.Ctors#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb#1)] @@ -161,7 +161,7 @@ constructor. + The following code example demonstrates how to use the constructor. [!code-csharp[System.Diagnostics.EventSchemaTraceListener.Ctors#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/CS/program.cs#2)] [!code-vb[System.Diagnostics.EventSchemaTraceListener.Ctors#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb#2)] @@ -198,7 +198,7 @@ ## Examples - The following code example demonstrates how to use the constructor. + The following code example demonstrates how to use the constructor. [!code-csharp[System.Diagnostics.EventSchemaTraceListener.Ctors#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/CS/program.cs#3)] [!code-vb[System.Diagnostics.EventSchemaTraceListener.Ctors#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb#3)] @@ -237,7 +237,7 @@ ## Examples - The following code example demonstrates how to use the constructor. + The following code example demonstrates how to use the constructor. [!code-csharp[System.Diagnostics.EventSchemaTraceListener.Ctors#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/CS/program.cs#4)] [!code-vb[System.Diagnostics.EventSchemaTraceListener.Ctors#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb#4)] @@ -278,7 +278,7 @@ ## Examples - The following code example demonstrates how to use the constructor. + The following code example demonstrates how to use the constructor. [!code-csharp[System.Diagnostics.EventSchemaTraceListener.Ctors#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/CS/program.cs#5)] [!code-vb[System.Diagnostics.EventSchemaTraceListener.Ctors#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.EventSchemaTraceListener.Ctors/VB/program.vb#5)] @@ -752,7 +752,7 @@ method is called and the `format` string and `args` array are passed in as parameters. This method formats the `args` object array and writes the formatted array as the `Data` node in the `EventData` element. + The `eventCache`, `source`, `eventType`, and `id` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The method is called and the `format` string and `args` array are passed in as parameters. This method formats the `args` object array and writes the formatted array as the `Data` node in the `EventData` element. > [!IMPORTANT] > This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. @@ -824,7 +824,7 @@ method is used to correlate related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Data` element. The method is called to convert the `relatedActivityId` value to a "B" formatted string, which appears in the header. The `Opcode` element in the footer identifies the trace event type as a . + The method is used to correlate related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before it is written. Therefore, a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Data` element. The method is called to convert the `relatedActivityId` value to a "B" formatted string, which appears in the header. The `Opcode` element in the footer identifies the trace event type as a . > [!IMPORTANT] > The method should not be called by application code. It is intended to be used by a object to emit the trace information for its method. diff --git a/xml/System.Diagnostics/EventSourceCreationData.xml b/xml/System.Diagnostics/EventSourceCreationData.xml index c3040fef19b09..1f07325238f34 100644 --- a/xml/System.Diagnostics/EventSourceCreationData.xml +++ b/xml/System.Diagnostics/EventSourceCreationData.xml @@ -18,7 +18,7 @@ ## Remarks Use the class to configure a new source for writing localized entries to an event log. It is not necessary to use this class to read from an event log. - This class defines the configuration settings for a new event source and its associated event log. The associated event log can be on the local computer or a remote computer. To create a new source for a new or existing event log on the local computer, set the and properties of an and call the method. This method creates the event source you specify in the property and registers it for the event log specified in . This behavior is similar to using the class to register an event source for an event log. + This class defines the configuration settings for a new event source and its associated event log. The associated event log can be on the local computer or a remote computer. To create a new source for a new or existing event log on the local computer, set the and properties of an and call the method. This method creates the event source you specify in the property and registers it for the event log specified in . This behavior is similar to using the class to register an event source for an event log. Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. @@ -71,7 +71,7 @@ instance, configure the instance properties for your application, and call the method. After the source is registered, you can write entries from the source using the or methods. + To write entries to an event log, you must first create an event source for the event log. To register a new source, initialize an instance, configure the instance properties for your application, and call the method. After the source is registered, you can write entries from the source using the or methods. You can register the event source with localized resources for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes string values directly to the event log, you do not need to set these properties. @@ -955,7 +955,7 @@ SVC_UPDATE.EXE method uses the , , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. + The source name is often the name of the application, or the name of a component within a large application. The method uses the , , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. After the registry values for the source are created, your application can use the source to write entries to the configured event log. diff --git a/xml/System.Diagnostics/PerformanceCounter.xml b/xml/System.Diagnostics/PerformanceCounter.xml index 5ce14c2073191..dd805b9d93977 100644 --- a/xml/System.Diagnostics/PerformanceCounter.xml +++ b/xml/System.Diagnostics/PerformanceCounter.xml @@ -42,7 +42,7 @@ To read from a performance counter, create an instance of the class, set the , , and, optionally, the or properties, and then call the method to take a performance counter reading. - To publish performance counter data, create one or more custom counters using the method, create an instance of the class, set the , and, optionally, or properties, and then call the , , or methods, or set the property to change the value of your custom counter. + To publish performance counter data, create one or more custom counters using the method, create an instance of the class, set the , and, optionally, or properties, and then call the , , or methods, or set the property to change the value of your custom counter. > [!NOTE] > The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. @@ -821,7 +821,7 @@ |Track a higher-capacity number of items or operations per second.|`RateOfCountsPerSecond64`|Tracking orders received per second on a site with very high volume.| |Calculate the average time to perform a process or to process an item|`AverageTimer32`|Calculate the average time an order takes to be processed.| - When you create a counter whose type requires the use of a corresponding base counter, you must declare the counter and the base in the you pass into the method. + When you create a counter whose type requires the use of a corresponding base counter, you must declare the counter and the base in the you pass into the method. > [!NOTE] > If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. @@ -1191,7 +1191,7 @@ |\|_| |/|_| - The property of the object obtained from the property is a common source of instance names that can contain invalid characters. + The property of the object obtained from the property is a common source of instance names that can contain invalid characters. diff --git a/xml/System.Diagnostics/Process.xml b/xml/System.Diagnostics/Process.xml index 2cfe0b220339b..6c83f66521aed 100644 --- a/xml/System.Diagnostics/Process.xml +++ b/xml/System.Diagnostics/Process.xml @@ -66,15 +66,15 @@ ## [!INCLUDE[net_core](~/includes/net-core-md.md)] Notes - In the .NET Framework on the desktop, the class by default uses encodings, which are typically code page encodings, for the input, output, and error streams. For example code, on systems whose culture is English (United States), code page 437 is the default encoding for the class. However, [!INCLUDE[net_core](~/includes/net-core-md.md)] may make only a limited subset of these encodings available. If this is the case, it uses as the default encoding. + In the .NET Framework on the desktop, the class by default uses encodings, which are typically code page encodings, for the input, output, and error streams. For example code, on systems whose culture is English (United States), code page 437 is the default encoding for the class. However, [!INCLUDE[net_core](~/includes/net-core-md.md)] may make only a limited subset of these encodings available. If this is the case, it uses as the default encoding. If a object depends on specific code page encodings, you can still make them available by doing the following *before* you call any methods: 1. Add a reference to the System.Text.Encoding.CodePages.dll assembly to your project. -2. Retrieve the object from the property. +2. Retrieve the object from the property. -3. Pass the object to the method to make the additional encodings supported by the encoding provider available. +3. Pass the object to the method to make the additional encodings supported by the encoding provider available. The class will then automatically use the default system encoding rather than UTF8, provided that you have registered the encoding provider before calling any methods. @@ -137,7 +137,7 @@ If you use a `static` overload of the method to start a new system process, the method creates a new component and associates it with the process. - When the property is set to its default value, `true`, you can start applications and documents in a way that is similar to using the `Run` dialog box of the Windows `Start` menu. When is `false`, you can start only executables. + When the property is set to its default value, `true`, you can start applications and documents in a way that is similar to using the `Run` dialog box of the Windows `Start` menu. When is `false`, you can start only executables. Any executable file that you can call from the command line can be started in one of two ways: by setting the appropriate members of the property and calling the method with no parameters, or by passing the appropriate parameter to the `static` member. @@ -265,7 +265,7 @@ 2. Set to `true`. -3. Add your event handler to the event. The event handler must match the delegate signature. +3. Add your event handler to the event. The event handler must match the delegate signature. 4. Start the . @@ -345,7 +345,7 @@ 2. Set to `true`. -3. Add your event handler to the event. The event handler must match the delegate signature. +3. Add your event handler to the event. The event handler must match the delegate signature. 4. Start the . @@ -1815,7 +1815,7 @@ The following code example creates a process that prints a file. It sets the , , or on remote computers. > [!NOTE] -> When the associated process is executing on the local machine, this property returns a period (".") for the machine name. You should use the property to get the correct machine name. +> When the associated process is executing on the local machine, this property returns a period (".") for the machine name. You should use the property to get the correct machine name. @@ -3573,7 +3573,7 @@ The following code example creates a process that prints a file. It sets the writes text to its standard error stream, that text is normally displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. @@ -3684,7 +3684,7 @@ p.WaitForExit(); A can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, writing to the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, writing to the stream throws an exception. @@ -3744,7 +3744,7 @@ p.WaitForExit(); When a writes text to its standard stream, that text is normally displayed on the console. By redirecting the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. > [!NOTE] -> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. +> To use , you must set to `false`, and you must set to `true`. Otherwise, reading from the stream throws an exception. The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. @@ -4014,7 +4014,7 @@ p.WaitForExit(); Starting a process by specifying its file name is similar to typing the information in the `Run` dialog box of the Windows `Start` menu. Therefore, the file name does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the file name can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated.doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the `Run` dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". - This overload does not allow command-line arguments for the process. If you need to specify one or more command-line arguments for the process, use the or overloads. + This overload does not allow command-line arguments for the process. If you need to specify one or more command-line arguments for the process, use the or overloads. Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance, specified start information (including the file name), and want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start. @@ -4309,7 +4309,7 @@ p.WaitForExit(); If the file name involves a nonexecutable file, such as a .doc file, you can include a verb specifying what action to take on the file. For example, you could set the to "Print" for a file ending in the .doc extension. The file name specified in the property does not need to have an extension if you manually enter a value for the property. However, if you use the property to determine what verbs are available, you must include the extension. - You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . + You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . If you did not use the method to start a process, the property does not reflect the parameters used to start the process. For example, if you use to get an array of processes running on the computer, the property of each does not contain the original file name or arguments used to start the process. @@ -4832,7 +4832,7 @@ p.WaitForExit(); ## Remarks makes the current thread wait until the associated process terminates. It should be called after all other methods are called on the process. To avoid blocking the current thread, use the event. - This method instructs the component to wait a finite amount of time for the process to exit. If the associated process does not exit by the end of the interval because the request to terminate is denied, `false` is returned to the calling procedure. You can specify a negative number () for `milliseconds`, and will behave the same as the overload. If you pass 0 (zero) to the method, it returns `true` only if the process has already exited; otherwise, it immediately returns `false`. + This method instructs the component to wait a finite amount of time for the process to exit. If the associated process does not exit by the end of the interval because the request to terminate is denied, `false` is returned to the calling procedure. You can specify a negative number () for `milliseconds`, and will behave the same as the overload. If you pass 0 (zero) to the method, it returns `true` only if the process has already exited; otherwise, it immediately returns `false`. > [!NOTE] > In the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] and earlier versions, if `milliseconds` was -1, the overload waited for milliseconds (approximately 24 days), not indefinitely. diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml index a6952d1adaec9..22ffde3b9b85a 100644 --- a/xml/System.Diagnostics/ProcessStartInfo.xml +++ b/xml/System.Diagnostics/ProcessStartInfo.xml @@ -664,7 +664,7 @@ For more information about secure strings and an example of how to obtain a password to set this property, see the class. > [!NOTE] -> If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. +> If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. ]]> @@ -1077,7 +1077,7 @@ p.WaitForExit(); > [!IMPORTANT] > The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. - If the property is not `null` or an empty string, the property must be `false`, or an will be thrown when the method is called. + If the property is not `null` or an empty string, the property must be `false`, or an will be thrown when the method is called. ]]> @@ -1127,7 +1127,7 @@ p.WaitForExit(); Setting this property to `false` enables you to redirect input, output, and error streams. > [!NOTE] -> must be `false` if the property is not `null` or an empty string, or an will be thrown when the method is called. +> must be `false` if the property is not `null` or an empty string, or an will be thrown when the method is called. When you use the operating system shell to start processes, you can start any document (which is any registered file type associated with an executable that has a default open action) and perform operations on the file, such as printing, by using the object. When is `false`, you can start only executables by using the object. diff --git a/xml/System.Diagnostics/ProcessThread.xml b/xml/System.Diagnostics/ProcessThread.xml index ce9919e7fc7c1..de1485d8c7eb1 100644 --- a/xml/System.Diagnostics/ProcessThread.xml +++ b/xml/System.Diagnostics/ProcessThread.xml @@ -97,7 +97,7 @@ ## Remarks The is the starting priority for the process thread. You can view information about the base priority through the System Monitor's Priority Base counter. - The operating system computes a thread's base priority by combining the thread's priority level range with the process's priority class. You can set the process's property to one of the values in the enumeration, which are , , , , , or . You can set the thread's property to a range of values that bounds the thread's base priority. Win32 uses four priority classes with seven base priority levels per class. + The operating system computes a thread's base priority by combining the thread's priority level range with the process's priority class. You can set the process's property to one of the values in the enumeration, which are , , , , , or . You can set the thread's property to a range of values that bounds the thread's base priority. Win32 uses four priority classes with seven base priority levels per class. The thread's current priority might deviate from the base priority. For example, the operating system can change the property based on the time elapsed or other boosts when a process must be put ahead of others for access to the processor. In addition, you can set the property to cause the system to temporarily boost the priority of a thread whenever the process is taken out of the wait state. The priority is reset when the process returns to the wait state. diff --git a/xml/System.Diagnostics/Stopwatch.xml b/xml/System.Diagnostics/Stopwatch.xml index c68842df3c03c..ea65e1967d6d6 100644 --- a/xml/System.Diagnostics/Stopwatch.xml +++ b/xml/System.Diagnostics/Stopwatch.xml @@ -43,7 +43,7 @@ The class assists the manipulation of timing-related performance counters within managed code. Specifically, the field and method can be used in place of the unmanaged Win32 APIs `QueryPerformanceFrequency` and `QueryPerformanceCounter`. > [!NOTE] -> On a multiprocessor computer, it does not matter which processor the thread runs on. However, because of bugs in the BIOS or the Hardware Abstraction Layer (HAL), you can get different timing results on different processors. To specify processor affinity for a thread, use the method. +> On a multiprocessor computer, it does not matter which processor the thread runs on. However, because of bugs in the BIOS or the Hardware Abstraction Layer (HAL), you can get different timing results on different processors. To specify processor affinity for a thread, use the method. @@ -246,7 +246,7 @@ By default, the elapsed time value of a instance equals the total of all measured time intervals. Each call to begins counting at the cumulative elapsed time; each call to ends the current interval measurement and freezes the cumulative elapsed time value. Use the method to clear the cumulative elapsed time in an existing instance. > [!NOTE] -> ticks are different from . Each tick in the value represents one 100-nanosecond interval. Each tick in the value represents the time interval equal to 1 second divided by the . +> ticks are different from . Each tick in the value represents one 100-nanosecond interval. Each tick in the value represents the time interval equal to 1 second divided by the . @@ -342,7 +342,7 @@ class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the current property of the instance. + If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the current property of the instance. diff --git a/xml/System.Diagnostics/TextWriterTraceListener.xml b/xml/System.Diagnostics/TextWriterTraceListener.xml index 43ea031dc91e9..95e2146c0fc2f 100644 --- a/xml/System.Diagnostics/TextWriterTraceListener.xml +++ b/xml/System.Diagnostics/TextWriterTraceListener.xml @@ -100,7 +100,7 @@ stream as the recipient of the tracing or debugging output. Its property is initialized to an empty string ("", or ). + This constructor uses the stream as the recipient of the tracing or debugging output. Its property is initialized to an empty string ("", or ). diff --git a/xml/System.Diagnostics/ThreadState.xml b/xml/System.Diagnostics/ThreadState.xml index fa44a3179f022..59d9a9efd9960 100644 --- a/xml/System.Diagnostics/ThreadState.xml +++ b/xml/System.Diagnostics/ThreadState.xml @@ -27,7 +27,7 @@ ## Remarks > [!IMPORTANT] -> There are two thread state enumerations, and . The thread state enumerations are only of interest in a few debugging scenarios. Your code should never use thread state to synchronize the activities of threads. +> There are two thread state enumerations, and . The thread state enumerations are only of interest in a few debugging scenarios. Your code should never use thread state to synchronize the activities of threads. ]]> diff --git a/xml/System.Diagnostics/Trace.xml b/xml/System.Diagnostics/Trace.xml index 3d501ab9b90c8..3505b3f1fbf70 100644 --- a/xml/System.Diagnostics/Trace.xml +++ b/xml/System.Diagnostics/Trace.xml @@ -64,7 +64,7 @@ ## Examples - The following example uses to indicate the beginning and the end of a program's execution. The example also uses the and methods to distinguish the tracing output. For a more complete example of the use of , see [How to: Add Trace Statements to Application Code](~/docs/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code.md). + The following example uses to indicate the beginning and the end of a program's execution. The example also uses the and methods to distinguish the tracing output. For a more complete example of the use of , see [How to: Add Trace Statements to Application Code](~/docs/framework/debug-trace-profile/how-to-add-trace-statements-to-application-code.md). [!code-cpp[Classic Trace Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace Example/CPP/source.cpp#1)] [!code-csharp[Classic Trace Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic Trace Example/CS/source.cs#1)] @@ -113,7 +113,7 @@ method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). + Use the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends a failure message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. @@ -122,7 +122,7 @@ > [!NOTE] > The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](~/docs/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace.md), the [<remove>](~/docs/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace.md), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: + You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ``` @@ -188,7 +188,7 @@ method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). + Use the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. @@ -197,7 +197,7 @@ > [!NOTE] > The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](~/docs/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace.md), the [<remove>](~/docs/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace.md), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: + You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ``` @@ -265,7 +265,7 @@ method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). + Use the method if you want to do assertions in release builds. The method works only in debug builds. For more information, see [Assertions in Managed Code](http://msdn.microsoft.com/library/70ab2522-6486-4076-a1a9-e0f11cd0f3a1). Typically, the method is used to identify logic errors during program development. evaluates the condition. If the result is `false`, it sends the specified diagnostic message and detailed message to the collection. You can customize this behavior by adding a to, or removing one from, the collection. @@ -274,7 +274,7 @@ > [!NOTE] > The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](~/docs/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace.md), the [<remove>](~/docs/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace.md), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). - You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: + You can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ``` @@ -1282,9 +1282,9 @@ End of list of errors This method calls the method of the trace listener. > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. @@ -1345,9 +1345,9 @@ End of list of errors This method calls the method of the trace listener. > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. @@ -1412,9 +1412,9 @@ End of list of errors This method calls the method of the trace listener. > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. @@ -1479,9 +1479,9 @@ End of list of errors This method calls the method of the trace listener. > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. diff --git a/xml/System.Diagnostics/TraceEventCache.xml b/xml/System.Diagnostics/TraceEventCache.xml index 8140cae5ff95b..0bb495cc239aa 100644 --- a/xml/System.Diagnostics/TraceEventCache.xml +++ b/xml/System.Diagnostics/TraceEventCache.xml @@ -30,7 +30,7 @@ > [!NOTE] > The class, designed as a performance optimization for trace listener calls, is of interest only to developers creating custom trace listeners. - The class is used as a parameter in tracing methods to accurately identify the source of a trace event. Examples of methods that use are and . The property contains data that can be used to correlate the trace with related traces. + The class is used as a parameter in tracing methods to accurately identify the source of a trace event. Examples of methods that use are and . The property contains data that can be used to correlate the trace with related traces. ]]> @@ -159,7 +159,7 @@ class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. The is accessed through the property. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity from the stack + The correlation data is stored as an object in the call context with the name "System.Diagnostics.Trace.CorrelationManagerSlot". The class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. The is accessed through the property. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity from the stack ]]> @@ -230,7 +230,7 @@ property formatted as a string. + The thread identifier is the value of the property formatted as a string. ]]> @@ -265,7 +265,7 @@ method to get the timestamp. If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the property of . + The get accessor calls the method to get the timestamp. If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the property of . ]]> diff --git a/xml/System.Diagnostics/TraceEventType.xml b/xml/System.Diagnostics/TraceEventType.xml index bda0d55927265..45e92aa3300dc 100644 --- a/xml/System.Diagnostics/TraceEventType.xml +++ b/xml/System.Diagnostics/TraceEventType.xml @@ -25,7 +25,7 @@ is used to identify the event that caused a trace in calls to the methods. + is used to identify the event that caused a trace in calls to the methods. ]]> diff --git a/xml/System.Diagnostics/TraceFilter.xml b/xml/System.Diagnostics/TraceFilter.xml index b587703743f5b..8698d813286a8 100644 --- a/xml/System.Diagnostics/TraceFilter.xml +++ b/xml/System.Diagnostics/TraceFilter.xml @@ -107,7 +107,7 @@ method to indicate tracing should occur when the trace event type of the event is equal to . + The following code example shows how to override the method to indicate tracing should occur when the trace event type of the event is equal to . [!code-cpp[System.Diagnostics.TraceFilter#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.diagnostics.tracefilter/cpp/source.cpp#2)] [!code-csharp[System.Diagnostics.TraceFilter#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.diagnostics.tracefilter/cs/source.cs#2)] diff --git a/xml/System.Diagnostics/TraceListener.xml b/xml/System.Diagnostics/TraceListener.xml index a167948aee330..bd5fe462fc9f6 100644 --- a/xml/System.Diagnostics/TraceListener.xml +++ b/xml/System.Diagnostics/TraceListener.xml @@ -992,7 +992,7 @@ property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the property for the console trace listener to to add call stack information to the trace output. + The property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the property for the console trace listener to to add call stack information to the trace output. The enumeration is not used by the following classes and methods: diff --git a/xml/System.Diagnostics/TraceListenerCollection.xml b/xml/System.Diagnostics/TraceListenerCollection.xml index ca5ed041de620..c4e805f635235 100644 --- a/xml/System.Diagnostics/TraceListenerCollection.xml +++ b/xml/System.Diagnostics/TraceListenerCollection.xml @@ -30,7 +30,7 @@ list is used to specify the output listeners for the and the collections. You cannot create an instance of this class. + The list is used to specify the output listeners for the and the collections. You cannot create an instance of this class. This list is thread-safe, however the methods used to access the list and the enumerator do not take synchronization locks. Instead, the collection is copied, the copy is modified, and a reference is set to the copy of the collection. Methods like , , and modify the elements in the collection. @@ -41,7 +41,7 @@ ## Examples - The following example creates a that writes to the console screen. The code then adds the new listener to the . + The following example creates a that writes to the console screen. The code then adds the new listener to the . [!code-cpp[Classic Trace.Listeners Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic Trace.Listeners Example/CPP/source.cpp#1)] [!code-csharp[Classic Trace.Listeners Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic Trace.Listeners Example/CS/source.cs#1)] @@ -84,7 +84,7 @@ that outputs to the console screen. The code then adds the new listener to the . + The following example creates a that outputs to the console screen. The code then adds the new listener to the . [!code-cpp[Classic TraceListenerCollection.Add Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceListenerCollection.Add Example/CPP/source.cpp#1)] [!code-csharp[Classic TraceListenerCollection.Add Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceListenerCollection.Add Example/CS/source.cs#1)] diff --git a/xml/System.Diagnostics/TraceLogRetentionOption.xml b/xml/System.Diagnostics/TraceLogRetentionOption.xml index 1c496d55f1ada..73610e4bf2939 100644 --- a/xml/System.Diagnostics/TraceLogRetentionOption.xml +++ b/xml/System.Diagnostics/TraceLogRetentionOption.xml @@ -15,7 +15,7 @@ enumeration is used to specify the value of the property in the class. That property setting determines the possible and default values for the and properties. + The enumeration is used to specify the value of the property in the class. That property setting determines the possible and default values for the and properties. You can set the and properties through the `maximumFileSize` and `maximumNumberOfFiles` custom attributes in the configuration file or by using the `maximumFileSize` or `maximumNumberOfFiles` parameters in the constructor. If the `maximumFileSize` or `maximumNumberOfFiles` attributes in the configuration file specify an out-of-range value, the properties are set to their default values. If you specify an out-of-range value in the `maximumFileSize` or `maximumNumberOfFiles` parameter when you call the constructor, an is thrown. diff --git a/xml/System.Diagnostics/TraceSource.xml b/xml/System.Diagnostics/TraceSource.xml index 3221d52a4077c..61e40402eaa90 100644 --- a/xml/System.Diagnostics/TraceSource.xml +++ b/xml/System.Diagnostics/TraceSource.xml @@ -67,7 +67,7 @@ > [!NOTE] > You should not call the tracing methods during finalization. Doing so can result in an being thrown. - You can customize the tracing output's target by adding or removing instances to or from the collection stored in the property. By default, trace output is produced using an instance of the class. The preceding configuration file example demonstrates removing the and adding a to produce the trace output for the trace source. For more information, see [<listeners>](~/docs/framework/configure-apps/file-schema/trace-debug/listeners-element-for-source.md) and [<sharedListeners>](~/docs/framework/configure-apps/file-schema/trace-debug/sharedlisteners-element.md). + You can customize the tracing output's target by adding or removing instances to or from the collection stored in the property. By default, trace output is produced using an instance of the class. The preceding configuration file example demonstrates removing the and adding a to produce the trace output for the trace source. For more information, see [<listeners>](~/docs/framework/configure-apps/file-schema/trace-debug/listeners-element-for-source.md) and [<sharedListeners>](~/docs/framework/configure-apps/file-schema/trace-debug/sharedlisteners-element.md). > [!NOTE] > Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and cannot be enumerated in this topic. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. @@ -227,7 +227,7 @@ property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. + The property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. The following is a sample of a trace source element specifying the custom attribute `SecondTraceSourceAttribute`: @@ -561,7 +561,7 @@ ## Remarks The method, like the method, is intended for automated tools, but it also allows the attaching of an additional object, such as an exception instance, to the trace. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -817,7 +817,7 @@ The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. - The trace content is listener specific. The default method writes the source name, event type, and numeric identity in the trace header, then calls the method, passing the `format` string and `args` array and using the property to format the string as the message output. + The trace content is listener specific. The default method writes the source name, event type, and numeric identity in the trace header, then calls the method, passing the `format` string and `args` array and using the property to format the string as the message output. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -882,7 +882,7 @@ ## Remarks The method provides an informational message intended to be read by users and not by tools. - calls the method, setting `eventType` to and passing the informative message as the message string. The method in turn calls the method of each trace listener. + calls the method, setting `eventType` to and passing the informative message as the message string. The method in turn calls the method of each trace listener. ]]> @@ -938,7 +938,7 @@ The method provides an informational message intended to be read by users and not by tools. - calls the method, setting `eventType` to and passing the message content as an object array with formatting information. The method in turn calls the method of each trace listener. + calls the method, setting `eventType` to and passing the message content as an object array with formatting information. The method in turn calls the method of each trace listener. ]]> @@ -993,7 +993,7 @@ method calls the method of each trace listener in the property to write the trace information. The default method in the base class calls the method to process the call, setting `eventType` to and appending a string representation of the `relatedActivityId` GUID to `message`. + The method calls the method of each trace listener in the property to write the trace information. The default method in the base class calls the method to process the call, setting `eventType` to and appending a string representation of the `relatedActivityId` GUID to `message`. is intended to be used with the logical operations of a . The `relatedActivityId` parameter relates to the property of a object. If a logical operation begins in one activity and transfers to another, the second activity logs the transfer by calling the method. The call relates the new activity identity to the previous identity. The most likely consumer of this functionality is a trace viewer that can report logical operations that span multiple activities. diff --git a/xml/System.Diagnostics/TraceSwitch.xml b/xml/System.Diagnostics/TraceSwitch.xml index d65064ba32971..5160ec545b0f0 100644 --- a/xml/System.Diagnostics/TraceSwitch.xml +++ b/xml/System.Diagnostics/TraceSwitch.xml @@ -47,7 +47,7 @@ ``` - This configuration section defines a with the set to `mySwitch`, and the set to 1, which corresponds to the enumeration value . + This configuration section defines a with the set to `mySwitch`, and the set to 1, which corresponds to the enumeration value . > [!NOTE] > In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. @@ -58,7 +58,7 @@ [!code-csharp[Classic TraceSwitch.TraceError Example#3](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CS/remarks.cs#3)] [!code-vb[Classic TraceSwitch.TraceError Example#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/VB/remarks.vb#3)] - By default, the switch property is set using the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, the of the new switch defaults to . + By default, the switch property is set using the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, the of the new switch defaults to . You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -77,7 +77,7 @@ ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . [!code-cpp[Classic TraceSwitch.TraceError Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CPP/source.cpp#1)] [!code-csharp[Classic TraceSwitch.TraceError Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CS/source.cs#1)] @@ -139,7 +139,7 @@ [!code-csharp[Classic TraceSwitch.TraceError Example#3](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CS/remarks.cs#3)] [!code-vb[Classic TraceSwitch.TraceError Example#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/VB/remarks.vb#3)] - When the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to . + When the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to . The class provides the , , , and properties to test the of the switch. The property gets or sets the switch's . @@ -149,7 +149,7 @@ ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . [!code-cpp[Classic TraceSwitch.TraceError Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CPP/source.cpp#1)] [!code-csharp[Classic TraceSwitch.TraceError Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CS/source.cs#1)] @@ -245,14 +245,14 @@ > [!NOTE] > In the .NET Framework version 2.0, you can use text to specify the value for a switch. For example, `true` for a or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. - When the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to . + When the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to . Setting this property updates the , , , and properties to reflect the new value. ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . [!code-cpp[Classic TraceSwitch.Level Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.Level Example/CPP/source.cpp#1)] [!code-csharp[Classic TraceSwitch.Level Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.Level Example/CS/source.cs#1)] @@ -370,12 +370,12 @@ , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to the highest importance, , , only error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to the highest importance, , , only error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . [!code-cpp[Classic TraceSwitch.TraceError Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CPP/source.cpp#1)] [!code-csharp[Classic TraceSwitch.TraceError Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CS/source.cs#1)] @@ -415,12 +415,12 @@ , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , informational messages, warnings, and error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , informational messages, warnings, and error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . [!code-cpp[Classic TraceSwitch.TraceInfo Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceInfo Example/CPP/source.cpp#1)] [!code-csharp[Classic TraceSwitch.TraceInfo Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceInfo Example/CS/source.cs#1)] @@ -460,12 +460,12 @@ , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , all debugging and tracing messages are transmitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , all debugging and tracing messages are transmitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes both error messages when the property is set to . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes both error messages when the property is set to . [!code-cpp[Classic TraceSwitch.TraceError Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CPP/source.cpp#1)] [!code-csharp[Classic TraceSwitch.TraceError Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceError Example/CS/source.cs#1)] @@ -505,12 +505,12 @@ , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , warnings and error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , warnings and error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message when the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message when the is less than . [!code-cpp[Classic TraceSwitch.TraceWarning Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceWarning Example/CPP/source.cpp#1)] [!code-csharp[Classic TraceSwitch.TraceWarning Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic TraceSwitch.TraceWarning Example/CS/source.cs#1)] diff --git a/xml/System.Diagnostics/XmlWriterTraceListener.xml b/xml/System.Diagnostics/XmlWriterTraceListener.xml index 34a47eac00fd1..a00f7cd10a802 100644 --- a/xml/System.Diagnostics/XmlWriterTraceListener.xml +++ b/xml/System.Diagnostics/XmlWriterTraceListener.xml @@ -207,7 +207,7 @@ property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + This constructor initializes the property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ``` ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = @@ -242,7 +242,7 @@ property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + This constructor initializes the property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ``` ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = @@ -282,7 +282,7 @@ > [!NOTE] > To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. - The property is set to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + The property is set to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ``` ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = @@ -338,7 +338,7 @@ instances in the collection. By default, the collection contains an instance of . You can customize this behavior by adding or removing a from the collection. + The default behavior is to display the message and detailed message in a message box when the application is running in user-interface mode, and to the instances in the collection. By default, the collection contains an instance of . You can customize this behavior by adding or removing a from the collection. ]]> @@ -509,7 +509,7 @@ method is called, passing in the `format` string and `args` array as parameters, to format the `args` object array as the `Message` element. + The `eventCache`, `source`, `eventType`, and `id` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The method is called, passing in the `format` string and `args` array as parameters, to format the `args` object array as the `Message` element. > [!IMPORTANT] > This method is not intended to be called directly by application code. It is called by methods of the , , and classes to write trace data. @@ -549,7 +549,7 @@ method is used for the correlation of related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Message` element. The method is called to convert the `relatedActivityId`value to a "B" formatted string, which appears in the header. The `SubTypeName` element in the footer identifies the trace event type as a . + The method is used for the correlation of related traces. The `eventCache`, `source`, `id`, and `relatedActivityId` parameters are used in the header and footer of the trace. The `id` parameter is converted to an unsigned integer before writing, so a negative `id` value is written as a large positive integer. The `message` parameter is written as the `Message` element. The method is called to convert the `relatedActivityId`value to a "B" formatted string, which appears in the header. The `SubTypeName` element in the footer identifies the trace event type as a . > [!IMPORTANT] > The method is not intended to be called by application code. It is intended to be called by a object to emit the trace information for its method. diff --git a/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml b/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml index c9b3b4a178264..54447a89d01fe 100644 --- a/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml +++ b/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml @@ -79,7 +79,7 @@ property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . @@ -138,7 +138,7 @@ foreach (UserPrincipal u in results) property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . @@ -302,7 +302,7 @@ foreach (UserPrincipal u in results) property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . @@ -361,7 +361,7 @@ foreach (UserPrincipal u in results) property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . @@ -418,7 +418,7 @@ foreach (UserPrincipal u in results) property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . diff --git a/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml b/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml index 51eb3a59681bb..93123ec221027 100644 --- a/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml @@ -423,7 +423,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -457,7 +457,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -495,7 +495,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -529,7 +529,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -567,7 +567,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -601,7 +601,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . @@ -668,7 +668,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -702,7 +702,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -740,7 +740,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml b/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml index 077ba94abcfb5..3eaeb5d610342 100644 --- a/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml @@ -219,7 +219,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -253,7 +253,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -371,7 +371,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -405,7 +405,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -439,7 +439,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectoryInterSiteTransport.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectoryInterSiteTransport.xml index bd59a7f550bcc..b63477a5c73e9 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectoryInterSiteTransport.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectoryInterSiteTransport.xml @@ -158,7 +158,7 @@ is `true`, any site link availability schedules that have been configured are ignored, and all site links become always-available for replication. When set to `false`, any previously configured site link availability schedules go back into effect. If no site link availability schedules have been configured, setting this property has no effect. + When the is `true`, any site link availability schedules that have been configured are ignored, and all site links become always-available for replication. When set to `false`, any previously configured site link availability schedules go back into effect. If no site link availability schedules have been configured, setting this property has no effect. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaProperty.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaProperty.xml index 776ce4bc28293..7a41cf80b2a96 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaProperty.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySchemaProperty.xml @@ -43,7 +43,7 @@ method must be called to commit the object that was created to the Active Directory Domain Services. + The method must be called to commit the object that was created to the Active Directory Domain Services. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySite.xml b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySite.xml index 3a76f8131f7de..f6a782c38dea6 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySite.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ActiveDirectorySite.xml @@ -511,7 +511,7 @@ object is writable. After modification, the method should be called. + The object is writable. After modification, the method should be called. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/ApplicationPartition.xml b/xml/System.DirectoryServices.ActiveDirectory/ApplicationPartition.xml index b1cec3dd1b170..bd3f660fed9db 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ApplicationPartition.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ApplicationPartition.xml @@ -127,7 +127,7 @@ property returns the same collection of objects as the method if the object has been committed to the underlying directory services store. + The property returns the same collection of objects as the method if the object has been committed to the underlying directory services store. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/Domain.xml b/xml/System.DirectoryServices.ActiveDirectory/Domain.xml index e5fa63a59b7ab..c15876d6a1ddb 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/Domain.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/Domain.xml @@ -68,7 +68,7 @@ The `trustPassword` parameter associates a password with the created trust. When the other side of the trust is created, the same password is provided and the two local trusts are then bound to each other. - To programmatically create both sides of a trust relationship in a single method call, use the method. + To programmatically create both sides of a trust relationship in a single method call, use the method. ]]> @@ -110,7 +110,7 @@ method is used to create only one side of a trust. + This method creates both sides of a trust relationship with a single method call. The method is used to create only one side of a trust. ]]> @@ -150,7 +150,7 @@ ## Remarks When one side of a trust relationship is deleted, the trust longer exists. - To delete both sides of a trust relationship with one method call, use the method. + To delete both sides of a trust relationship with one method call, use the method. ]]> @@ -188,7 +188,7 @@ method. + To delete only one side of a trust relationship, use the method. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/DomainController.xml b/xml/System.DirectoryServices.ActiveDirectory/DomainController.xml index 16236de143146..38f814d17a50b 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/DomainController.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/DomainController.xml @@ -147,7 +147,7 @@ method is used to demote the domain controller from a global catalog server. + The method is used to demote the domain controller from a global catalog server. ]]> @@ -756,7 +756,7 @@ method should be used instead whenever possible. + This method is a destructive operation because it causes the role to be taken without the cooperation of the server that currently holds the role. The method should be used instead whenever possible. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/Forest.xml b/xml/System.DirectoryServices.ActiveDirectory/Forest.xml index ba176051fce13..34539e9f40d30 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/Forest.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/Forest.xml @@ -74,7 +74,7 @@ The `trustPassword` parameter associates a password with the created trust. When the other side of the trust is created, the same password is provided and the two local trusts are then bound to each other. - To programmatically create both sides of a trust relationship in a single method call, use the method. + To programmatically create both sides of a trust relationship in a single method call, use the method. ]]> @@ -116,7 +116,7 @@ method is used to create only one side of a trust. + This method creates both sides of a trust relationship with a single method call. The method is used to create only one side of a trust. ]]> @@ -156,7 +156,7 @@ ## Remarks When one side of a trust relationship is deleted, the trust is no longer established. - To delete both sides of a trust relationship with one method call, use the method. + To delete both sides of a trust relationship with one method call, use the method. ]]> @@ -194,7 +194,7 @@ method. + To delete only one side of a trust relationship, use the method. ]]> diff --git a/xml/System.DirectoryServices.ActiveDirectory/ReplicationCursor.xml b/xml/System.DirectoryServices.ActiveDirectory/ReplicationCursor.xml index e2f076fde1a89..b0d722110eec4 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ReplicationCursor.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ReplicationCursor.xml @@ -36,7 +36,7 @@ indicates the time when this domain controller last synchronized to changes for this partition on the source directory system agent (DSA). + The indicates the time when this domain controller last synchronized to changes for this partition on the source directory system agent (DSA). ]]> diff --git a/xml/System.DirectoryServices/DirectoryEntry.xml b/xml/System.DirectoryServices/DirectoryEntry.xml index fff9fbe441301..86c5ca888dab7 100644 --- a/xml/System.DirectoryServices/DirectoryEntry.xml +++ b/xml/System.DirectoryServices/DirectoryEntry.xml @@ -38,7 +38,7 @@ The classes associated with the component can be used with any of the Active Directory Domain Services service providers. Some of the current providers are Internet Information Services (IIS), Lightweight Directory Access Protocol (LDAP), Novell NetWare Directory Service (NDS), and WinNT. > [!NOTE] -> It is assumed that you have a general understanding of Active Directory Domain Services before using this class. For more information, see the namespace overview. +> It is assumed that you have a general understanding of Active Directory Domain Services before using this class. For more information, see the namespace overview. ]]> @@ -484,7 +484,7 @@ int main() ## Security -- Use for deleting entries from the Active Directory Domain Services hierarchy. Associated enumeration: . +- Use for deleting entries from the Active Directory Domain Services hierarchy. Associated enumeration: . ]]> @@ -1061,7 +1061,7 @@ Console::WriteLine("The Native GUID of the ADS object: {0}", ## Remarks Use this property to cast the native Active Directory Domain Services object, which implements the IADs interface, when you want to use a COM interface. For more information about the IADs interface, see the topic [IADs](http://msdn.microsoft.com/library/default.asp?url=/library/adsi/adsi/iads.asp) in the MSDN Library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library/default.asp?url=/library/adsi/adsi/iads.asp). - This object is for advanced scenarios that cannot be accomplished with the classes alone. To use it, you need to import one of the COM interfaces from the IADs family, then cast this property to that interface. + This object is for advanced scenarios that cannot be accomplished with the classes alone. To use it, you need to import one of the COM interfaces from the IADs family, then cast this property to that interface. ]]> diff --git a/xml/System.DirectoryServices/DirectorySearcher.xml b/xml/System.DirectoryServices/DirectorySearcher.xml index 63b8460375492..df820d60191a4 100644 --- a/xml/System.DirectoryServices/DirectorySearcher.xml +++ b/xml/System.DirectoryServices/DirectorySearcher.xml @@ -26,7 +26,7 @@ When you create an instance of , you specify the root you want to retrieve, and an optional list of properties to retrieve. The property enables you to set additional properties to do the following tasks: -- Cache the search results on the local computer. Set the property to `true` to store directory information on the local computer. Updates are made to this local cache and committed to Active Directory Domain Services only when the method is called. +- Cache the search results on the local computer. Set the property to `true` to store directory information on the local computer. Updates are made to this local cache and committed to Active Directory Domain Services only when the method is called. - Specify the length of time to search, using the property. @@ -42,7 +42,7 @@ For a list of initial property values for an instance of the class, see the constructor. > [!NOTE] -> It is assumed that you have a general understanding of Active Directory Domain Services before using this class. For more information, see the overview. +> It is assumed that you have a general understanding of Active Directory Domain Services before using this class. For more information, see the overview. ]]> diff --git a/xml/System.DirectoryServices/PropertyCollection.xml b/xml/System.DirectoryServices/PropertyCollection.xml index f027c462c1ffe..e1fc0ec56b66b 100644 --- a/xml/System.DirectoryServices/PropertyCollection.xml +++ b/xml/System.DirectoryServices/PropertyCollection.xml @@ -236,7 +236,7 @@ ## Remarks returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions that result from changes made by other threads. @@ -289,7 +289,7 @@ Dim myCollection As New ICollection() ## Remarks For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's SyncRoot property. - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a Synchronized method on a collection, the expected usage for looks like this: diff --git a/xml/System.DirectoryServices/SchemaNameCollection.xml b/xml/System.DirectoryServices/SchemaNameCollection.xml index ae343ca5b0ba2..41f5838462633 100644 --- a/xml/System.DirectoryServices/SchemaNameCollection.xml +++ b/xml/System.DirectoryServices/SchemaNameCollection.xml @@ -381,7 +381,7 @@ ## Remarks returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -434,7 +434,7 @@ Dim myCollection As New ICollection() ## Remarks For collections with an underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: diff --git a/xml/System.DirectoryServices/SearchResult.xml b/xml/System.DirectoryServices/SearchResult.xml index 2f608504fe437..1ff493b06b7b1 100644 --- a/xml/System.DirectoryServices/SearchResult.xml +++ b/xml/System.DirectoryServices/SearchResult.xml @@ -17,7 +17,7 @@ class are very similar to instances of class. The crucial difference is that the class retrieves its information from the Active Directory Domain Services hierarchy each time a new object is accessed, whereas the data for is already available in the , where it gets returned from a query that is performed with the class. Only those properties that are specified through the collection in your query will be available from . + Instances of the class are very similar to instances of class. The crucial difference is that the class retrieves its information from the Active Directory Domain Services hierarchy each time a new object is accessed, whereas the data for is already available in the , where it gets returned from a query that is performed with the class. Only those properties that are specified through the collection in your query will be available from . @@ -360,7 +360,7 @@ Console::WriteLine("The path for the 'mySearchResult' search result is : {0}\n", . + This collection only contains properties that were explicitly requested through . diff --git a/xml/System.DirectoryServices/SearchResultCollection.xml b/xml/System.DirectoryServices/SearchResultCollection.xml index e37cdafe0eb21..00dc693d7ab5a 100644 --- a/xml/System.DirectoryServices/SearchResultCollection.xml +++ b/xml/System.DirectoryServices/SearchResultCollection.xml @@ -368,7 +368,7 @@ ## Remarks returns an object, which can be used to synchronize access to the . - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -421,7 +421,7 @@ Dim myCollection As New ICollection() ## Remarks For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: diff --git a/xml/System.Drawing.Design/ToolboxItemContainer.xml b/xml/System.Drawing.Design/ToolboxItemContainer.xml index 681af0f751609..7920678f12946 100644 --- a/xml/System.Drawing.Design/ToolboxItemContainer.xml +++ b/xml/System.Drawing.Design/ToolboxItemContainer.xml @@ -22,7 +22,7 @@ ## Remarks is a simple class that encapsulates a for efficiency. By having a single class that is always loaded, you can defer the loading of the until it is needed. Because new classes can be derived from , you could load a that could, in turn, load an assembly that is not already in memory. For a large collection of objects, this could cause a large number of assemblies to be loaded, which decreases performance. Instead, the toolbox service deals only with objects and retrieves their contained only when necessary. - The is designed to hold any cached data from the . The default implementation only holds the filter of the , but deriving classes may choose to cache the name, image, and other information. objects support two forms of serialization: they can be serialized through standard runtime serialization, and they can also load and save themselves from a . The former provides a very easy way to save objects to a persistent storage. The latter provides a way to integrate objects with mixed data storage formats. + The is designed to hold any cached data from the . The default implementation only holds the filter of the , but deriving classes may choose to cache the name, image, and other information. objects support two forms of serialization: they can be serialized through standard runtime serialization, and they can also load and save themselves from a . The former provides a very easy way to save objects to a persistent storage. The latter provides a way to integrate objects with mixed data storage formats. ]]> diff --git a/xml/System.Drawing.Design/ToolboxService.xml b/xml/System.Drawing.Design/ToolboxService.xml index 7c57ea43b754c..25461e961ff39 100644 --- a/xml/System.Drawing.Design/ToolboxService.xml +++ b/xml/System.Drawing.Design/ToolboxService.xml @@ -102,7 +102,7 @@ ## Remarks The method gives you the opportunity to provide a derived version of a . By default, the class does not support linked items, so it returns `null` for link parameters that are not `null`. To provide link support, you should override this method to create a derived that is capable of handling links. - The data object passed in should contain data obtained from a prior call to the property on a toolbox item container. + The data object passed in should contain data obtained from a prior call to the property on a toolbox item container. ]]> diff --git a/xml/System.Drawing.Drawing2D/SmoothingMode.xml b/xml/System.Drawing.Drawing2D/SmoothingMode.xml index 5fde6d86b5382..d5392233516db 100644 --- a/xml/System.Drawing.Drawing2D/SmoothingMode.xml +++ b/xml/System.Drawing.Drawing2D/SmoothingMode.xml @@ -20,10 +20,10 @@ AntiAlias and HighQuality are equivalent and specify rendering with smoothing applied. > [!NOTE] -> When the property is specified by using the enumeration, it does not affect text. To set the text rendering quality, use the property and the enumeration. +> When the property is specified by using the enumeration, it does not affect text. To set the text rendering quality, use the property and the enumeration. > [!NOTE] -> When the property is specified by using the enumeration, it does not affect areas filled by a path gradient brush. Areas filled by using a object are rendered the same way (aliased) regardless of the setting for the property. +> When the property is specified by using the enumeration, it does not affect areas filled by a path gradient brush. Areas filled by using a object are rendered the same way (aliased) regardless of the setting for the property. ]]> diff --git a/xml/System.Drawing.Imaging/ColorPalette.xml b/xml/System.Drawing.Imaging/ColorPalette.xml index b83125eac51e1..9fe9bba48396a 100644 --- a/xml/System.Drawing.Imaging/ColorPalette.xml +++ b/xml/System.Drawing.Imaging/ColorPalette.xml @@ -16,7 +16,7 @@ object directly. If you created a object, you could then manipulate the palette size for a particular image, which is not allowed. Use the property to obtain a object. + You are not allowed to construct a object directly. If you created a object, you could then manipulate the palette size for a particular image, which is not allowed. Use the property to obtain a object. The colors in the palette are limited to 32-bit ARGB colors. A 32-bit ARGB color has 8 bits each for alpha, red, green, and blue values. The lowest 8 bits make up the blue bit, the next 8 bits are green, the next 8 bits are red, and the most significant 8 bits are alpha. This means each component can vary from 0 to 255. Fully on is 255 and fully off is 0. Alpha is used to make the color value transparent (alpha = 0) or opaque (alpha = 255). The number of intensity levels in the image can be increased without increasing the number of colors used. This process creates what is called a halftone, and it offers increased contrast at a cost of decreased resolution. diff --git a/xml/System.Drawing.Imaging/ImageAttributes.xml b/xml/System.Drawing.Imaging/ImageAttributes.xml index df5dd7d13812a..e9361c98f1009 100644 --- a/xml/System.Drawing.Imaging/ImageAttributes.xml +++ b/xml/System.Drawing.Imaging/ImageAttributes.xml @@ -829,7 +829,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - Calling the method is equivalent to calling the method and passing for the `flags` parameter. specifies that all colors (including grays) are adjusted by the color-adjustment matrix, not the grayscale-adjustment matrix. Therefore, the grayscale-adjustment matrix passed to this method has no effect. + Calling the method is equivalent to calling the method and passing for the `flags` parameter. specifies that all colors (including grays) are adjusted by the color-adjustment matrix, not the grayscale-adjustment matrix. Therefore, the grayscale-adjustment matrix passed to this method has no effect. ]]> @@ -933,7 +933,7 @@ The default color-adjustment and grayscale-adjustment settings apply to all categories that do not have adjustment settings of their own. For example, if you never specify any adjustment settings for the pen category, the default settings apply to the pen category. - Calling the method is equivalent to calling the method and passing for the `flags` parameter. specifies that all colors (including grays) are adjusted by the color-adjustment matrix + Calling the method is equivalent to calling the method and passing for the `flags` parameter. specifies that all colors (including grays) are adjusted by the color-adjustment matrix @@ -1586,7 +1586,7 @@ method is equivalent to calling and passing for the `color` parameter. specifies the color of pixels outside of a rendered image. This color is visible if the mode parameter is set to and the source rectangle passed to the method is larger than the image itself. + Calling the method is equivalent to calling and passing for the `color` parameter. specifies the color of pixels outside of a rendered image. This color is visible if the mode parameter is set to and the source rectangle passed to the method is larger than the image itself. diff --git a/xml/System.Drawing.Imaging/PropertyItem.xml b/xml/System.Drawing.Imaging/PropertyItem.xml index bc87bae0c5703..58cafcca164e6 100644 --- a/xml/System.Drawing.Imaging/PropertyItem.xml +++ b/xml/System.Drawing.Imaging/PropertyItem.xml @@ -20,14 +20,14 @@ A is not intended to be used as a stand-alone object. A object is intended to be used by classes that are derived from . A object is used to retrieve and to change the metadata of existing image files, not to create the metadata. Therefore, the class does not have a defined `Public` constructor, and you cannot create an instance of a object. - To work around the absence of a `Public` constructor, use an existing object instead of creating a new instance of the class. For more information, see . + To work around the absence of a `Public` constructor, use an existing object instead of creating a new instance of the class. For more information, see . ## Examples - The following code example demonstrates how to read and display the metadata in an image file using the class and the property. + The following code example demonstrates how to read and display the metadata in an image file using the class and the property. - This example is designed to be used in a Windows Form that imports the namespace. Paste the code into the form and change the path to `fakePhoto.jpg` to point to an image file on your system. Call the `ExtractMetaData` method when handling the form's event, passing `e` as . + This example is designed to be used in a Windows Form that imports the namespace. Paste the code into the form and change the path to `fakePhoto.jpg` to point to an image file on your system. Call the `ExtractMetaData` method when handling the form's event, passing `e` as . [!code-cpp[System.Drawing.ImageExample#6](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp#6)] [!code-csharp[System.Drawing.ImageExample#6](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Drawing.ImageExample/CS/form1.cs#6)] diff --git a/xml/System.Drawing.Printing/Margins.xml b/xml/System.Drawing.Printing/Margins.xml index f567585780665..9e22954e0ad6c 100644 --- a/xml/System.Drawing.Printing/Margins.xml +++ b/xml/System.Drawing.Printing/Margins.xml @@ -269,7 +269,7 @@ to indicate the , , , and properties of both margins have the same value; otherwise, . - ]]> + ]]> @@ -296,7 +296,7 @@ to indicate if the , , , or properties of both margins are not equal; otherwise, . - ]]> + ]]> diff --git a/xml/System.Drawing.Printing/PageSettings.xml b/xml/System.Drawing.Printing/PageSettings.xml index 2eddf3dab1454..cb58ace626091 100644 --- a/xml/System.Drawing.Printing/PageSettings.xml +++ b/xml/System.Drawing.Printing/PageSettings.xml @@ -20,7 +20,7 @@ class is used to specify settings that modify the way a page will be printed. Typically, you set default settings for all pages to be printed through the property. To specify settings on a page-by-page basis, handle the or event and modify the argument included in the or , respectively. + The class is used to specify settings that modify the way a page will be printed. Typically, you set default settings for all pages to be printed through the property. To specify settings on a page-by-page basis, handle the or event and modify the argument included in the or , respectively. For more information about handling events, see the class overview. For more information about printing, see the namespace overview. @@ -54,7 +54,7 @@ ## Remarks The default constructor initializes all fields to their default values. - Typically, you do not create an instance of , but instead use the to set settings for all pages. + Typically, you do not create an instance of , but instead use the to set settings for all pages. ]]> @@ -150,7 +150,7 @@ property to determine if the printer supports color printing. If the printer supports color, but you do not want to print in color, set the property to `false`. The default will be `true`. + You can use the property to determine if the printer supports color printing. If the printer supports color, but you do not want to print in color, set the property to `false`. The default will be `true`. @@ -274,12 +274,12 @@ property to determine the angle, in degrees, that the portrait orientation is rotated to produce the landscape orientation. + You can use the property to determine the angle, in degrees, that the portrait orientation is rotated to produce the landscape orientation. ## Examples - The following code example sets a document's default page orientation to landscape through the property, and prints the document. The example has three prerequisites: + The following code example sets a document's default page orientation to landscape through the property, and prints the document. The example has three prerequisites: - A variable named `filePath` has been set to the path of the file to print. @@ -317,7 +317,7 @@ event, you can use this property along with the property to calculate the printing area for the page. + When handling the event, you can use this property along with the property to calculate the printing area for the page. @@ -360,9 +360,9 @@ represents the size of the paper through the property, which contains one of the values. + A represents the size of the paper through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. For information about how you can specify a custom paper size, see the constructor. @@ -408,9 +408,9 @@ represents the source of the paper through the property, which contains one of the values. + A represents the source of the paper through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. @@ -481,9 +481,9 @@ represents the printer resolution of through the property, which contains one of the values. + A represents the printer resolution of through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. diff --git a/xml/System.Drawing.Printing/PaperSize.xml b/xml/System.Drawing.Printing/PaperSize.xml index 73008eea1589b..ecc7659913291 100644 --- a/xml/System.Drawing.Printing/PaperSize.xml +++ b/xml/System.Drawing.Printing/PaperSize.xml @@ -16,7 +16,7 @@ and properties to get the paper sizes that are available on the printer and to set the paper size for a page, respectively. + This class is used by the and properties to get the paper sizes that are available on the printer and to set the paper size for a page, respectively. You can use the constructor to specify a custom paper size. The and property values can be set only for custom objects. @@ -50,8 +50,8 @@ |Property|Initial value| |--------------|-------------------| -||| -||| +||| +||| ]]> diff --git a/xml/System.Drawing.Printing/PaperSource.xml b/xml/System.Drawing.Printing/PaperSource.xml index 7529f98d7fda0..e86918bd66e4a 100644 --- a/xml/System.Drawing.Printing/PaperSource.xml +++ b/xml/System.Drawing.Printing/PaperSource.xml @@ -16,7 +16,7 @@ and properties to get the paper source trays that are available on the printer and to set the paper source for a page, respectively. + This class is used by and properties to get the paper source trays that are available on the printer and to set the paper source for a page, respectively. For more information about printing, see the namespace overview. @@ -53,8 +53,8 @@ |Property|Initial value| |--------------|-------------------| -||| -||| +||| +||| ]]> diff --git a/xml/System.Drawing.Printing/PaperSourceKind.xml b/xml/System.Drawing.Printing/PaperSourceKind.xml index d43377dc22e0b..e26dac73cd07e 100644 --- a/xml/System.Drawing.Printing/PaperSourceKind.xml +++ b/xml/System.Drawing.Printing/PaperSourceKind.xml @@ -15,7 +15,7 @@ property. + This enumeration is used by the property. For more information on printing, see the namespace overview. diff --git a/xml/System.Drawing.Printing/PrintAction.xml b/xml/System.Drawing.Printing/PrintAction.xml index b97348ade4a14..0f19cdf4506d3 100644 --- a/xml/System.Drawing.Printing/PrintAction.xml +++ b/xml/System.Drawing.Printing/PrintAction.xml @@ -18,7 +18,7 @@ The is used by the type to indicate what type of event is occurring. > [!NOTE] -> The does not reliably indicate the type of print operation occurring, and returns PrintToFile in all cases. +> The does not reliably indicate the type of print operation occurring, and returns PrintToFile in all cases. ]]> diff --git a/xml/System.Drawing.Printing/PrintController.xml b/xml/System.Drawing.Printing/PrintController.xml index 7872e09ec5b43..c131e2dea2c5e 100644 --- a/xml/System.Drawing.Printing/PrintController.xml +++ b/xml/System.Drawing.Printing/PrintController.xml @@ -16,7 +16,7 @@ controls how a is printed. invokes the print controller's , , , and methods, which in turn tell the printer how to print the document. Print preview uses a specialized . For an example of a print controller that is specialized for print preview, see the . + When implemented in a derived class, controls how a is printed. invokes the print controller's , , , and methods, which in turn tell the printer how to print the document. Print preview uses a specialized . For an example of a print controller that is specialized for print preview, see the . is used by , and not typically used directly. diff --git a/xml/System.Drawing.Printing/PrintDocument.xml b/xml/System.Drawing.Printing/PrintDocument.xml index 0ae8318574a07..7017533b3df9c 100644 --- a/xml/System.Drawing.Printing/PrintDocument.xml +++ b/xml/System.Drawing.Printing/PrintDocument.xml @@ -135,7 +135,7 @@ property. For example, the property specifies whether the page prints in color, the property specifies landscape or portrait orientation, and the property specifies the margins of the page. + You can specify several default page settings through the property. For example, the property specifies whether the page prints in color, the property specifies landscape or portrait orientation, and the property specifies the margins of the page. To specify settings on a page-by-page basis, handle the or event and modify the argument included in the or , respectively. @@ -218,7 +218,7 @@ ## Remarks Typically, you handle the event to release fonts, file streams, and other resources used during the printing process, like fonts. - You indicate that there are no more pages to print by setting the property to `false` in the event. The event also occurs if the printing process is canceled or an exception occurs during the printing process. + You indicate that there are no more pages to print by setting the property to `false` in the event. The event also occurs if the printing process is canceled or an exception occurs during the printing process. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs. For more information about handling events with delegates, see [Events](http://msdn.microsoft.com/library/b6f65241-e0ad-4590-a99f-200ce741bb1f). @@ -383,9 +383,9 @@ object origin. When is `true`, the object location takes into account the property value and the printable area of the page. When is `false`, only the printable area of the page is used to determine the location of the object origin, the value is ignored. + Calculating the area available to print requires knowing the physical size of the paper, the margins for the page, and the location of the object origin. When is `true`, the object location takes into account the property value and the printable area of the page. When is `false`, only the printable area of the page is used to determine the location of the object origin, the value is ignored. - For example, if is `true`, and is set for 1 inch on each side, the object included in the is located 1 inch from the left and top of the page. If the printable area of the page is .25 of an inch on each side and is `false`, the object is located .25 of an inch from the left and top of the page. + For example, if is `true`, and is set for 1 inch on each side, the object included in the is located 1 inch from the left and top of the page. If the printable area of the page is .25 of an inch on each side and is `false`, the object is located .25 of an inch from the left and top of the page. > [!NOTE] > The printable area of a page varies from printer to printer and is not guaranteed to be symmetrical. @@ -415,7 +415,7 @@ ## Remarks Specify the output to print by handling the event and by using the included in the . - Use the property to specify which printer should print the document. + Use the property to specify which printer should print the document. The method prints the document without using a print dialog. Use a when you want to offer the user the ability to choose print settings. @@ -514,7 +514,7 @@ property. For example, use the property to specify the number of copies you want to print, the property to specify the printer to use, and the property to specify the range of pages you want to print. + You can specify several printer settings through the property. For example, use the property to specify the number of copies you want to print, the property to specify the printer to use, and the property to specify the range of pages you want to print. @@ -549,9 +549,9 @@ property of the . For example, to specify a line of text that should be printed, draw the text using the method. + To specify the output to print, use the property of the . For example, to specify a line of text that should be printed, draw the text using the method. - In addition to specifying the output, you can indicate if there are additional pages to print by setting the property to `true`. The default is `false`, which indicates that there are no more pages to print. Individual page settings can also be modified through the and the print job can be canceled by setting the property to `true`. To print each page of a document using different page settings, handle the event. + In addition to specifying the output, you can indicate if there are additional pages to print by setting the property to `true`. The default is `false`, which indicates that there are no more pages to print. Individual page settings can also be modified through the and the print job can be canceled by setting the property to `true`. To print each page of a document using different page settings, handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs. For more information about handling events with delegates, see [Events](http://msdn.microsoft.com/library/b6f65241-e0ad-4590-a99f-200ce741bb1f). @@ -590,7 +590,7 @@ property or by setting the property to a . Changes made to the affect only the current page, not the document's default page settings. The print job can also be canceled by setting the property to `true` for the . + It is possible to print each page of a document using different page settings. You set page settings by modifying individual properties of the property or by setting the property to a . Changes made to the affect only the current page, not the document's default page settings. The print job can also be canceled by setting the property to `true` for the . To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs. For more information about handling events with delegates, see [Events](http://msdn.microsoft.com/library/b6f65241-e0ad-4590-a99f-200ce741bb1f). diff --git a/xml/System.Drawing.Printing/PrinterResolution.xml b/xml/System.Drawing.Printing/PrinterResolution.xml index 32649a21ab594..8e6f5afd41ac2 100644 --- a/xml/System.Drawing.Printing/PrinterResolution.xml +++ b/xml/System.Drawing.Printing/PrinterResolution.xml @@ -16,7 +16,7 @@ and properties to get the printer resolutions that are available on the printer and to set the printing resolution for a page, respectively. + This class is used by the and properties to get the printer resolutions that are available on the printer and to set the printing resolution for a page, respectively. Use the property to determine whether the printer resolution type is the value . If so, use the and properties to determine the printer resolution in the horizontal and vertical directions, respectively. diff --git a/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml index 597c6c0f87992..90d8e3f09eab5 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml @@ -20,9 +20,9 @@ contains instances that represents the paper sizes through the property, which contains one of the values. + The contains instances that represents the paper sizes through the property, which contains one of the values. - Typically, you set a page's paper size through the property to a valid instance available through the collection. + Typically, you set a page's paper size through the property to a valid instance available through the collection. See the constructor to find out how you can specify a custom paper size. diff --git a/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml index d2a19016d760e..e7764ef45fced 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml @@ -20,9 +20,9 @@ contains instances that represents the paper source trays through the property, which contains one of the values. + The contains instances that represents the paper source trays through the property, which contains one of the values. - Typically, you set a page's paper source through the property to a valid instance available through the collection. + Typically, you set a page's paper source through the property to a valid instance available through the collection. diff --git a/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml index a413110514fe2..9545e0230c6f6 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml @@ -20,9 +20,9 @@ contains instances that represents the printer resolutions supported through the property, which contains one of the values. + The contains instances that represents the printer resolutions supported through the property, which contains one of the values. - Typically, you set the printer's resolution through the property to a valid instance available through the collection. + Typically, you set the printer's resolution through the property to a valid instance available through the collection. If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. diff --git a/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml index 58fa39ab4f847..2abd8a1ddeffa 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml @@ -20,7 +20,7 @@ property, which indicates the names of printers installed on a computer, is a . + The property, which indicates the names of printers installed on a computer, is a . ]]> diff --git a/xml/System.Drawing.Printing/PrinterSettings.xml b/xml/System.Drawing.Printing/PrinterSettings.xml index 462c1e9f81464..255e7dbd34ff8 100644 --- a/xml/System.Drawing.Printing/PrinterSettings.xml +++ b/xml/System.Drawing.Printing/PrinterSettings.xml @@ -20,7 +20,7 @@ through or properties to modify printer settings. The most common printer setting is , which specifies the printer to print to. + Typically, you access a through or properties to modify printer settings. The most common printer setting is , which specifies the printer to print to. For more information about printing with Windows Forms, see the namespace overview. If you wish to print from a Windows Presentation Foundation application, see the namespace. @@ -63,7 +63,7 @@ ## Remarks The default constructor initializes all fields to their default values. - Typically, you do not create an instance of , but instead use the to set settings for the printer. + Typically, you do not create an instance of , but instead use the to set settings for the printer. ]]> @@ -359,11 +359,11 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the requires the and to be specified and the value to be within that range. + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the requires the and to be specified and the value to be within that range. - During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. + During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. - The , and can also be set programmatically, though the implementation is the same. + The , and can also be set programmatically, though the implementation is the same. ]]> @@ -664,7 +664,7 @@ property to `true` to print a page in landscape format. + Valid rotation values are 90 and 270 degrees. If landscape is not supported, the only valid rotation value is 0 degrees. You set the property to `true` to print a page in landscape format. ]]> @@ -714,7 +714,7 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . ]]> @@ -740,7 +740,7 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . ]]> @@ -766,9 +766,9 @@ contains instances that represent the paper sizes through the property, which contains one of the values. + The contains instances that represent the paper sizes through the property, which contains one of the values. - Typically, you set a page's paper size through the property to a valid available through the collection. + Typically, you set a page's paper size through the property to a valid available through the collection. To specify a custom paper size, see the constructor. @@ -804,9 +804,9 @@ contains instances that represent the paper source trays through the property, which contains one of the values. + The contains instances that represent the paper source trays through the property, which contains one of the values. - Typically, you set a page's paper source through the property to a valid available through the collection. + Typically, you set a page's paper source through the property to a valid available through the collection. @@ -885,9 +885,9 @@ contains instances that represent the printer resolutions supported through the property, which contains one of the values. + The contains instances that represent the printer resolutions supported through the property, which contains one of the values. - Typically, you set a page's paper source through the property to a valid available through the collection. + Typically, you set a page's paper source through the property to a valid available through the collection. If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. @@ -942,11 +942,11 @@ property is used by the .when the user selects a print range. The default is `AllPages`. To enable the user to specify a range of pages to print, the property must be set to `true`. To enable the user to specify the selected pages to print, the property must be set to `true`. + The property is used by the .when the user selects a print range. The default is `AllPages`. To enable the user to specify a range of pages to print, the property must be set to `true`. To enable the user to specify the selected pages to print, the property must be set to `true`. - During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. + During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. - The , and can also be set programmatically, though the implementation is the same. + The , and can also be set programmatically, though the implementation is the same. ]]> @@ -973,10 +973,10 @@ property is used by the when the user selects the **Print to file** option. In such a case, the output port is set to "FILE," causing the Windows printing subsystem to prompt the user for a file name when the method is called. + The property is used by the when the user selects the **Print to file** option. In such a case, the output port is set to "FILE," causing the Windows printing subsystem to prompt the user for a file name when the method is called. > [!NOTE] -> The property is only used by the and cannot be set programmatically. The `Print to file` option only appears on the when the property is set to `true`. +> The property is only used by the and cannot be set programmatically. The `Print to file` option only appears on the when the property is set to `true`. ]]> @@ -1055,7 +1055,7 @@ to `true`. + To print using color, and if the printer supports it, set to `true`. @@ -1091,11 +1091,11 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the also requires the and to be specified and the value to be within that range. + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the also requires the and to be specified and the value to be within that range. - During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. + During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. - The , and can also be set programmatically, though the implementation is the same. + The , and can also be set programmatically, though the implementation is the same. ]]> diff --git a/xml/System.Drawing/Bitmap.xml b/xml/System.Drawing/Bitmap.xml index 00738b327287a..115f9ad4d119d 100644 --- a/xml/System.Drawing/Bitmap.xml +++ b/xml/System.Drawing/Bitmap.xml @@ -87,7 +87,7 @@ ## Remarks You must keep the stream open for the lifetime of the . - Due to a limitation of the [!INCLUDE[ndptecgdiplus](~/includes/ndptecgdiplus-md.md)] decoder, an is thrown if you construct a bitmap from a .png image file with a single dimension greater than 65,535 pixels. + Due to a limitation of the [!INCLUDE[ndptecgdiplus](~/includes/ndptecgdiplus-md.md)] decoder, an is thrown if you construct a bitmap from a .png image file with a single dimension greater than 65,535 pixels. @@ -209,7 +209,7 @@ ## Remarks You must keep the stream open for the lifetime of the . - Due to a limitation of the [!INCLUDE[ndptecgdiplus](~/includes/ndptecgdiplus-md.md)] decoder, an is thrown if you construct a bitmap from a .png image file with a single dimension greater than 65,535 pixels. + Due to a limitation of the [!INCLUDE[ndptecgdiplus](~/includes/ndptecgdiplus-md.md)] decoder, an is thrown if you construct a bitmap from a .png image file with a single dimension greater than 65,535 pixels. ]]> @@ -574,7 +574,7 @@ requires security permission to call unmanaged code. For a managed alternative for creating a bitmap from an embedded resource, see . works only with bitmaps that are named resources in a DLL. + requires security permission to call unmanaged code. For a managed alternative for creating a bitmap from an embedded resource, see . works only with bitmaps that are named resources in a DLL. ]]> @@ -708,7 +708,7 @@ - Gets an icon handle for the . -- Sets the attribute of the form to an icon created from the handle. +- Sets the attribute of the form to an icon created from the handle. [!code-cpp[System.Drawing.ClassicBitmapExamples#6](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicBitmapExamples/CPP/form1.cpp#6)] [!code-csharp[System.Drawing.ClassicBitmapExamples#6](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Drawing.ClassicBitmapExamples/CS/form1.cs#6)] @@ -793,7 +793,7 @@ The specifies the attributes of the , such as size, pixel format, the starting address of the pixel data in memory, and length of each scan line (stride). - When calling this method, you should use a member of the enumeration that contains a specific bits-per-pixel (BPP) value. Using values such as and will throw an . Also, passing the incorrect pixel format for a bitmap will throw an . + When calling this method, you should use a member of the enumeration that contains a specific bits-per-pixel (BPP) value. Using values such as and will throw an . Also, passing the incorrect pixel format for a bitmap will throw an . @@ -845,9 +845,9 @@ ## Remarks Use the method to lock an existing bitmap in system memory so that it can be changed programmatically. You can change the color of an image with the method, although the method offers better performance for large-scale changes. - When calling this method, you should use a member of the enumeration that contains a specific bits-per-pixel (BPP) value. Using values, such as and , will throw an . Also, passing the incorrect pixel format for a bitmap will throw an . + When calling this method, you should use a member of the enumeration that contains a specific bits-per-pixel (BPP) value. Using values, such as and , will throw an . Also, passing the incorrect pixel format for a bitmap will throw an . - This version of the method is intended to be used with a `flags` value of . + This version of the method is intended to be used with a `flags` value of . ]]> diff --git a/xml/System.Drawing/BufferedGraphics.xml b/xml/System.Drawing/BufferedGraphics.xml index e3524adbec795..e20edefb91d81 100644 --- a/xml/System.Drawing/BufferedGraphics.xml +++ b/xml/System.Drawing/BufferedGraphics.xml @@ -27,7 +27,7 @@ > [!NOTE] > The simplest way to use double buffering is to set the control style flag on a control using the method. Setting the flag for a control redirects all painting for the control through a default graphics buffer, without requiring any additional code. This flag is set to `true` by default. - The class has no public constructor and must be created by the for an application domain using its method. You can retrieve the for the current application domain from the static property. + The class has no public constructor and must be created by the for an application domain using its method. You can retrieve the for the current application domain from the static property. The property can be used for drawing to the graphics buffer. This property provides access to the object that draws to the graphics buffer allocated for this object. diff --git a/xml/System.Drawing/BufferedGraphicsContext.xml b/xml/System.Drawing/BufferedGraphicsContext.xml index 07f9c07ee2f14..77313fbd71861 100644 --- a/xml/System.Drawing/BufferedGraphicsContext.xml +++ b/xml/System.Drawing/BufferedGraphicsContext.xml @@ -27,7 +27,7 @@ The class provides methods for creating and configuring a graphics buffer. The method creates a , which is a wrapper for a graphics buffer that also provides methods you can use to write to the buffer and render its contents to an output device. - You can retrieve the for the current application domain from the static property. For graphically intensive applications such as animation, you can create a dedicated using the constructor, but for most applications the property will be sufficient. + You can retrieve the for the current application domain from the static property. For graphically intensive applications such as animation, you can create a dedicated using the constructor, but for most applications the property will be sufficient. For more information on drawing buffered graphics and custom buffering implementations, see [Double Buffered Graphics](~/docs/framework/winforms/advanced/double-buffered-graphics.md) and [How to: Manually Manage Buffered Graphics](~/docs/framework/winforms/advanced/how-to-manually-manage-buffered-graphics.md). diff --git a/xml/System.Drawing/BufferedGraphicsManager.xml b/xml/System.Drawing/BufferedGraphicsManager.xml index 7e7991092949c..906bbf33a02db 100644 --- a/xml/System.Drawing/BufferedGraphicsManager.xml +++ b/xml/System.Drawing/BufferedGraphicsManager.xml @@ -20,7 +20,7 @@ This class has one static property, , which returns the main for the current application domain. The class creates instances that can be used to draw buffered graphics. - The class has no public constructor and must be created by the object for an application domain using its method. You can retrieve the object for the current application domain from the static property. + The class has no public constructor and must be created by the object for an application domain using its method. You can retrieve the object for the current application domain from the static property. For more information on double buffering, see [Double Buffered Graphics](~/docs/framework/winforms/advanced/double-buffered-graphics.md), , and . diff --git a/xml/System.Drawing/CharacterRange.xml b/xml/System.Drawing/CharacterRange.xml index 48a8fb3e0ff20..c2001b186e762 100644 --- a/xml/System.Drawing/CharacterRange.xml +++ b/xml/System.Drawing/CharacterRange.xml @@ -178,7 +178,7 @@ ## Remarks You can also test for equality using the method. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example demonstrates how to use the operator. To run this example, paste it into a Windows Form. Handle the form’s event and call the `CharacterRangeEquality1` method from the event-handling method, passing `e` as . @@ -218,7 +218,7 @@ ## Remarks The method returns the opposite of the method. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example demonstrates how to use the method. To run this example, paste it into a Windows Form. Handle the form’s event and call the `CharacterRangeInequality` method from the event-handling method, passing `e` as . diff --git a/xml/System.Drawing/ContentAlignment.xml b/xml/System.Drawing/ContentAlignment.xml index cac90c6f9fdbb..a3fc3593146a5 100644 --- a/xml/System.Drawing/ContentAlignment.xml +++ b/xml/System.Drawing/ContentAlignment.xml @@ -20,7 +20,7 @@ and constructors and the enumeration. To run this example paste this code into a Windows Form that contains a label named `Label1` and call the `IntializeLabel1` method in the form's constructor. + The following code example demonstrates how to use the and constructors and the enumeration. To run this example paste this code into a Windows Form that contains a label named `Label1` and call the `IntializeLabel1` method in the form's constructor. [!code-cpp[System.Drawing.PointsAndSizes#7](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp#7)] [!code-csharp[System.Drawing.PointsAndSizes#7](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CS/form1.cs#7)] diff --git a/xml/System.Drawing/Font.xml b/xml/System.Drawing/Font.xml index 90615bbbbed11..f55eec7756c64 100644 --- a/xml/System.Drawing/Font.xml +++ b/xml/System.Drawing/Font.xml @@ -138,7 +138,7 @@ property set to and its property set to . Windows Forms applications support TrueType fonts and have limited support for OpenType fonts. If the `familyName` parameter specifies a font that is not installed on the machine running the application or is not supported, Microsoft Sans Serif will be substituted. + The resulting font has its property set to and its property set to . Windows Forms applications support TrueType fonts and have limited support for OpenType fonts. If the `familyName` parameter specifies a font that is not installed on the machine running the application or is not supported, Microsoft Sans Serif will be substituted. @@ -219,7 +219,7 @@ property set to . + The resulting font has its property set to . ]]> @@ -283,7 +283,7 @@ property set to . + The resulting font has its property set to . ]]> @@ -972,7 +972,7 @@ ## Remarks The line spacing of a is the vertical distance between the base lines of two consecutive lines of text. Thus, the line spacing includes the blank space between lines along with the height of the character itself. - If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. For a screen display that has a vertical resolution of 96 dots per inch, you can calculate the height as follows: + If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. For a screen display that has a vertical resolution of 96 dots per inch, you can calculate the height as follows: 2355*(0.3/2048)\*96 = 33.11719 @@ -1005,11 +1005,11 @@ ## Remarks The line spacing of a is the vertical distance between the base lines of two consecutive lines of text. Thus, the line spacing includes the blank space between lines along with the height of the character itself. - If the property of the font is set to anything other than , the height, in pixels, is calculated using the vertical resolution of the specified object. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. If the object has a property value of and a property value of 96 dots per inch, the height is calculated as follows: + If the property of the font is set to anything other than , the height, in pixels, is calculated using the vertical resolution of the specified object. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. If the object has a property value of and a property value of 96 dots per inch, the height is calculated as follows: 2355*(0.3/2048)\*96 = 33.1171875 - Continuing with the same example, suppose the property of the object is set to rather than . Then (using 1 inch = 25.4 millimeters) the height, in millimeters, is calculated as follows: + Continuing with the same example, suppose the property of the object is set to rather than . Then (using 1 inch = 25.4 millimeters) the height, in millimeters, is calculated as follows: 2355*(0.3/2048)25.4 = 8.762256 @@ -1059,7 +1059,7 @@ property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. If the specified vertical resolution is 96 dots per inch, the height is calculated as follows: + If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. If the specified vertical resolution is 96 dots per inch, the height is calculated as follows: 2355*(0.3/2048)\*96 = 33.1171875 @@ -1093,7 +1093,7 @@ ## Remarks The line spacing is the vertical distance between the base lines of two consecutive lines of text. Thus, the line spacing includes the blank space between lines along with the height of the character itself. - If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. For a screen display that has a vertical resolution of 96 dots per inch, you can calculate the height as follows: + If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. For a screen display that has a vertical resolution of 96 dots per inch, you can calculate the height as follows: 2355*(0.3/2048)\*96 = 33.11719 diff --git a/xml/System.Drawing/FontConverter.xml b/xml/System.Drawing/FontConverter.xml index 65d7f197b96f5..d83a8211da37a 100644 --- a/xml/System.Drawing/FontConverter.xml +++ b/xml/System.Drawing/FontConverter.xml @@ -47,7 +47,7 @@ object through the method. + You should access a object through the method. ]]> diff --git a/xml/System.Drawing/Graphics.xml b/xml/System.Drawing/Graphics.xml index e8522eb281610..d9bc3d13bda56 100644 --- a/xml/System.Drawing/Graphics.xml +++ b/xml/System.Drawing/Graphics.xml @@ -25,7 +25,7 @@ ## Remarks The class provides methods for drawing objects to the display device. A is associated with a specific device context. - You can obtain a object by calling the method on an object that inherits from , or by handling a control's event and accessing the property of the class. You can also create a object from an image by using the method. For more information about creating a object, see [How to: Create Graphics Objects for Drawing](~/docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md). + You can obtain a object by calling the method on an object that inherits from , or by handling a control's event and accessing the property of the class. You can also create a object from an image by using the method. For more information about creating a object, see [How to: Create Graphics Objects for Drawing](~/docs/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing.md). You can draw many different shapes and lines by using a object. For more information about how to draw lines and shapes, see the specific `Draw`*GraphicalElement* method for the line or shape you want to draw. These methods include , , , , and . For more information about how to draw lines and shapes, see [Using a Pen to Draw Lines and Shapes](~/docs/framework/winforms/advanced/using-a-pen-to-draw-lines-and-shapes.md) and [Using a Brush to Fill Shapes](~/docs/framework/winforms/advanced/using-a-brush-to-fill-shapes.md). diff --git a/xml/System.Drawing/Icon.xml b/xml/System.Drawing/Icon.xml index d8fe772b87f1b..5da04554156dd 100644 --- a/xml/System.Drawing/Icon.xml +++ b/xml/System.Drawing/Icon.xml @@ -477,7 +477,7 @@ - Gets an icon handle for the . -- Sets the attribute of the form to an icon created from the handle. +- Sets the attribute of the form to an icon created from the handle. - Calls the Win32 API function `DestroyIcon` to release resources. diff --git a/xml/System.Drawing/Image.xml b/xml/System.Drawing/Image.xml index fecba4d1d5af2..b3bd833903c02 100644 --- a/xml/System.Drawing/Image.xml +++ b/xml/System.Drawing/Image.xml @@ -1056,9 +1056,9 @@ ## Examples - The following code example demonstrates how to read and display the metadata in an image file using the class and the property. + The following code example demonstrates how to read and display the metadata in an image file using the class and the property. - This example is designed to be used a Windows Form that imports the namespace. Paste the code into the form and change the path to `fakePhoto.jpg` to point to an image file on your system. Call the `ExtractMetaData` method when handling the form's event, passing `e` as . + This example is designed to be used a Windows Form that imports the namespace. Paste the code into the form and change the path to `fakePhoto.jpg` to point to an image file on your system. Call the `ExtractMetaData` method when handling the form's event, passing `e` as . [!code-cpp[System.Drawing.ImageExample#6](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp#6)] [!code-csharp[System.Drawing.ImageExample#6](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Drawing.ImageExample/CS/form1.cs#6)] diff --git a/xml/System.Drawing/ImageFormatConverter.xml b/xml/System.Drawing/ImageFormatConverter.xml index 31d85747a7d9a..ec60317f79ca0 100644 --- a/xml/System.Drawing/ImageFormatConverter.xml +++ b/xml/System.Drawing/ImageFormatConverter.xml @@ -22,7 +22,7 @@ The converts to and from known image formats, as specified in the class. > [!NOTE] -> If you want to convert between image formats, such as converting between BMP and JPEG, use one of the methods that takes an object as a parameter. +> If you want to convert between image formats, such as converting between BMP and JPEG, use one of the methods that takes an object as a parameter. ]]> diff --git a/xml/System.Drawing/Point.xml b/xml/System.Drawing/Point.xml index d9e12190cb2c9..5fd29392d7f22 100644 --- a/xml/System.Drawing/Point.xml +++ b/xml/System.Drawing/Point.xml @@ -114,7 +114,7 @@ ## Examples - The following code example demonstrates how to use the and constructors and the enumeration. To run this example, paste this code into a Windows Form that contains a label named `Label1`, and call the `IntializeLabel1` method in the form's constructor. + The following code example demonstrates how to use the and constructors and the enumeration. To run this example, paste this code into a Windows Form that contains a label named `Label1`, and call the `IntializeLabel1` method in the form's constructor. [!code-cpp[System.Drawing.PointsAndSizes#7](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp#7)] [!code-csharp[System.Drawing.PointsAndSizes#7](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CS/form1.cs#7)] diff --git a/xml/System.Drawing/PointF.xml b/xml/System.Drawing/PointF.xml index afb4bcf270bec..b47809455679b 100644 --- a/xml/System.Drawing/PointF.xml +++ b/xml/System.Drawing/PointF.xml @@ -26,7 +26,7 @@ to a , use or . + To convert a to a , use or . ]]> @@ -365,7 +365,7 @@ ## Remarks The operator adds the of the specified size to the x-coordinate of the and the to the y-coordinate of the . - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `opAdditionExample`, passing `e` as . @@ -534,7 +534,7 @@ ## Remarks The operator subtracts the of the specified size from the x-coordinate of the and the from the y-coordinate of the . - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following code example demonstrates how to use the operator. To run this example, paste the following code into a Windows Form. Handle the form's event and call `opSubtractionExample`, passing `e` as . diff --git a/xml/System.Drawing/Region.xml b/xml/System.Drawing/Region.xml index 1cbfeb0c4d873..02d9a5f3052d5 100644 --- a/xml/System.Drawing/Region.xml +++ b/xml/System.Drawing/Region.xml @@ -24,7 +24,7 @@ An application can also use regions in hit-testing operations, such as checking whether a point or a rectangle intersects a region. For more information on using regions for hit-testing, see [How to: Use Hit Testing with a Region](~/docs/framework/winforms/advanced/how-to-use-hit-testing-with-a-region.md). - An application can fill a region by using the method and a object. + An application can fill a region by using the method and a object. @@ -775,7 +775,7 @@ and methods. + For code examples, see the and methods. ]]> diff --git a/xml/System.Drawing/Size.xml b/xml/System.Drawing/Size.xml index ae817e7541305..288af9e03ab3b 100644 --- a/xml/System.Drawing/Size.xml +++ b/xml/System.Drawing/Size.xml @@ -89,7 +89,7 @@ and constructors and the enumeration. To run this example, paste this code into a Windows Form that contains a label named `Label1` and call the `IntializeLabel1` method in the form's constructor. + The following code example demonstrates how to use the and constructors and the enumeration. To run this example, paste this code into a Windows Form that contains a label named `Label1` and call the `IntializeLabel1` method in the form's constructor. [!code-cpp[System.Drawing.PointsAndSizes#7](~/samples/snippets/cpp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CPP/form1.cpp#7)] [!code-csharp[System.Drawing.PointsAndSizes#7](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Drawing.PointsAndSizes/CS/form1.cs#7)] diff --git a/xml/System.Drawing/SizeF.xml b/xml/System.Drawing/SizeF.xml index 269c876048d1b..3db18cd310700 100644 --- a/xml/System.Drawing/SizeF.xml +++ b/xml/System.Drawing/SizeF.xml @@ -35,7 +35,7 @@ - -- +- - @@ -137,7 +137,7 @@ - -- +- - @@ -390,7 +390,7 @@ - -- +- - diff --git a/xml/System.Drawing/StringFormat.xml b/xml/System.Drawing/StringFormat.xml index 19c8a8eb8d268..77bffa17075e7 100644 --- a/xml/System.Drawing/StringFormat.xml +++ b/xml/System.Drawing/StringFormat.xml @@ -561,7 +561,7 @@ . + Setting more than 32 character ranges is not allowed and will cause an . diff --git a/xml/System.Drawing/SystemColors.xml b/xml/System.Drawing/SystemColors.xml index 7af75639f2b07..81acc44242558 100644 --- a/xml/System.Drawing/SystemColors.xml +++ b/xml/System.Drawing/SystemColors.xml @@ -16,7 +16,7 @@ or classes rather than creating a new pen or brush based on a value from . For example, if you wanted to get a brush for the face color of a 3-D element, use the property because it gets a brush that already exists, whereas calling the constructor with a parameter value of will create a new brush. + Better performance is achieved by using the properties of the or classes rather than creating a new pen or brush based on a value from . For example, if you wanted to get a brush for the face color of a 3-D element, use the property because it gets a brush that already exists, whereas calling the constructor with a parameter value of will create a new brush. diff --git a/xml/System.EnterpriseServices.Internal/AppDomainHelper.xml b/xml/System.EnterpriseServices.Internal/AppDomainHelper.xml index 1c670d143dc04..8c68dfa6d98c5 100644 --- a/xml/System.EnterpriseServices.Internal/AppDomainHelper.xml +++ b/xml/System.EnterpriseServices.Internal/AppDomainHelper.xml @@ -61,9 +61,9 @@ . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. - For more information about and , see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). + For more information about and , see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). ]]> diff --git a/xml/System.EnterpriseServices.Internal/ComManagedImportUtil.xml b/xml/System.EnterpriseServices.Internal/ComManagedImportUtil.xml index cf61c039cf0e6..7d23dd64ba5d6 100644 --- a/xml/System.EnterpriseServices.Internal/ComManagedImportUtil.xml +++ b/xml/System.EnterpriseServices.Internal/ComManagedImportUtil.xml @@ -117,7 +117,7 @@ calls , which performs the following steps: + calls , which performs the following steps: 1. Registration of the assembly. diff --git a/xml/System.EnterpriseServices/IServiceCall.xml b/xml/System.EnterpriseServices/IServiceCall.xml index fa8e4a7cf235b..82748635e3c32 100644 --- a/xml/System.EnterpriseServices/IServiceCall.xml +++ b/xml/System.EnterpriseServices/IServiceCall.xml @@ -46,7 +46,7 @@ . The batch work in this method is run by a call to either or . + The batch work that is run in this method runs in the context and thread apartment of the activity created by the call to . The batch work in this method is run by a call to either or . > [!CAUTION] > You must ensure that this method is thread safe in situations where the activity object created by is not created with a synchronized context, because in such situations many calls to can run at the same time. diff --git a/xml/System.EnterpriseServices/MustRunInClientContextAttribute.xml b/xml/System.EnterpriseServices/MustRunInClientContextAttribute.xml index 2e9a34534d2df..b399a1c726612 100644 --- a/xml/System.EnterpriseServices/MustRunInClientContextAttribute.xml +++ b/xml/System.EnterpriseServices/MustRunInClientContextAttribute.xml @@ -24,7 +24,7 @@ is thrown when an attempt is made to create the object. + If the context attributes of the attributed object conflict with those of the context of the creator, a is thrown when an attempt is made to create the object. For more information about using attributes, see [Attributes](~/docs/standard/attributes/index.md). diff --git a/xml/System.Globalization/Calendar.xml b/xml/System.Globalization/Calendar.xml index e0906d42dc070..432e9f0d09f7b 100644 --- a/xml/System.Globalization/Calendar.xml +++ b/xml/System.Globalization/Calendar.xml @@ -183,7 +183,7 @@ The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#1)] [!code-vb[System.Globalization.Calendar.AddMethods#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#1)] @@ -247,7 +247,7 @@ The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#2)] [!code-vb[System.Globalization.Calendar.AddMethods#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#2)] @@ -311,7 +311,7 @@ The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#3)] [!code-vb[System.Globalization.Calendar.AddMethods#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#3)] @@ -375,7 +375,7 @@ The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#4)] [!code-vb[System.Globalization.Calendar.AddMethods#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#4)] @@ -443,7 +443,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -507,7 +507,7 @@ The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#6)] [!code-vb[System.Globalization.Calendar.AddMethods#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#6)] @@ -573,7 +573,7 @@ In all .NET Framework classes derived from the class, a week is defined as seven days. - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#7)] [!code-vb[System.Globalization.Calendar.AddMethods#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#7)] @@ -641,7 +641,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] @@ -855,7 +855,7 @@ ## Examples - The following code example displays the values contained in . + The following code example displays the values contained in . [!code-cpp[System.Globalization.JapaneseCalendar.Eras#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.Eras/CPP/yslin_japanesecalendar_eras.cpp#1)] [!code-csharp[System.Globalization.JapaneseCalendar.Eras#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.JapaneseCalendar.Eras/CS/yslin_japanesecalendar_eras.cs#1)] @@ -1783,11 +1783,11 @@ ## Remarks This method can be used to determine the number of weeks in the year by setting `time` to the last day of the year. - The object for a particular culture that uses the calendar indicated by the property includes the following culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters: + The object for a particular culture that uses the calendar indicated by the property includes the following culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters: -- The property contains the default first day of the week that can be used for the `firstDayOfWeek` parameter. +- The property contains the default first day of the week that can be used for the `firstDayOfWeek` parameter. -- The property contains the default calendar week rule that can be used for the `rule` parameter. +- The property contains the default calendar week rule that can be used for the `rule` parameter. The following example uses the current culture's object to determine that January 1, 2011 is in the first week of the year in the Gregorian calendar. diff --git a/xml/System.Globalization/CalendarAlgorithmType.xml b/xml/System.Globalization/CalendarAlgorithmType.xml index b1d7a524643bc..ad99cc6f5d256 100644 --- a/xml/System.Globalization/CalendarAlgorithmType.xml +++ b/xml/System.Globalization/CalendarAlgorithmType.xml @@ -31,7 +31,7 @@ ## Remarks A date calculation for a particular calendar depends on whether the calendar is solar-based, lunar-based, or lunisolar-based. For example, the , , and classes are solar-based, the and classes are lunar-based,.and the and classes are lunisolar-based, thus using solar calculations for the year and lunar calculations for the month and day. - A value, which is returned by a calendar member such as the property, specifies the foundation for a particular calendar. + A value, which is returned by a calendar member such as the property, specifies the foundation for a particular calendar. diff --git a/xml/System.Globalization/CalendarWeekRule.xml b/xml/System.Globalization/CalendarWeekRule.xml index b0992a9414683..8898b8ce56016 100644 --- a/xml/System.Globalization/CalendarWeekRule.xml +++ b/xml/System.Globalization/CalendarWeekRule.xml @@ -34,9 +34,9 @@ enumeration is returned by the property and is used by the culture's current calendar to determine the calendar week rule. The enumeration value is also used as a parameter to the method. + A member of the enumeration is returned by the property and is used by the culture's current calendar to determine the calendar week rule. The enumeration value is also used as a parameter to the method. - Calendar week rules depend on the value that indicates the first day of the week in addition to depending on a value. The property provides the default value for a culture, but any value can be specified as the first day of the week in the method. + Calendar week rules depend on the value that indicates the first day of the week in addition to depending on a value. The property provides the default value for a culture, but any value can be specified as the first day of the week in the method. The first week based on the FirstDay value can have one to seven days. The first week based on the FirstFullWeek value always has seven days. The first week based on the FirstFourDayWeek value can have four to seven days. @@ -73,7 +73,7 @@ |Jan 8 Fri|Week 2|Week 1|Week 1| |Jan 9 Sat|Week 2|Week 1|Week 1| - The following example illustrates how the and values are used together to determine how weeks are assigned. In the Gregorian calendar, the first day of the year (January 1) in 2013 falls on a Tuesday. If the designated first day of the week is Sunday, the first Sunday (January 6) is the first day of the first week of the year, and Saturday (January 5) belongs to the fifty-third week of the previous year. Changing the calendar week rule to FirstFourDayWeek defines Tuesday (January 1) as the beginning of the first week of the year, because there are more than four days between Tuesday, January 1, and Sunday, January 6. Using this rule, January 5 belongs to the first week of the year. For 2010, a year in which January 1 falls on a Friday, applying the FirstFourDayWeek rule with as the first day of the week makes Sunday, January 3 the beginning of the first week of the year, because the first week in 2010 that has more than four days is January 3 through 9. + The following example illustrates how the and values are used together to determine how weeks are assigned. In the Gregorian calendar, the first day of the year (January 1) in 2013 falls on a Tuesday. If the designated first day of the week is Sunday, the first Sunday (January 6) is the first day of the first week of the year, and Saturday (January 5) belongs to the fifty-third week of the previous year. Changing the calendar week rule to FirstFourDayWeek defines Tuesday (January 1) as the beginning of the first week of the year, because there are more than four days between Tuesday, January 1, and Sunday, January 6. Using this rule, January 5 belongs to the first week of the year. For 2010, a year in which January 1 falls on a Friday, applying the FirstFourDayWeek rule with as the first day of the week makes Sunday, January 3 the beginning of the first week of the year, because the first week in 2010 that has more than four days is January 3 through 9. [!code-csharp[System.Globalization.CalendarWeekRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendarweekrule/cs/calendarweekruleex.cs#1)] [!code-vb[System.Globalization.CalendarWeekRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendarweekrule/vb/calendarweekruleex.vb#1)] @@ -81,7 +81,7 @@ > [!NOTE] > This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .Net](http://go.microsoft.com/fwlink/?LinkId=160851). - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> diff --git a/xml/System.Globalization/CharUnicodeInfo.xml b/xml/System.Globalization/CharUnicodeInfo.xml index d256235b44b8f..443d077d44280 100644 --- a/xml/System.Globalization/CharUnicodeInfo.xml +++ b/xml/System.Globalization/CharUnicodeInfo.xml @@ -40,13 +40,13 @@ - Digit value. Applies to numeric characters that can be combined with other numeric characters to represent a whole number in a numbering system. -- Decimal digit value. Applies only to characters that represent decimal digits in the decimal (base 10) system. A decimal digit can be one of ten digits, from zero through nine. These characters are members of the category. +- Decimal digit value. Applies only to characters that represent decimal digits in the decimal (base 10) system. A decimal digit can be one of ten digits, from zero through nine. These characters are members of the category. In addition, the class is used internally by a number of other .NET Framework types and methods that rely on character classification. These include: - The class, which works with textual elements instead of single characters in a string. -- The overloads of the method, which determine the category to which a character or surrogate pair belongs. +- The overloads of the method, which determine the category to which a character or surrogate pair belongs. - The [character classes](~/docs/standard/base-types/character-classes-in-regular-expressions.md) recognized by , the .NET Framework's regular expression engine. @@ -499,12 +499,12 @@ ## Remarks The Unicode characters are divided into categories. A character's category is one of its properties. For example, a character might be an uppercase letter, a lowercase letter, a decimal digit number, a letter number, a connector punctuation, a math symbol, or a currency symbol. The class returns the category of a Unicode character. For more information on Unicode characters, see the [Unicode Standard](http://go.microsoft.com/fwlink/?linkid=37123). - The method assumes that `ch` corresponds to a single linguistic character and returns its category. This means that, for surrogate pairs, it returns instead of the category to which the surrogate belongs. For example, the Ugaritic alphabet occupies code points U+10380 to U+1039F. The following example uses the method to instantiate a string that represents UGARITIC LETTER ALPA (U+10380), which is the first letter of the Ugaritic alphabet. As the output from the example shows, the method returns `false` if it is passed either the high surrogate or the low surrogate of this character. + The method assumes that `ch` corresponds to a single linguistic character and returns its category. This means that, for surrogate pairs, it returns instead of the category to which the surrogate belongs. For example, the Ugaritic alphabet occupies code points U+10380 to U+1039F. The following example uses the method to instantiate a string that represents UGARITIC LETTER ALPA (U+10380), which is the first letter of the Ugaritic alphabet. As the output from the example shows, the method returns `false` if it is passed either the high surrogate or the low surrogate of this character. [!code-csharp[System.Globalization.CharUnicodeInfo.GetUnicodeCategory#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getunicodecategory/cs/getunicodecategory1.cs#1)] [!code-vb[System.Globalization.CharUnicodeInfo.GetUnicodeCategory#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getunicodecategory/vb/getunicodecategory1.vb#1)] - Note that does not always return the same value as the method when passed a particular character as a parameter. The method is designed to reflect the current version of the Unicode standard. In contrast, although the method usually reflects the current version of the Unicode standard, it might return a character's category based on a previous version of the standard, or it might return a category that differs from the current standard to preserve backward compatibility. + Note that does not always return the same value as the method when passed a particular character as a parameter. The method is designed to reflect the current version of the Unicode standard. In contrast, although the method usually reflects the current version of the Unicode standard, it might return a character's category based on a previous version of the standard, or it might return a category that differs from the current standard to preserve backward compatibility. @@ -560,12 +560,12 @@ ## Remarks The Unicode characters are divided into categories. A character's category is one of its properties. For example, a character might be an uppercase letter, a lowercase letter, a decimal digit number, a letter number, a connector punctuation, a math symbol, or a currency symbol. The class returns the category of a Unicode character. For more information on Unicode characters, see the [Unicode Standard](http://go.microsoft.com/fwlink/?linkid=37123). - If the object at position `index` is the first character of a valid surrogate pair, the method returns the Unicode category of the surrogate pair instead of returning . For example, the Ugaritic alphabet occupies code points U+10380 to U+1039F. The following example uses the method to instantiate a string that represents UGARITIC LETTER ALPA (U+10380), which is the first letter of the Ugaritic alphabet. As the output from the example shows, the method returns if it is passed the high surrogate of this character, which indicates that it considers the surrogate pair. However, if it is passed the low surrogate, it considers only the low surrogate in isolation and returns . + If the object at position `index` is the first character of a valid surrogate pair, the method returns the Unicode category of the surrogate pair instead of returning . For example, the Ugaritic alphabet occupies code points U+10380 to U+1039F. The following example uses the method to instantiate a string that represents UGARITIC LETTER ALPA (U+10380), which is the first letter of the Ugaritic alphabet. As the output from the example shows, the method returns if it is passed the high surrogate of this character, which indicates that it considers the surrogate pair. However, if it is passed the low surrogate, it considers only the low surrogate in isolation and returns . [!code-csharp[System.Globalization.CharUnicodeInfo.GetUnicodeCategory#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getunicodecategory/cs/getunicodecategory1.cs#2)] [!code-vb[System.Globalization.CharUnicodeInfo.GetUnicodeCategory#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.charunicodeinfo.getunicodecategory/vb/getunicodecategory1.vb#2)] - Note that method does not always return the same value as the method when passed a particular character as a parameter. The method is designed to reflect the current version of the Unicode standard. In contrast, although the method usually reflects the current version of the Unicode standard, it might return a character's category based on a previous version of the standard, or it might return a category that differs from the current standard to preserve backward compatibility. + Note that method does not always return the same value as the method when passed a particular character as a parameter. The method is designed to reflect the current version of the Unicode standard. In contrast, although the method usually reflects the current version of the Unicode standard, it might return a character's category based on a previous version of the standard, or it might return a category that differs from the current standard to preserve backward compatibility. diff --git a/xml/System.Globalization/ChineseLunisolarCalendar.xml b/xml/System.Globalization/ChineseLunisolarCalendar.xml index 4a42e2389b3e4..5d80f00a778e8 100644 --- a/xml/System.Globalization/ChineseLunisolarCalendar.xml +++ b/xml/System.Globalization/ChineseLunisolarCalendar.xml @@ -38,7 +38,7 @@ Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Chinese lunisolar calendar. - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> diff --git a/xml/System.Globalization/CompareInfo.xml b/xml/System.Globalization/CompareInfo.xml index 33b15a056ad69..96a67bed9c6f3 100644 --- a/xml/System.Globalization/CompareInfo.xml +++ b/xml/System.Globalization/CompareInfo.xml @@ -41,18 +41,18 @@ ## Remarks Conventions for comparing and sorting data vary from culture to culture. For example, sort order may be based on phonetics or on the visual representation of characters. In East Asian languages, characters are sorted by the stroke and radical of ideographs. Sorting also depends on the order languages and cultures use for the alphabet. For example, the Danish language has an "Æ" character that it sorts after "Z" in the alphabet. In addition, comparisons may be case-sensitive or case-insensitive, and casing rules may also differ by culture. The class is responsible for maintaining this culture-sensitive string comparison data and for performing culture-sensitive string operations. - Typically, you do not have to instantiate a object directly, because one is used implicitly by all non-ordinal string comparison operations, including calls to the method. However, if you do want to retrieve a object, you can do it in one of these ways: + Typically, you do not have to instantiate a object directly, because one is used implicitly by all non-ordinal string comparison operations, including calls to the method. However, if you do want to retrieve a object, you can do it in one of these ways: -- By retrieving the value of the property for a particular culture. +- By retrieving the value of the property for a particular culture. - By calling the static method with a culture name. This allows for late-bound access to a object. ## Ignored search values Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. Comparison methods such as and do not consider such characters when they perform a culture-sensitive comparison. Ignorable characters include: -- . Culture-sensitive comparison methods will always find an empty string at the beginning (index zero) of the string being searched. +- . Culture-sensitive comparison methods will always find an empty string at the beginning (index zero) of the string being searched. -- A character or string consisting of characters with code points that are not considered in the operation because of comparison options, In particular, the and options produce searches in which symbols and nonspacing combining characters are ignored. +- A character or string consisting of characters with code points that are not considered in the operation because of comparison options, In particular, the and options produce searches in which symbols and nonspacing combining characters are ignored. - A string with code points that have no linguistic significance. For example, a soft hyphen (U+00AD) is always ignored in a culture-sensitive string comparison. @@ -132,7 +132,7 @@ . If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. + By default, the comparison is performed by using . If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. > [!NOTE] > When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -719,7 +719,7 @@ ## Remarks Two objects are equal if their and properties are equal. - This method overrides . + This method overrides . If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. @@ -870,7 +870,7 @@ > [!NOTE] > The behavior of this method is unpredictable. It is recommended for your application to use a version of this method that does not take an assembly input. - The `assembly` parameter must be of the same type as . + The `assembly` parameter must be of the same type as . ]]> @@ -918,7 +918,7 @@ > [!NOTE] > The behavior of this method is unpredictable. We recommend that you use a version of this method that does not take an assembly input. - The `assembly` parameter must be of the same type as . + The `assembly` parameter must be of the same type as . ]]> @@ -970,7 +970,7 @@ . + This method overrides . This method generates the same hash code for two objects that are equal according to the method. @@ -1152,10 +1152,10 @@ ## Remarks This method searches the source string from the beginning of the string to the end of the string. - This overload performs a culture-sensitive search. If `value` represents a precomposed Unicode character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode code points are the same, you should call an overload that has a parameter of type and use the value. Unlike , which performs a culture-sensitive comparison, overloads of the method that search for a character perform an ordinal comparison and overloads that search for a string perform a culture-sensitive comparison. + This overload performs a culture-sensitive search. If `value` represents a precomposed Unicode character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode code points are the same, you should call an overload that has a parameter of type and use the value. Unlike , which performs a culture-sensitive comparison, overloads of the method that search for a character perform an ordinal comparison and overloads that search for a string perform a culture-sensitive comparison. > [!NOTE] -> When possible, you should use string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should use string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1222,7 +1222,7 @@ This overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where the Unicode values are compared, you should use one of the overloads that has a parameter of type and use the value. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1292,12 +1292,12 @@ ## Remarks The source string is searched forward starting at the beginning of the string and ending at the end of the string. - The value is not valid for this method. + The value is not valid for this method. - If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should use string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should use string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1360,10 +1360,10 @@ ## Remarks The source string is searched forward starting at `startIndex` and ending at the end of the string. - This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1431,12 +1431,12 @@ ## Remarks The source string is searched forward starting at the beginning of the string and ending at the end of the string. - The value is not valid for this method. + The value is not valid for this method. If `options` does not include the value, this overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search, where the Unicode values are compared. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1506,7 +1506,7 @@ This overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where the Unicode values are compared, you should call one of the overloads that has a parameter of type and use the value. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1582,12 +1582,12 @@ ## Remarks The source string is searched forward starting at `startIndex` and ending at the end of the string. - The value is not valid for this method. + The value is not valid for this method. - If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1659,10 +1659,10 @@ ## Remarks The source string is searched forward starting at `startIndex` and ending at `startIndex` + `count` - 1. - This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1740,12 +1740,12 @@ ## Remarks The source string is searched forward starting at `startIndex` and ending at the end of the string. - The value is not valid for this method. + The value is not valid for this method. If `options` does not include the value, this overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search, where the Unicode values are compared. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1826,7 +1826,7 @@ This overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where the Unicode values are compared, you should call one of the overloads that has a parameter of type and use the value. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -1917,12 +1917,12 @@ ## Remarks The source string is searched forward starting at `startIndex` and ending at `startIndex` + `count` - 1. - The value is not valid for this method. + The value is not valid for this method. - If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2009,12 +2009,12 @@ ## Remarks The source string is searched forward starting at `startIndex` and ending at `startIndex` + `count` - 1. - The value is not valid for this method. + The value is not valid for this method. If `options` does not include the value, this overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search, where the Unicode values are compared. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2098,7 +2098,7 @@ Every string starts and ends with an empty substring (""); therefore, if `prefix` is an empty string, this method returns `true`. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2168,10 +2168,10 @@ ## Remarks Every string starts and ends with an empty substring (""); therefore, if `prefix` is an empty string, this method returns `true`. - The value is not valid for this method. + The value is not valid for this method. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2330,7 +2330,7 @@ Every string starts and ends with an empty substring (""); therefore, if `suffix` is an empty string, this method returns `true`. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2400,10 +2400,10 @@ ## Remarks Every string starts and ends with an empty substring (""); therefore, if `suffix` is an empty string, this method returns `true`. - The value is not valid for this method. + The value is not valid for this method. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2467,10 +2467,10 @@ ## Remarks The source string is searched backward starting at the end of the string and ending at the beginning of the string. - This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2534,10 +2534,10 @@ ## Remarks The source string is searched backward starting at the end of the string and ending at the beginning of the string. - This overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where the Unicode values are compared, you should call one of the overloads that has a parameter of type and use the value. + This overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where the Unicode values are compared, you should call one of the overloads that has a parameter of type and use the value. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2607,12 +2607,12 @@ ## Remarks The source string is searched backward starting at the end of the string and ending at the beginning of the string. - The value is not valid for this method. + The value is not valid for this method. - If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2675,10 +2675,10 @@ ## Remarks The source string is searched backward starting at `startIndex` and ending at the beginning of the string. - This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2746,12 +2746,12 @@ ## Remarks The source string is searched backward starting at the end of the string and ending at the beginning of the string. - The value is not valid for this method. + The value is not valid for this method. If `options` does not include the value, this overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search, where the Unicode values are compared. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2818,10 +2818,10 @@ ## Remarks The source string is searched backward starting at `startIndex` and ending at the beginning of the string. - This overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where the Unicode values are compared, you should call one of the overloads that has a parameter of type and use the value. + This overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where the Unicode values are compared, you should call one of the overloads that has a parameter of type and use the value. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2895,12 +2895,12 @@ ## Remarks The source string is searched backward starting at `startIndex` and ending at the beginning of the string. - The value is not valid for this method. + The value is not valid for this method. - If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -2972,10 +2972,10 @@ ## Remarks The source string is searched backward starting at `startIndex` and ending at `startIndex` - `count` + 1. - This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + This overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if the Unicode values are the same, you should call one of the overloads that has a parameter of type and use the value. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -3053,12 +3053,12 @@ ## Remarks The source string is searched backward starting at `startIndex` and ending at the beginning of the string. - The value is not valid for this method. + The value is not valid for this method. If `options` does not include the value, this overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search, where the Unicode values are compared. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -3139,7 +3139,7 @@ This overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. To perform an ordinal (culture-insensitive) search, where the Unicode values are compared, you should call one of the overloads that has a parameter of type and use the value. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons . +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons . @@ -3230,12 +3230,12 @@ ## Remarks The source string is searched backward starting at `startIndex` and ending at `startIndex` - `count` + 1. - The value is not valid for this method. + The value is not valid for this method. - If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. + If `options` does not include the value, this overload performs a culture-sensitive search. If the character is a Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), it might be considered equivalent to any occurrence of its components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search. A character is considered equivalent to another character only if the Unicode values are the same. Overloads of that search for a character perform an ordinal search, whereas those that search for a string perform a culture-sensitive search. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -3322,12 +3322,12 @@ ## Remarks The source string is searched backward starting at `startIndex` and ending at `startIndex` - `count` + 1. - The value is not valid for this method. + The value is not valid for this method. If `options` does not include the value, this overload performs a culture-sensitive search. A Unicode value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. If `options` includes the value, this overload performs an ordinal (culture-insensitive) search, where the Unicode values are compared. > [!NOTE] -> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. +> When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -3443,7 +3443,7 @@ and properties can have different values. For example, an property value of hexadecimal 0x10407 identifies an alternate sort culture that sorts names as they might appear in a German telephone book. The property has a value of "de-de_phoneb", whereas the property of the associated German (Germany) culture has a value of "de-DE". + The and properties can have different values. For example, an property value of hexadecimal 0x10407 identifies an alternate sort culture that sorts names as they might appear in a German telephone book. The property has a value of "de-de_phoneb", whereas the property of the associated German (Germany) culture has a value of "de-DE". @@ -3529,7 +3529,7 @@ method. It returns a string that consists of the class name and the value of the instance property, separated by a hyphen. + This method overrides the method. It returns a string that consists of the class name and the value of the instance property, separated by a hyphen. ]]> diff --git a/xml/System.Globalization/CompareOptions.xml b/xml/System.Globalization/CompareOptions.xml index 0487786e5a291..d863072dd6fea 100644 --- a/xml/System.Globalization/CompareOptions.xml +++ b/xml/System.Globalization/CompareOptions.xml @@ -41,7 +41,7 @@ The .NET Framework uses three distinct ways of sorting: word sort, string sort, and ordinal sort. Word sort performs a culture-sensitive comparison of strings. Certain nonalphanumeric characters might have special weights assigned to them. For example, the hyphen ("-") might have a very small weight assigned to it so that "coop" and "co-op" appear next to each other in a sorted list. String sort is similar to word sort, except that there are no special cases. Therefore, all nonalphanumeric symbols come before all alphanumeric characters. Ordinal sort compares strings based on the Unicode values of each element of the string. - The StringSort value can only be used with and . is thrown if the StringSort value is used with , , , or . + The StringSort value can only be used with and . is thrown if the StringSort value is used with , , , or . > [!NOTE] > When possible, the application should use string comparison methods that accept a value to specify the kind of comparison expected. As a general rule, user-facing comparisons are best served by the use of linguistic options (using the current culture), while security comparisons should specify Ordinal or OrdinalIgnoreCase. diff --git a/xml/System.Globalization/CultureAndRegionInfoBuilder.xml b/xml/System.Globalization/CultureAndRegionInfoBuilder.xml index 78ce96b2ab106..5761866ed96a6 100644 --- a/xml/System.Globalization/CultureAndRegionInfoBuilder.xml +++ b/xml/System.Globalization/CultureAndRegionInfoBuilder.xml @@ -30,15 +30,15 @@ A custom culture can be registered on a computer only by a user who has administrative rights on that computer. Consequently, apps typically do not create and install custom cultures. Instead, you can use the class to create a special-purpose tool that an administrator can use to create, install, and register a custom culture. After the custom culture is registered on a computer, you can use the class in your app to create instances of the custom culture just as you would for a predefined culture. - If you parse date and time strings generated for a custom culture, you should use the or method instead of the or method to improve the probability that the parse operation will succeed. A date and time string for a custom culture can be complicated and therefore difficult to parse. The and methods try to parse a string with several implicit parse patterns, all of which might fail. The method, in contrast, requires the application to explicitly designate one or more exact parse patterns that are likely to succeed. + If you parse date and time strings generated for a custom culture, you should use the or method instead of the or method to improve the probability that the parse operation will succeed. A date and time string for a custom culture can be complicated and therefore difficult to parse. The and methods try to parse a string with several implicit parse patterns, all of which might fail. The method, in contrast, requires the application to explicitly designate one or more exact parse patterns that are likely to succeed. ## Defining and Creating a Custom Culture You use the class to define and name a custom culture. The custom culture can be an entirely new culture, a new culture that is based on an existing culture (that is, a supplemental culture), or a culture that replaces an existing .NET Framework culture. In each case, the basic steps are the same: -1. Instantiate a object by calling its constructor. To replace an existing culture, pass that culture's name and the enumeration value to the constructor. To create a new culture or a supplemental culture, pass a unique culture name and either the or enumeration value. +1. Instantiate a object by calling its constructor. To replace an existing culture, pass that culture's name and the enumeration value to the constructor. To create a new culture or a supplemental culture, pass a unique culture name and either the or enumeration value. > [!NOTE] - > If you use the enumeration value to instantiate a object, the object's properties are automatically populated with values from the object to be replaced. + > If you use the enumeration value to instantiate a object, the object's properties are automatically populated with values from the object to be replaced. 2. If you are creating a new or supplemental culture: @@ -69,13 +69,13 @@ ## Instantiating a Custom Culture You can create an instance of the custom culture in one of the following ways: -- By invoking the constructor with the culture name. +- By invoking the constructor with the culture name. -- By calling the method with the culture name. +- By calling the method with the culture name. -- By calling the method with the culture name. +- By calling the method with the culture name. - In addition, the array of objects that is returned by the method includes the custom culture. + In addition, the array of objects that is returned by the method includes the custom culture. @@ -246,7 +246,7 @@ property corresponds to the property. + The property corresponds to the property. The and objects that are assigned to the and properties both support culture-sensitive and case-sensitive string comparison. The object also has methods that include a parameter that supports culture-sensitive, case-insensitive comparison. These two properties should be assigned and objects that represent the same locale. @@ -756,7 +756,7 @@ property corresponds to the property. + The property corresponds to the property. For replacement cultures the culture identifier is mapped to the corresponding National Language Support (NLS) locale identifier. For user-defined custom cultures, the value of this property is always hexadecimal 0x1000. @@ -986,7 +986,7 @@ method stores a custom culture as a file on the local computer, in the Globalization subdirectory of the directory returned by the Win32 [GetWindowsDirectory](http://go.microsoft.com/fwlink/?LinkId=191561) function. This process is called registering the custom culture. After the custom culture is registered, a new custom culture can be created by specifying the culture name in a constructor or when calling the method. + The method stores a custom culture as a file on the local computer, in the Globalization subdirectory of the directory returned by the Win32 [GetWindowsDirectory](http://go.microsoft.com/fwlink/?LinkId=191561) function. This process is called registering the custom culture. After the custom culture is registered, a new custom culture can be created by specifying the culture name in a constructor or when calling the method. The custom culture can be removed by calling the method. @@ -1075,7 +1075,7 @@ property provides culture-specific casing information for strings. It corresponds to the property. + The property provides culture-specific casing information for strings. It corresponds to the property. The and objects that are assigned to the and properties both support culture-sensitive and case-sensitive string comparison. The object also has methods that include a parameter that supports culture-sensitive, case-insensitive comparison. These two properties should be assigned and objects that represent the same locale. diff --git a/xml/System.Globalization/CultureAndRegionModifiers.xml b/xml/System.Globalization/CultureAndRegionModifiers.xml index a87f89e9fe927..0da55e391b851 100644 --- a/xml/System.Globalization/CultureAndRegionModifiers.xml +++ b/xml/System.Globalization/CultureAndRegionModifiers.xml @@ -20,7 +20,7 @@ values as an argument to the constructor. You use the resulting object to create a custom culture. + Specify a bitwise combination of one or more values as an argument to the constructor. You use the resulting object to create a custom culture. A custom culture can have a combination of these characteristics: diff --git a/xml/System.Globalization/CultureInfo.xml b/xml/System.Globalization/CultureInfo.xml index 9a76f999b0224..59127702792c6 100644 --- a/xml/System.Globalization/CultureInfo.xml +++ b/xml/System.Globalization/CultureInfo.xml @@ -82,17 +82,17 @@ A culture identifier is a standard international numeric abbreviation and has the components necessary to uniquely identify one of the installed cultures. Your application can use predefined culture identifiers or define custom identifiers. - Certain predefined culture names and identifiers are used by this and other classes in the namespace. Detailed culture information appears in the [National Language Support (NLS) API Reference](http://go.microsoft.com/fwlink/?LinkId=200048) at the Go Global Developer Center. + Certain predefined culture names and identifiers are used by this and other classes in the namespace. Detailed culture information appears in the [National Language Support (NLS) API Reference](http://go.microsoft.com/fwlink/?LinkId=200048) at the Go Global Developer Center. Remember that the culture names and identifiers represent only a subset of cultures that can be found on a particular computer. Windows versions or service packs can change the available cultures. Applications add custom cultures using the class. Users add their own custom cultures using the Microsoft Locale Builder tool. Microsoft Locale Builder is written in managed code using the `CultureAndRegionInfoBuilder` class. Several distinct names are closely associated with a culture, notably the names associated with the following class members: -- +- -- +- -- +- ## Invariant, neutral, and specific cultures @@ -112,7 +112,7 @@ A or a can be created only for the invariant culture or for specific cultures, not for neutral cultures. - If is the but the is not set to zh-TW, then , , and return an empty string (""). + If is the but the is not set to zh-TW, then , , and return an empty string (""). ## Custom cultures @@ -125,7 +125,7 @@ - Standard cultures with user overrides. The user can use the **Region and Language** application in **Control Panel** to customize an existing culture's property values. > [!NOTE] -> You can use the class to define, save, and register custom cultures that either supplement or replace existing cultures. The method creates a Locale Data Markup Language (LDML) file that can be used to install a custom culture on target systems. For step-by step information on using the class to create a new or replacement culture, see the class topic. +> You can use the class to define, save, and register custom cultures that either supplement or replace existing cultures. The method creates a Locale Data Markup Language (LDML) file that can be used to install a custom culture on target systems. For step-by step information on using the class to create a new or replacement culture, see the class topic. Because the .NET Framework supports custom cultures, you should consider the following when working with culture-specific data: @@ -135,7 +135,7 @@ - Remember that custom cultures override default values. Therefore, you cannot consider culture data to be stable. Country names, number and date formats, and spellings may change in the future. If you want to serialize culture-sensitive data such as date and time strings to be passed to the date and time parsing functions, you should use the invariant culture or a specific . - The property value of custom cultures installed on a system includes the flag, and custom cultures are assigned an property value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096). Note that, starting with Windows 10, this value is also assigned to system-defined cultures that lack complete cultural data. + The property value of custom cultures installed on a system includes the flag, and custom cultures are assigned an property value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096). Note that, starting with Windows 10, this value is also assigned to system-defined cultures that lack complete cultural data. ## Dynamic culture data @@ -151,12 +151,12 @@ > [!NOTE] > For information on how the current and current UI culture is determined on a per-thread basis, see the [Culture and threads](#Threads) section. For information on how the current and current UI culture is determined on threads executing in a new application domain, and on threads that cross application domain boundaries, see the [Culture and application domains](#AppDomain) section. For information on how the current and current is determined on threads performing task-based asynchronous operations, see the [Culture and task-based asynchronous operations](#Async) section. - For more detailed information on the current culture, see the property topic. For more detailed information on the current UI culture, see the property topic. + For more detailed information on the current culture, see the property topic. For more detailed information on the current UI culture, see the property topic. ### Retrieving the current and current UI cultures You can get a object that represents the current culture in either of two ways: -- By retrieving the value of the property. +- By retrieving the value of the property. - By retrieving the value of the [Thread.CurrentThread.CurrentCulture]() property. @@ -167,7 +167,7 @@ You can get a object that represents the current UI culture in either of two ways: -- By retrieving the value of the property. +- By retrieving the value of the property. - By retrieving the value of the [Thread.CurrentThread.CurrentUICulture]() property. @@ -181,7 +181,7 @@ 1. Instantiate a object that represents that culture by calling a class constructor and passing it the name of the culture. The constructor instantiates a object that reflects user overrides if the new culture is the same as the current Windows culture. The constructor allows you to specify whether the newly instantiated object reflects user overrides if the new culture is the same as the current Windows culture. -2. Assign the object to the or property. In addition, for apps running on the version 4.6 or later of the desktop .NET Framework, you can also assign the object to the or property. +2. Assign the object to the or property. In addition, for apps running on the version 4.6 or later of the desktop .NET Framework, you can also assign the object to the or property. The following example retrieves the current culture. If it is anything other than the French (France) culture, it changes the current culture to French (France). Otherwise, it changes the current culture to French (Luxembourg). @@ -197,7 +197,7 @@ ## Getting all cultures You can retrieve an array specific categories of cultures or of all the cultures available on the local computer by calling the method. For example, you can retrieve custom cultures, specific cultures, or neutral cultures either alone or in combination. - The following example calls the method twice, first with the enumeration member to retrieve all custom cultures, and then with the enumeration member to retrieve all replacement cultures. + The following example calls the method twice, first with the enumeration member to retrieve all custom cultures, and then with the enumeration member to retrieve all replacement cultures. [!code-csharp[System.Globalization.CultureInfo#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.Globalization.CultureInfo/cs/GetCultures1.cs#5)] [!code-vb[System.Globalization.CultureInfo#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.Globalization.CultureInfo/vb/GetCultures1.vb#5)] @@ -209,12 +209,12 @@ [!code-csharp[System.Globalization.CultureInfo.Class.Thread#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureinfo.class.thread/cs/defaultthread1.cs#1)] [!code-vb[System.Globalization.CultureInfo.Class.Thread#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.class.thread/vb/defaultthread1.vb#1)] - In versions of the .NET Framework before the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the most common way to ensure that the main application thread shares the same culture with all other worker threads is to pass either the name of the application-wide culture or a object that represents the application-wide culture to a delegate. The following example uses this approach to ensure that the currency values displayed by two threads reflect the formatting conventions of the same culture. + In versions of the .NET Framework before the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the most common way to ensure that the main application thread shares the same culture with all other worker threads is to pass either the name of the application-wide culture or a object that represents the application-wide culture to a delegate. The following example uses this approach to ensure that the currency values displayed by two threads reflect the formatting conventions of the same culture. [!code-csharp[System.Globalization.CultureInfo.Class.Thread#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureinfo.class.thread/cs/perthread1.cs#2)] [!code-vb[System.Globalization.CultureInfo.Class.Thread#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.class.thread/vb/perthread1.vb#2)] - You can set the culture and UI culture of thread pool threads in a similar manner by calling the method. + You can set the culture and UI culture of thread pool threads in a similar manner by calling the method. Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can set the culture and UI culture of all threads in an application domain more directly by assigning a object that represents that culture to the and properties. The following example uses these properties to ensure that all threads in the default application domain share the same culture. @@ -247,7 +247,7 @@ - Creates a task that executes the delegate asynchronously on a thread pool thread. -- Creates a task that executes the delegate synchronously on the main app thread by calling the method. +- Creates a task that executes the delegate synchronously on the main app thread by calling the method. As the output from the example shows, when the current culture is changed to French (France), the current culture of the thread from which tasks are invoked asynchronously becomes the current culture for that asynchronous operation. @@ -275,11 +275,11 @@ ## CultureInfo object serialization When a object is serialized, all that is actually stored is and . It is successfully de-serialized only in an environment where that has the same meaning. The following three examples show why this is not always the case: -- If the property value is , and if that culture was first introduced in Windows Vista or a later version of the Windows operating system, it is not possible to de-serialize it on Windows XP. Similarly, if the culture was first introduced in Windows XP Service Pack 2, it is not possible to de-serialize it for a Windows XP system on which the culture has not been installed. +- If the property value is , and if that culture was first introduced in Windows Vista or a later version of the Windows operating system, it is not possible to de-serialize it on Windows XP. Similarly, if the culture was first introduced in Windows XP Service Pack 2, it is not possible to de-serialize it for a Windows XP system on which the culture has not been installed. -- If the value is , and the computer on which it is de-serialized does not have this user custom culture installed, it is not possible to de-serialize it. +- If the value is , and the computer on which it is de-serialized does not have this user custom culture installed, it is not possible to de-serialize it. -- If the value is , and the computer on which it is de-serialized does not have this replacement culture, it de-serializes to the same name, but not all of the same characteristics. For example, if en-US is a replacement culture on computer A, but not on computer B, and if a object referring to this culture is serialized on computer A and de-serialized on computer B, then none of the custom characteristics of the culture are transmitted. The culture de-serializes successfully, but with a different meaning. +- If the value is , and the computer on which it is de-serialized does not have this replacement culture, it de-serializes to the same name, but not all of the same characteristics. For example, if en-US is a replacement culture on computer A, but not on computer B, and if a object referring to this culture is serialized on computer A and de-serialized on computer B, then none of the custom characteristics of the culture are transmitted. The culture de-serializes successfully, but with a different meaning. ## Control Panel overrides @@ -360,7 +360,7 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin In most cases, the `culture` parameter is mapped to the corresponding National Language Support (NLS) locale identifier. The value of the `culture` parameter becomes the value of the property of the new . - We recommend that you call the locale name constructor , because locale names are preferable to LCIDs. For custom locales, a locale name is required. + We recommend that you call the locale name constructor , because locale names are preferable to LCIDs. For custom locales, a locale name is required. The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the specified culture identifier matches the culture identifier of the current Windows culture, this constructor creates a that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the (for example, if the selected calendar is not one of the ) the results of the methods and the values of the properties are undefined. @@ -425,7 +425,7 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin ## Remarks For a list of predefined culture names, see the [National Language Support (NLS) API Reference](http://go.microsoft.com/fwlink/?LinkId=200048) at the Go Global Developer Center. In addition, starting with Windows 10, `name` can be any valid BCP-47 language tag. - If `name` is , the constructor creates an instance of the invariant culture; this is equivalent to retrieving the value of the property. + If `name` is , the constructor creates an instance of the invariant culture; this is equivalent to retrieving the value of the property. The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the culture identifier associated with `name` matches the culture identifier of the current Windows culture, this constructor creates a object that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. @@ -496,7 +496,7 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin In most cases, the `culture` parameter is mapped to the corresponding National Language Support (NLS) locale identifier. The value of the `culture` parameter becomes the value of the property of the new . - We recommend that you call the locale name constructor , because locale names are preferable to LCIDs. For custom locales, a locale name is required. + We recommend that you call the locale name constructor , because locale names are preferable to LCIDs. For custom locales, a locale name is required. The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. @@ -566,7 +566,7 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin ## Remarks For a list of predefined culture names, see the [National Language Support (NLS) API Reference](http://go.microsoft.com/fwlink/?LinkId=200048) at the Go Global Developer Center. In addition, starting with Windows 10, `name` can be any valid BCP-47 language tag. - If `name` is , the constructor creates an instance of the invariant culture; this is equivalent to retrieving the value of the property. + If `name` is , the constructor creates an instance of the invariant culture; this is equivalent to retrieving the value of the property. The user might choose to override some of the values associated with the current Windows culture through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. @@ -680,7 +680,7 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin The method clears the cache of objects created by and refreshes the information in the , , and properties, based on the current system settings. - The method does not refresh the information in the property for existing threads. However, future threads will have any new property values. + The method does not refresh the information in the property for existing threads. However, future threads will have any new property values. ]]> @@ -950,7 +950,7 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin ## Remarks The object that is returned by this property and its associated objects determine the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. - The current culture is a property of the executing thread, which is returned by the static property. The value of the property corresponds to the value of the property. Retrieving the value of the property is equivalent to retrieving the object returned by the `Thread.CurrentThread.CurrentCulture` property. Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], setting the value of the property also changes the current thread culture. + The current culture is a property of the executing thread, which is returned by the static property. The value of the property corresponds to the value of the property. Retrieving the value of the property is equivalent to retrieving the object returned by the `Thread.CurrentThread.CurrentCulture` property. Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], setting the value of the property also changes the current thread culture. > [!NOTE] > In the .NET Framework 4.5.2 and earlier versions, the property is read-only; that is, you can retrieve the property value, but you cannot set it. To change the current culture, you assign the object that represents the new culture to the `Thread.CurrentThread.CurrentCulture` property. Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], the property is read-write; you can both set and retrieve the property's value. If you do set the property value to a object that represents a new culture, the value of the `Thread.CurrentThread.CurrentCulture` property also changes. @@ -984,29 +984,29 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin ## Getting the Current Culture - The property is a per-thread setting; that is, each thread can have its own culture. You get the culture of the current thread by retrieving the value of the property, as the following example illustrates. + The property is a per-thread setting; that is, each thread can have its own culture. You get the culture of the current thread by retrieving the value of the property, as the following example illustrates. [!code-csharp[System.Globalization.CultureInfo.CurrentCulture#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/cs/Get1.cs#5)] [!code-vb[System.Globalization.CultureInfo.CurrentCulture#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/Get1.vb#5)] - You can also retrieve the value of the current thread's culture from the property. + You can also retrieve the value of the current thread's culture from the property. ## Explicitly Setting the CurrentCulture Property - Staring with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], to change the culture that is used by an existing thread, you set the property to the new culture. If you explicitly change a thread's culture in this way, that change persists if the thread crosses application domain boundaries. The following example changes the current thread culture to Dutch (Netherlands). It also shows that, when the current thread crosses application domain boundaries, its current culture remains changed. + Staring with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], to change the culture that is used by an existing thread, you set the property to the new culture. If you explicitly change a thread's culture in this way, that change persists if the thread crosses application domain boundaries. The following example changes the current thread culture to Dutch (Netherlands). It also shows that, when the current thread crosses application domain boundaries, its current culture remains changed. [!code-csharp[System.Globalization.CultureInfo.CurrentCulture#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/cs/changeculture11.cs#11)] [!code-vb[System.Globalization.CultureInfo.CurrentCulture#11](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/changeculture11.vb#11)] > [!NOTE] -> Changing the culture by using the property requires a permission with the value set. Manipulating threads is dangerous because of the security state associated with threads. Therefore, this permission should be given only to trustworthy code, and then only as necessary. You cannot change thread culture in semi-trusted code. +> Changing the culture by using the property requires a permission with the value set. Manipulating threads is dangerous because of the security state associated with threads. Therefore, this permission should be given only to trustworthy code, and then only as necessary. You cannot change thread culture in semi-trusted code. Starting with the [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)], you can explicitly change the current thread culture to either a specific culture (such as French (Canada)) or a neutral culture (such as French). When a object represents a neutral culture, the values of properties such as , , , , and reflect the specific culture that is associated with the neutral culture. For example, the dominant culture for the English neutral culture is English (United States); the dominant culture for the German culture is German (Germany). The following example illustrates the difference in formatting when the current culture is set to a specific culture, French (Canada), and a neutral culture, French. [!code-csharp[System.Globalization.CultureInfo.CurrentCulture#12](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/cs/specific12.cs#12)] [!code-vb[System.Globalization.CultureInfo.CurrentCulture#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/specific12.vb#12)] - You can also use the property along with the property to set the property of an ASP.NET application to the user's preferred culture, as the following example illustrates. + You can also use the property along with the property to set the property of an ASP.NET application to the user's preferred culture, as the following example illustrates. [!code-csharp[System.Globalization.CultureInfo.CurrentCulture#13](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/cs/aspculture13.cs#13)] [!code-vb[System.Globalization.CultureInfo.CurrentCulture#13](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentculture/vb/aspculture13.vb#13)] @@ -1097,10 +1097,10 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin > [!NOTE] > In the [!INCLUDE[Compact](~/includes/compact-md.md)], the property is read-only. The current UI culture is determined by the system's regional settings and cannot be changed programmatically. - Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], to change the user interface culture used by a thread, set the property to the new culture. If you explicitly change a thread's UI culture in this way, that change persists if the thread crosses application domain boundaries. + Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], to change the user interface culture used by a thread, set the property to the new culture. If you explicitly change a thread's UI culture in this way, that change persists if the thread crosses application domain boundaries. > [!NOTE] -> In the .NET Framework 4.5.2 and earlier versions, the property is read-only; that is, you can retrieve the property value, but you cannot set it. To change the current UI culture, you assign the object that represents the new UI culture to the `Thread.CurrentThread.CurrentUICulture` property. Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], the property is read-write; you can both set and retrieve the property's value. If you do set the property value to a object that represents a new culture, the value of the `Thread.CurrentThread.CurrentCulture` property also changes. +> In the .NET Framework 4.5.2 and earlier versions, the property is read-only; that is, you can retrieve the property value, but you cannot set it. To change the current UI culture, you assign the object that represents the new UI culture to the `Thread.CurrentThread.CurrentUICulture` property. Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], the property is read-write; you can both set and retrieve the property's value. If you do set the property value to a object that represents a new culture, the value of the `Thread.CurrentThread.CurrentCulture` property also changes. In this section: @@ -1112,21 +1112,21 @@ In .NET Framework and .NET Core apps, the current culture is a per-thread settin ## Getting the Current UI Culture - The property is a per-thread setting; that is, each thread can have its own UI culture. You get the UI culture of the current thread by retrieving the value of the property, as the following example illustrates. + The property is a per-thread setting; that is, each thread can have its own UI culture. You get the UI culture of the current thread by retrieving the value of the property, as the following example illustrates. [!code-csharp[System.Globalization.CultureInfo.CurrentUICulture#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/cs/Get1.cs#5)] [!code-vb[System.Globalization.CultureInfo.CurrentUICulture#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/Get1.vb#5)] - You can also retrieve the value of the current thread's UI culture from the property. + You can also retrieve the value of the current thread's UI culture from the property. ## Explicitly Setting the Current UI Culture - Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], you can change the current UI culture by assigning a object that represents the new culture to the property. The current UI culture can be set to either a specific culture (such as en-US or de-DE) or to a neutral culture (such as en or de). The following example sets the current UI culture to fr-FR or French (France). + Starting with the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], you can change the current UI culture by assigning a object that represents the new culture to the property. The current UI culture can be set to either a specific culture (such as en-US or de-DE) or to a neutral culture (such as en or de). The following example sets the current UI culture to fr-FR or French (France). [!code-csharp[System.Globalization.CultureInfo.CurrentUICulture#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/cs/currentuiculture1.cs#1)] [!code-vb[System.Globalization.CultureInfo.CurrentUICulture#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.currentuiculture/vb/currentuiculture1.vb#1)] - In a multithreaded application, you can explicitly set the UI culture of any thread by assigning a object that represents that culture to the thread's property. If the thread whose culture you want to set is the current thread, you can assign the new culture to the property. When the UI culture of a thread is set explicitly, that thread retains the same culture even if it crosses application domain boundaries and executes code in another application domain. + In a multithreaded application, you can explicitly set the UI culture of any thread by assigning a object that represents that culture to the thread's property. If the thread whose culture you want to set is the current thread, you can assign the new culture to the property. When the UI culture of a thread is set explicitly, that thread retains the same culture even if it crosses application domain boundaries and executes code in another application domain. ## Implicitly Setting the Current UI Culture @@ -1548,7 +1548,7 @@ csc /resource:GreetingStrings.resources Example1.cs . + This method overrides . Two objects are considered equal if their and properties are equal. @@ -1592,7 +1592,7 @@ csc /resource:GreetingStrings.resources Example1.cs ## Remarks Languages such as Arabic, Hebrew, Urdu, and Syriac are based on bidirectional text. Windows applications, which have a graphical user interface, support bidirectional languages. However, console applications, which employ the text user interface of the operating system console, do not provide bidirectional support. Therefore, if you localize a console application to Arabic or Hebrew, your application displays unreadable text on the console screen. - The user interface culture specifies the resources an application needs to support user input and output, and by default is the same as the operating system culture. For example, the property returns an Arabic culture for an Arabic operating system. Use the method to retrieve a culture suitable for a console application user interface. After your application retrieves the fallback user interface culture, it should assign the culture to the current user interface culture of the current thread. For more information, see the "Explicitly Setting the Current UI Culture" section of the property. + The user interface culture specifies the resources an application needs to support user input and output, and by default is the same as the operating system culture. For example, the property returns an Arabic culture for an Arabic operating system. Use the method to retrieve a culture suitable for a console application user interface. After your application retrieves the fallback user interface culture, it should assign the culture to the current user interface culture of the current thread. For more information, see the "Explicitly Setting the Current UI Culture" section of the property. The following are predefined cultures that have a different fallback user interface culture name from the predefined culture name. @@ -1778,11 +1778,11 @@ csc /resource:GreetingStrings.resources Example1.cs ## Remarks For a list of predefined culture names, see the [National Language Support (NLS) API Reference](http://go.microsoft.com/fwlink/?LinkId=200048) at the Go Global Developer Center. In addition, starting with Windows 10, `name` can be any valid BCP-47 language tag. - The method retrieves a cached, read-only object. It offers better performance than a corresponding call to the constructor. + The method retrieves a cached, read-only object. It offers better performance than a corresponding call to the constructor. If `name` is the name of the current culture, the returned object does not reflect any user overrides. This makes the method suitable for server applications or tools that do not have a real user account on the system and that need to load multiple cultures efficiently. - If `name` is , the method returns the invariant culture. This is equivalent to retrieving the value of the property. + If `name` is , the method returns the invariant culture. This is equivalent to retrieving the value of the property. ]]> @@ -1833,7 +1833,7 @@ csc /resource:GreetingStrings.resources Example1.cs The method obtains a cached, read-only object. It offers better performance than a corresponding call to a constructor. The method is used to create a culture similar to that specified by the `name` parameter, but with different sorting and casing rules. - If `name` or `altName` is the name of the current culture, the returned objects do not reflect any user overrides. If `name` is , the method returns the invariant culture. This is equivalent to retrieving the value of the property. If `altName` is , the method uses the writing system and comparison rules specified by the invariant culture. + If `name` or `altName` is the name of the current culture, the returned objects do not reflect any user overrides. If `name` is , the method returns the invariant culture. This is equivalent to retrieving the value of the property. If `altName` is , the method uses the writing system and comparison rules specified by the invariant culture. ]]> @@ -2009,7 +2009,7 @@ csc /resource:GreetingStrings.resources Example1.cs implements . + implements . `NumberFormatInfo` provides the culture-specific numeric format used in conjunction with the Format methods in the base data types. `DateTimeFormatInfo` controls how the date and time values are formatted for a specific culture. @@ -2051,7 +2051,7 @@ csc /resource:GreetingStrings.resources Example1.cs . + This method overrides . This method generates the same hash code for two objects that are equal according to the method. @@ -2094,7 +2094,7 @@ csc /resource:GreetingStrings.resources Example1.cs ## Remarks > [!NOTE] -> This property and the method are deprecated. Instead, you should use a the property. IETF tags and names are identical. +> This property and the method are deprecated. Instead, you should use a the property. IETF tags and names are identical. The RFC 4646 standard that is maintained by the Internet Engineering Task Force (IETF) defines an IETF language tag, which provides a uniform means of identifying a language. The format of an IETF language tag is similar to the culture name returned by the property, but does not identify a culture uniquely. That is, different cultures share the same IETF language tag if those cultures have identical linguistic characteristics. The linguistic characteristics of a culture are contained in the object associated with a object. @@ -2173,7 +2173,7 @@ csc /resource:GreetingStrings.resources Example1.cs instantiation method. also retrieves an instance of the invariant culture. It can be used in almost any method in the namespace that requires a culture. The objects returned by properties such as , , and also reflect the string comparison and formatting conventions of the invariant culture. + The invariant culture is culture-insensitive; it is associated with the English language but not with any country/region. You specify the invariant culture by name by using an empty string ("") in the call to a instantiation method. also retrieves an instance of the invariant culture. It can be used in almost any method in the namespace that requires a culture. The objects returned by properties such as , , and also reflect the string comparison and formatting conventions of the invariant culture. Unlike culture-sensitive data, which is subject to change by user customization or by updates to the .NET Framework or the operating system, invariant culture data is stable over time and across installed cultures and cannot be customized by users. This makes the invariant culture particularly useful for operations that require culture-independent results, such as formatting and parsing operations that persist formatted data, or sorting and ordering operations that require that data be displayed in a fixed order regardless of culture. @@ -2183,7 +2183,7 @@ csc /resource:GreetingStrings.resources Example1.cs ## Persisting Data The property can be used to persist data in a culture-independent format. This provides a known format that does not change and that can be used to serialize and deserialize data across cultures. After the data is deserialized, it can be formatted appropriately based on the cultural conventions of the current user. - For example, if you choose to persist date and time data in string form, you can pass the object to the or method to create the string, and you can pass the object to the or method to convert the string back to a date and time value. This technique ensures that the underlying date and time values do not change when the data is read or written by users from different cultures. + For example, if you choose to persist date and time data in string form, you can pass the object to the or method to create the string, and you can pass the object to the or method to convert the string back to a date and time value. This technique ensures that the underlying date and time values do not change when the data is read or written by users from different cultures. The following example uses the invariant culture to persist a value as a string. It then parses the string and displays its value by using the formatting conventions of the French (France) and German (Germany) cultures. @@ -2191,7 +2191,7 @@ csc /resource:GreetingStrings.resources Example1.cs [!code-vb[System.Globalization.CultureInfo.InvariantCulture#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureinfo.invariantculture/vb/persist1.vb#1)] ## Security Decisions - If you are making a security decision (such as whether to allow access to a system resource) based on the result of a string comparison or a case change, you should not use the invariant culture. Instead, you should perform a case-sensitive or case-insensitive ordinal comparison by calling a method that includes a parameter and supplying either or as an argument. Code that performs culture-sensitive string operations can cause security vulnerabilities if the current culture is changed or if the culture on the computer that is running the code differs from the culture that is used to test the code. In contrast, an ordinal comparison depends solely on the binary value of the compared characters. + If you are making a security decision (such as whether to allow access to a system resource) based on the result of a string comparison or a case change, you should not use the invariant culture. Instead, you should perform a case-sensitive or case-insensitive ordinal comparison by calling a method that includes a parameter and supplying either or as an argument. Code that performs culture-sensitive string operations can cause security vulnerabilities if the current culture is changed or if the culture on the computer that is running the code differs from the culture that is used to test the code. In contrast, an ordinal comparison depends solely on the binary value of the compared characters. ]]> @@ -2419,7 +2419,7 @@ csc /resource:GreetingStrings.resources Example1.cs ## Remarks For a list of predefined culture names and identifiers that the property can return, see the [National Language Support (NLS) API Reference](http://go.microsoft.com/fwlink/?LinkId=200048) at the Go Global Developer Center. In addition, starting with Windows 10, `name` can be any valid BCP-47 language tag. Note that culture names are subject to change, and that they also can reflect the names of custom cultures. - The property follows the naming standards provided in the class topic. It returns the short form of the culture name that excludes any indication of an alternate sort order. For example, if you instantiate a object by using the string "de-DE_phoneb" to reflect an alternate sort order, the property returns "de-DE". + The property follows the naming standards provided in the class topic. It returns the short form of the culture name that excludes any indication of an alternate sort order. For example, if you instantiate a object by using the string "de-DE_phoneb" to reflect an alternate sort order, the property returns "de-DE". To get the full name of the culture, you should use the , , or property. @@ -2768,7 +2768,7 @@ csc /resource:GreetingStrings.resources Example1.cs For example, the three-letter abbreviation for English is "eng". > [!NOTE] -> When communicating between processes or persisting data it is usually better to use the full . Using just the language can lose context and data. +> When communicating between processes or persisting data it is usually better to use the full . Using just the language can lose context and data. @@ -2817,7 +2817,7 @@ csc /resource:GreetingStrings.resources Example1.cs This property returns the same value as the Windows API method `GetLocaleInfo` with the LOCALE_SABBREVLANGNAME value. For example, the three-letter code for English (United States) as defined in the Windows API is "enu". > [!NOTE] -> When communicating between processes or persisting data it is usually better to use the full . Using just the language can lose context and data. +> When communicating between processes or persisting data it is usually better to use the full . Using just the language can lose context and data. @@ -2869,7 +2869,7 @@ csc /resource:GreetingStrings.resources Example1.cs . It returns a normalized version of the culture name that is passed to the or constructor or to the or method. It normalizes the result string by converting characters in *languagecode2* to lowercase and converting characters in *country/regioncode2* to uppercase if necessary. + This method overrides . It returns a normalized version of the culture name that is passed to the or constructor or to the or method. It normalizes the result string by converting characters in *languagecode2* to lowercase and converting characters in *country/regioncode2* to uppercase if necessary. Predefined culture names are listed in the [National Language Support (NLS) API Reference](http://go.microsoft.com/fwlink/?LinkId=200048) page at the Go Global Developer Center. @@ -2913,7 +2913,7 @@ csc /resource:GreetingStrings.resources Example1.cs For example, the two-letter abbreviation for English is "en". The property value for the invariant culture is "iv". > [!NOTE] -> When communicating between processes or persisting data it is usually better to use the full . Using just the language can lose context and data. +> When communicating between processes or persisting data it is usually better to use the full . Using just the language can lose context and data. If ISO 639-1 does not define a two-letter language code for a particular culture, the property returns a string that consists of three or more letters. For more information, see the example. diff --git a/xml/System.Globalization/CultureNotFoundException.xml b/xml/System.Globalization/CultureNotFoundException.xml index 985e2df292b4c..656711340b0e0 100644 --- a/xml/System.Globalization/CultureNotFoundException.xml +++ b/xml/System.Globalization/CultureNotFoundException.xml @@ -37,11 +37,11 @@ ## Remarks A exception is thrown whenever the construction of an invalid culture is eventually attempted within a method. Most commonly, this exception is thrown when a call to one of the following methods fails to create or return a culture: -- constructors. +- constructors. -- The method. +- The method. -- The method. +- The method. > [!WARNING] > On Windows 7 and later operating systems, the .NET Framework retrieves culture data from the operating system. The exception is thrown if the operating system is unable to find the culture, and the culture is not a custom culture or a replacement culture. diff --git a/xml/System.Globalization/CultureTypes.xml b/xml/System.Globalization/CultureTypes.xml index 0d739a74cf649..6655611945c8b 100644 --- a/xml/System.Globalization/CultureTypes.xml +++ b/xml/System.Globalization/CultureTypes.xml @@ -32,7 +32,7 @@ property, and also serve as a filter that limits the cultures returned by the method. For more information on cultures, see . + These culture type values are returned by the property, and also serve as a filter that limits the cultures returned by the method. For more information on cultures, see . Generally, your application should enumerate all cultures, using the AllCultures value. This allows enumeration of custom cultures, as well as the other culture types. @@ -168,7 +168,7 @@ ## Remarks Custom cultures can have any user-specified name, not just a two-letter code. - The invariant culture is included in the array of cultures returned by the method that specifies this value. + The invariant culture is included in the array of cultures returned by the method that specifies this value. ]]> @@ -259,7 +259,7 @@ value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096). As a result, code such as + In Windows versions prior to Windows 10, the UserCustomCulture value is assigned to custom cultures created by the developer. In Windows 10, the UserCustomCulture value is also assigned to system cultures that are not backed by a complete set of cultural data and that do not have unique local identifiers. (All cultures of type UserCustomCulture share a value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096). As a result, code such as [!code-csharp[System.Globalization.CultureTypes#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.cultureTypes/cs/getcultures3.cs#2)] [!code-vb[System.Globalization.CultureTypes#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.cultureTypes/vb/getcultures3.vb#2)] diff --git a/xml/System.Globalization/DateTimeFormatInfo.xml b/xml/System.Globalization/DateTimeFormatInfo.xml index 9f26e8cd54dcd..c03a5cd6c39f6 100644 --- a/xml/System.Globalization/DateTimeFormatInfo.xml +++ b/xml/System.Globalization/DateTimeFormatInfo.xml @@ -88,7 +88,7 @@ - By calling the parameterless constructor. The returned object is read/write. -- By retrieving the value of the property from the object that is returned by the property. The returned object is read-only. +- By retrieving the value of the property from the object that is returned by the property. The returned object is read-only. The following example uses each of these methods to instantiate a object that represents the invariant culture. It then indicates whether the object is read-only. @@ -99,13 +99,13 @@ ### Instantiating a DateTimeFormatInfo object for a specific culture A specific culture represents a language that is spoken in a particular country/region. For example, en-US is a specific culture that represents the English language spoken in the United States, and en-CA is a specific culture that represents the English language spoken in Canada. You can instantiate a object that represents the formatting conventions of a specific culture in the following ways: -- By calling the method and retrieving the value of the returned object's property. The returned object is read-only. +- By calling the method and retrieving the value of the returned object's property. The returned object is read-only. - By passing the static method a object that represents the culture whose object you want to retrieve. The returned object is read/write. -- By calling the static method and retrieving the value of the returned object's property. The returned object is read/write. +- By calling the static method and retrieving the value of the returned object's property. The returned object is read/write. -- By calling the class constructor and retrieving the value of the returned object's property. The returned object is read/write. +- By calling the class constructor and retrieving the value of the returned object's property. The returned object is read/write. The following example illustrates each of these ways to instantiate a object and indicates whether the resulting object is read-only. @@ -114,7 +114,7 @@ ### Instantiating a DateTimeFormatInfo object for a neutral culture - A neutral culture represents a culture or language that is independent of a country/region; it is typically the parent of one or more specific cultures. For example, Fr is a neutral culture for the French language and the parent of the fr-FR culture. You can instantiate a object that represents the formatting conventions of a neutral culture in the same ways that you create a object that represents the formatting conventions of a specific culture. In addition, you can retrieve a neutral culture's object by retrieving a neutral culture from a specific culture's property and retrieving the object returned by its property. Unless the parent culture represents the invariant culture, the returned object is read/write. The following example illustrates these ways of instantiating a object that represents a neutral culture. + A neutral culture represents a culture or language that is independent of a country/region; it is typically the parent of one or more specific cultures. For example, Fr is a neutral culture for the French language and the parent of the fr-FR culture. You can instantiate a object that represents the formatting conventions of a neutral culture in the same ways that you create a object that represents the formatting conventions of a specific culture. In addition, you can retrieve a neutral culture's object by retrieving a neutral culture from a specific culture's property and retrieving the object returned by its property. Unless the parent culture represents the invariant culture, the returned object is read/write. The following example illustrates these ways of instantiating a object that represents a neutral culture. [!code-csharp[System.Globalization.DateTimeFormatInfo.Class#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/cs/create1.cs#2)] [!code-vb[System.Globalization.DateTimeFormatInfo.Class#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/vb/create1.vb#2)] @@ -124,7 +124,7 @@ However, a neutral culture lacks culture-specific formatting information, because it is independent of a specific country/region. Instead of populating the object with generic values, the .NET Framework returns a object that reflects the formatting conventions of a specific culture that is a child of the neutral culture. For example, the object for the neutral en culture reflects the formatting conventions of the en-US culture, and the object for the fr culture reflects the formatting conventions of the fr-FR culture. - You can use code like the following to determine which specific culture's formatting conventions a neutral culture represents. The example uses reflection to compare the properties of a neutral culture with the properties of a specific child culture. It considers two calendars to be equivalent if they are the same calendar type and, for Gregorian calendars, if their properties have identical values. + You can use code like the following to determine which specific culture's formatting conventions a neutral culture represents. The example uses reflection to compare the properties of a neutral culture with the properties of a specific child culture. It considers two calendars to be equivalent if they are the same calendar type and, for Gregorian calendars, if their properties have identical values. [!code-csharp[System.Globalization.DateTimeFormatInfo.Class#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/cs/instantiate6c.cs#6)] [!code-vb[System.Globalization.DateTimeFormatInfo.Class#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/vb/instantiate6c.vb#6)] @@ -135,7 +135,7 @@ - By retrieving the value of the property. The returned object is read-only. -- By retrieving the value of the property from the object that is returned by the property. The returned object is read-only. +- By retrieving the value of the property from the object that is returned by the property. The returned object is read-only. - By calling the method with a object that represents the current culture. The returned object is read-only. @@ -148,14 +148,14 @@ - By retrieving a object in any of the three previous ways and calling the method on the returned object. This creates a copy of the original object, except that its property is `false`. -- By calling the method to create a object that represents the current culture, and then using its property to retrieve the object. +- By calling the method to create a object that represents the current culture, and then using its property to retrieve the object. The following example illustrates each way of instantiating a read/write object and displays the value of its property. [!code-csharp[System.Globalization.DateTimeFormatInfo.Class#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/cs/instantiate2.cs#7)] [!code-vb[System.Globalization.DateTimeFormatInfo.Class#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/vb/instantiate2.vb#7)] - In Windows, the user can override some of the property values used in formatting and parsing operations through the **Region and Language** application in Control Panel. For example, a user whose culture is English (United States) might choose to display long time values using a 24-hour clock (in the format HH:mm:ss) instead of the default 12-hour clock (in the format h:mm:ss tt). The objects retrieved in the ways discussed previously all reflect these user overrides. If this is undesirable, you can create a object that does not reflect user overrides (and is also read/write instead of read-only) by calling the constructor and supplying a value of `false` for the `useUserOverride` argument. The following example illustrates this for a system whose current culture is English (United States) and whose long time pattern has been changed from the default of h:mm:ss tt to HH:mm:ss. + In Windows, the user can override some of the property values used in formatting and parsing operations through the **Region and Language** application in Control Panel. For example, a user whose culture is English (United States) might choose to display long time values using a 24-hour clock (in the format HH:mm:ss) instead of the default 12-hour clock (in the format h:mm:ss tt). The objects retrieved in the ways discussed previously all reflect these user overrides. If this is undesirable, you can create a object that does not reflect user overrides (and is also read/write instead of read-only) by calling the constructor and supplying a value of `false` for the `useUserOverride` argument. The following example illustrates this for a system whose current culture is English (United States) and whose long time pattern has been changed from the default of h:mm:ss tt to HH:mm:ss. [!code-csharp[System.Globalization.DateTimeFormatInfo.Class#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/cs/instantiate3.cs#8)] [!code-vb[System.Globalization.DateTimeFormatInfo.Class#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/vb/instantiate3.vb#8)] @@ -170,7 +170,7 @@ - Cascading changes to property values. A number of culture-related properties can change at run time, which, in turn, causes data to change. For example, the current culture can be changed either programmatically or through user action. When this happens, the object returned by the property changes to an object associated with the current culture. Similarly, a culture's calendar can change, which can result in changes to numerous property values. -- User preferences. Users of your application might choose to override some of the values associated with the current system culture through the regional and language options in Control Panel. For example, users might choose to display the date in a different format. If the property is set to `true`, the properties of the object is also retrieved from the user settings. If the user settings are incompatible with the culture associated with the object (for example, if the selected calendar is not one of the calendars indicated by the property), the results of the methods and the values of the properties are undefined. +- User preferences. Users of your application might choose to override some of the values associated with the current system culture through the regional and language options in Control Panel. For example, users might choose to display the date in a different format. If the property is set to `true`, the properties of the object is also retrieved from the user settings. If the user settings are incompatible with the culture associated with the object (for example, if the selected calendar is not one of the calendars indicated by the property), the results of the methods and the values of the properties are undefined. To minimize the possibility of inconsistent data, all user-overridable properties of a object are initialized when the object is created. There is still a possibility of inconsistency, because neither object creation nor the user override process is atomic and the relevant values can change during object creation. However, this situation should be extremely rare. @@ -179,11 +179,11 @@ |Source of CultureInfo and DateTimeFormatInfo object|Reflects user overrides| |---------------------------------------------------------|-----------------------------| |`CultureInfo.CurrentCulture.DateTimeFormat` property|Yes| -| property|Yes| -| method|Yes| -| method|No| -| constructor|Yes| -| constructor|Depends on value of `useUserOverride` parameter| +| property|Yes| +| method|Yes| +| method|No| +| constructor|Yes| +| constructor|Depends on value of `useUserOverride` parameter| Unless there is a compelling reason to do otherwise, you should respect user overrides when you use the object in client applications to format and parse user input or to display data. For server applications or unattended applications, you should not. However, if you are using the object either explicitly or implicitly to persist date and time data in string form, you should either use a object that reflects the formatting conventions of the invariant culture, or you should specify a custom date and time format string that you use regardless of culture. @@ -191,21 +191,21 @@ ## Formatting dates and times A object is used implicitly or explicitly in all date and time formatting operations. These include calls to the following methods: -- All date and time formatting methods, such as and . +- All date and time formatting methods, such as and . -- The major composite formatting method, which is . +- The major composite formatting method, which is . -- Other composite formatting methods, such as and . +- Other composite formatting methods, such as and . - All date and time formatting operations make use of an implementation. The interface includes a single method, . This callback method is passed a object that represents the type needed to provide formatting information. The method returns either an instance of that type or `null` if it cannot provide an instance of the type. The .NET Framework includes two implementations for formatting dates and times: + All date and time formatting operations make use of an implementation. The interface includes a single method, . This callback method is passed a object that represents the type needed to provide formatting information. The method returns either an instance of that type or `null` if it cannot provide an instance of the type. The .NET Framework includes two implementations for formatting dates and times: -- The class, which represents a specific culture (or a specific language in a specific country/region). In a date and time formatting operation, the method returns the object associated with its property. +- The class, which represents a specific culture (or a specific language in a specific country/region). In a date and time formatting operation, the method returns the object associated with its property. -- The class, which provides information about the formatting conventions of its associated culture. The method returns an instance of itself. +- The class, which provides information about the formatting conventions of its associated culture. The method returns an instance of itself. - If an implementation is not provided to a formatting method explicitly, the object returned by the property that represents the current thread culture is used. + If an implementation is not provided to a formatting method explicitly, the object returned by the property that represents the current thread culture is used. - The following example illustrates the relationship between the interface and the class in formatting operations. It defines a custom implementation whose method displays the type of the object requested by the formatting operation. If it is requesting a object, the method provides the object for the current thread culture. As the output from the example shows, the method requests a object to provide formatting information, whereas the method requests and objects as well as an implementation. + The following example illustrates the relationship between the interface and the class in formatting operations. It defines a custom implementation whose method displays the type of the object requested by the formatting operation. If it is requesting a object, the method provides the object for the current thread culture. As the output from the example shows, the method requests a object to provide formatting information, whereas the method requests and objects as well as an implementation. [!code-csharp[System.Globalization.DateTimeFormatInfo.Class#9](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/cs/formatprovider1.cs#9)] [!code-vb[System.Globalization.DateTimeFormatInfo.Class#9](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.class/vb/formatprovider1.vb#9)] @@ -262,7 +262,7 @@ - You can use the class to define either a custom culture (a culture that has a unique name and that supplements existing cultures) or a replacement culture (one that is used instead of a specific culture). You can save and access this culture programmatically as you would any object supported by the .NET Framework. -- If the result string is not culture-sensitive and doesn't follow a predefined format, you can use a custom date and time format string. For example, if you are serializing date and time data in the format YYYYMMDDHHmmss, you can generate the result string by passing the custom format string to the method, and you can convert the result string back to a value by calling the method. +- If the result string is not culture-sensitive and doesn't follow a predefined format, you can use a custom date and time format string. For example, if you are serializing date and time data in the format YYYYMMDDHHmmss, you can generate the result string by passing the custom format string to the method, and you can convert the result string back to a value by calling the method. ### Changing the short date pattern The following example changes the format of a result string produced by the "d" (short date) standard format string. It changes the associated property for the en-US or English (United States) culture from its default of "M/d/yyyy" to "yyyy'-"MM"-"dd" and uses the "d" standard format string to display the date both before and after the property is changed. @@ -318,9 +318,9 @@ ## Parsing date and time strings Parsing involves converting the string representation of a date and time to a or value. Both of these types include the `Parse`, `TryParse`, `ParseExact`, and `TryParseExact` methods to support parsing operations. The `Parse` and `TryParse` methods convert a string that can have a variety of formats, whereas `ParseExact` and `TryParseExact` require that the string have a defined format or formats. If the parsing operation fails, `Parse` and `ParseExact` throw an exception, whereas `TryParse` and `TryParseExact` return `false`. - The parsing methods implicitly or explicitly use a enumeration value to determine which style elements (such as leading, trailing, or inner white space) can be present in the string to be parsed, and how to interpret the parsed string or any missing elements. If you don't provide a value when you call the `Parse` or `TryParse` method, the default is , which is a composite style that includes the , , and flags. For the `ParseExact` and `TryParseExact` methods, the default is ; the input string must correspond precisely to a particular custom date and time format string. + The parsing methods implicitly or explicitly use a enumeration value to determine which style elements (such as leading, trailing, or inner white space) can be present in the string to be parsed, and how to interpret the parsed string or any missing elements. If you don't provide a value when you call the `Parse` or `TryParse` method, the default is , which is a composite style that includes the , , and flags. For the `ParseExact` and `TryParseExact` methods, the default is ; the input string must correspond precisely to a particular custom date and time format string. - The parsing methods also implicitly or explicitly use a object that defines the specific symbols and patterns that can occur in the string to be parsed. If you don't provide a object, the object for the current thread culture is used by default. For more information about parsing date and time strings, see the individual parsing methods, such as , , , and . + The parsing methods also implicitly or explicitly use a object that defines the specific symbols and patterns that can occur in the string to be parsed. If you don't provide a object, the object for the current thread culture is used by default. For more information about parsing date and time strings, see the individual parsing methods, such as , , , and . The following example illustrates the culture-sensitive nature of parsing date and time strings. It tries to parse two date strings by using the conventions of the en-US, en-GB, fr-FR, and fi-FI cultures. The date that is interpreted as 8/18/2014 in the en-US culture throws a exception in the other three cultures because 18 is interpreted as the month number. 1/2/2015 is parsed as the second day of the first month in the en-US culture, but as the first day of the second month in the remaining cultures. @@ -400,9 +400,9 @@ object that represents the date and time information of the invariant culture. To create a object for a specific culture, create a object for that culture and retrieve the object returned by its property. + This constructor creates a object that represents the date and time information of the invariant culture. To create a object for a specific culture, create a object for that culture and retrieve the object returned by its property. - The properties of the object created by this constructor can be modified. However, you cannot modify the property, because the invariant culture supports only a localized version of the Gregorian calendar. To create a object that uses a specific calendar, you must instantiate a object that supports that calendar and assign the calendar to the property of the object returned by the property. + The properties of the object created by this constructor can be modified. However, you cannot modify the property, because the invariant culture supports only a localized version of the Gregorian calendar. To create a object that uses a specific calendar, you must instantiate a object that supports that calendar and assign the calendar to the property of the object returned by the property. ]]> @@ -443,7 +443,7 @@ ## Remarks If setting this property, the array must be one-dimensional and must have exactly seven elements. The first element (the element at index zero) represents the first day of the week in the calendar defined by the property. - If a custom format string includes the "ddd" format specifier, the or method includes the appropriate member of the array in place of the "ddd" in the result string. + If a custom format string includes the "ddd" format specifier, the or method includes the appropriate member of the array in place of the "ddd" in the result string. This property is affected if the value of the property changes. If the selected does not support abbreviated day names, the array contains the full day names. @@ -500,9 +500,9 @@ or method includes the appropriate member of the array in place of the "MMM" in the result string. + In some languages, a month name that is part of a date appears in the genitive case. For example, a date in the ru-RU or Russian (Russia) culture consists of the day number and the genitive month name, such as 1 Января (1 January). For these cultures, if a custom format string includes the "MMM" format specifier, the or method includes the appropriate member of the array in place of the "MMM" in the result string. - In a set operation, the array must be one-dimensional with exactly 13 elements, because objects accommodate calendars that have 13 months. For calendars that have 12 months, the thirteenth element should be . The first element (the element at index zero) represents the first month of the year defined by the property. + In a set operation, the array must be one-dimensional with exactly 13 elements, because objects accommodate calendars that have 13 months. For calendars that have 12 months, the thirteenth element should be . The first element (the element at index zero) represents the first month of the year defined by the property. If you set the property, you must also set the property. @@ -614,7 +614,7 @@ ## Remarks The property is used for all times from 0:00:00 (midnight) to 11:59:59.999. - If a custom format string includes the "tt" format specifier and the time is before noon, the or method includes the value of the property in place of "tt" in the result string. If the custom format string includes the "t" custom format specifier, only the first character of the property value is included. You should use "tt" for languages for which it is necessary to maintain the distinction between A.M. and P.M. An example is Japanese, in which the A.M. and P.M. designators differ in the second character instead of the first character. + If a custom format string includes the "tt" format specifier and the time is before noon, the or method includes the value of the property in place of "tt" in the result string. If the custom format string includes the "t" custom format specifier, only the first character of the property value is included. You should use "tt" for languages for which it is necessary to maintain the distinction between A.M. and P.M. An example is Japanese, in which the A.M. and P.M. designators differ in the second character instead of the first character. For cultures that do not use an A.M. designator, this property returns an empty string. @@ -657,7 +657,7 @@ property accepts only calendars that are valid for the culture that is associated with the object. The property specifies the calendars that can be used by a particular culture, and the property specifies the default calendar for the culture. + The property accepts only calendars that are valid for the culture that is associated with the object. The property specifies the calendars that can be used by a particular culture, and the property specifies the default calendar for the culture. Changing the value of this property affects the following properties as well: , , , , , , , , , , and . @@ -666,7 +666,7 @@ ## Examples - The following example defines a `ChangeCalendar` method that changes a culture's current calendar to a specified calendar unless it is already the current calendar or if it is not supported by the culture. The code that calls the method instantiates a object that represents the Arabic (Egypt) culture and first attempts to change its calendar to the Japanese calendar. Because the Japanese calendar is not supported, the method makes not change the culture's calendar. However, because the Umm al-Qura calendar is a member of the collection, the method does succeed in making it the current calendar for the ar-EG culture. + The following example defines a `ChangeCalendar` method that changes a culture's current calendar to a specified calendar unless it is already the current calendar or if it is not supported by the culture. The code that calls the method instantiates a object that represents the Arabic (Egypt) culture and first attempts to change its calendar to the Japanese calendar. Because the Japanese calendar is not supported, the method makes not change the culture's calendar. However, because the Umm al-Qura calendar is a member of the collection, the method does succeed in making it the current calendar for the ar-EG culture. [!code-csharp[System.Globalization.DateTimeFormatInfo.Calendar#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.Globalization.DateTimeFormatInfo.Calendar/cs/CalendarTest1.cs#1)] [!code-vb[System.Globalization.DateTimeFormatInfo.Calendar#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.Globalization.DateTimeFormatInfo.Calendar/vb/CalendarTest1.vb#1)] @@ -836,7 +836,7 @@ method displays the value of in place of the "/" in the result string. + If a custom format string includes the "/" format specifier, the method displays the value of in place of the "/" in the result string. The property defines the string that replaces the date separator ("/" custom date and time format specifier) in a result string in a formatting operation. It also defines the date separator string in a parsing operation. @@ -889,7 +889,7 @@ ## Remarks If setting this property, the array must be one-dimensional and must have exactly seven elements. The first element (the element at index zero) represents the first day of the week in the calendar defined by the property. - If a custom format string includes the "dddd" format specifier, the method includes the value of the appropriate member in place of "dddd" in the result string. + If a custom format string includes the "dddd" format specifier, the method includes the value of the appropriate member in place of "dddd" in the result string. This property is affected if the value of the property changes. @@ -1099,7 +1099,7 @@ ## Remarks The era name is the name a calendar uses to refer to a period of time reckoned from a fixed point or event. For example, "A.D." or "C.E." is the current era in the Gregorian calendar. - The valid values for `era` are listed in the property of the appropriate class derived from . For example: displays a list of eras that are supported by this implementation. + The valid values for `era` are listed in the property of the appropriate class derived from . For example: displays a list of eras that are supported by this implementation. In the class, the abbreviated era name is the first character of the full era name. This character is either the single-character case-insensitive Latin alphabet abbreviation or the single-character Kanji abbreviation. @@ -1206,20 +1206,20 @@ ## Remarks This method returns an array that contains all custom format strings that correspond to standard format strings. See [Standard Date and Time Format Strings](~/docs/standard/base-types/standard-date-and-time-format-strings.md) for a list of the standard format strings. - You can use the custom format strings in the array returned by the method in formatting operations. However, if you do, the string representation of a date and time value returned in that formatting operation cannot always be parsed successfully by the `Parse` and `TryParse` methods. Therefore, you cannot assume that the custom format strings returned by the method can be used to round-trip date and time values. The following example illustrates this problem. It retrieves a object that contains formatting information for the Italy (Italian) culture. It passes each custom format string in the array returned by the method to the method to create the string representation of a date and time. This example then attempts to parse this value by calling the method. As the output from the example shows, some of the custom format strings do not produce a date and time value that successfully round-trips. + You can use the custom format strings in the array returned by the method in formatting operations. However, if you do, the string representation of a date and time value returned in that formatting operation cannot always be parsed successfully by the `Parse` and `TryParse` methods. Therefore, you cannot assume that the custom format strings returned by the method can be used to round-trip date and time values. The following example illustrates this problem. It retrieves a object that contains formatting information for the Italy (Italian) culture. It passes each custom format string in the array returned by the method to the method to create the string representation of a date and time. This example then attempts to parse this value by calling the method. As the output from the example shows, some of the custom format strings do not produce a date and time value that successfully round-trips. [!code-csharp[System.Globalization.DateTimeFormatInfo.GetAllDateTimePatterns#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.getalldatetimepatterns/cs/getalldatetimepatternsex1.cs#1)] [!code-vb[System.Globalization.DateTimeFormatInfo.GetAllDateTimePatterns#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.getalldatetimepatterns/vb/getalldatetimepatternsex1.vb#1)] To parse the string representation of a date and time that can be expressed in a number of predefined custom formats, call one of the following methods: -- +- -- +- -- +- -- +- The custom format strings in the array returned by the method depends on the current calendar of the culture for which the object supplies formatting information. If the calendar changes, the array returned by this method also changes. @@ -1271,20 +1271,20 @@ ## Remarks This method returns an array containing the custom format strings that correspond to a particular standard format string. See [Standard Date and Time Format Strings](~/docs/standard/base-types/standard-date-and-time-format-strings.md) for a list of the standard format strings. - You can use the custom format strings in the array returned by the method in formatting operations. However, if you do, the string representation of a date and time value returned in that formatting operation cannot always be parsed successfully by the `Parse` and `TryParse` methods. Therefore, you cannot assume that the custom format strings returned by the method can be used to round-trip date and time values. The following example illustrates this problem. It retrieves a object that contains formatting information for the Russia (Russian) culture. It calls the method for each standard format string, and then passes each custom format string in the returned array to the method to create the string representation of a date and time. This example then attempts to parse this value by calling the method. As the output from the example shows, some of the custom format strings do not produce a date and time value that successfully round-trips. + You can use the custom format strings in the array returned by the method in formatting operations. However, if you do, the string representation of a date and time value returned in that formatting operation cannot always be parsed successfully by the `Parse` and `TryParse` methods. Therefore, you cannot assume that the custom format strings returned by the method can be used to round-trip date and time values. The following example illustrates this problem. It retrieves a object that contains formatting information for the Russia (Russian) culture. It calls the method for each standard format string, and then passes each custom format string in the returned array to the method to create the string representation of a date and time. This example then attempts to parse this value by calling the method. As the output from the example shows, some of the custom format strings do not produce a date and time value that successfully round-trips. [!code-csharp[System.Globalization.DateTimeFormatInfo.GetAllDateTimePatterns#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.getalldatetimepatterns/cs/getalldatetimepatternsex2.cs#2)] [!code-vb[System.Globalization.DateTimeFormatInfo.GetAllDateTimePatterns#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.datetimeformatinfo.getalldatetimepatterns/vb/getalldatetimepatternsex2.vb#2)] To parse the string representation of a date and time that can be expressed in a number of predefined custom formats, call one of the following methods: -- +- -- +- -- +- -- +- The custom format strings in the array returned by the method depends on the current calendar of the culture for which the object supplies formatting information. If the calendar changes, the array returned by this method also changes. @@ -1399,7 +1399,7 @@ The comparison with `eraName` is case-insensitive, for example, "A.D." is equivalent to "a.d.". - ignores punctuation in abbreviated era names, only if the is selected in and the culture uses "A.D." as the era name, that is, "A.D." is equivalent to "AD". + ignores punctuation in abbreviated era names, only if the is selected in and the culture uses "A.D." as the era name, that is, "A.D." is equivalent to "AD". compares `eraName` with the full era name returned by and with the abbreviated era name returned by . @@ -1457,7 +1457,7 @@ ## Remarks The era name is the name a calendar uses to refer to a period of time reckoned from a fixed point or event. For example, "A.D." or "C.E." is the current era in the Gregorian calendar. - The valid values for `era` are listed in the property of the appropriate class derived from . For example: displays a list of eras that are supported by this implementation. + The valid values for `era` are listed in the property of the appropriate class derived from . For example: displays a list of eras that are supported by this implementation. ]]> @@ -1505,7 +1505,7 @@ object is passed as the parameter. This method implements . + The `Format(String, IFormatProvider)` method supported by the base data types invoke this method when the current object is passed as the parameter. This method implements . ]]> @@ -1552,11 +1552,11 @@ method of `formatProvider` using an object as the `Type` parameter. If `formatProvider` is `null` or if returns `null`, this method returns . + This method uses the method of `formatProvider` using an object as the `Type` parameter. If `formatProvider` is `null` or if returns `null`, this method returns . Your application can get a object for a specific culture using one of the following methods: -- The property. +- The property. - The method, where `provider` is a object. @@ -1784,7 +1784,7 @@ property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "D" standard format string. The following example illustrates the relationships among the following: the "D" standard format string, the custom format string returned by the property, and the culture-specific representation of a date. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "D" standard format string. The following example illustrates the relationships among the following: the "D" standard format string, the custom format string returned by the property, and the culture-specific representation of a date. [!code-csharp[System.Globalization.DateTimeFormatInfo.LongDatePattern#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.DateTimeFormatInfo.LongDatePattern/CS/longdatepattern1.cs#2)] [!code-vb[System.Globalization.DateTimeFormatInfo.LongDatePattern#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.DateTimeFormatInfo.LongDatePattern/VB/longdatepattern1.vb#2)] @@ -1846,7 +1846,7 @@ property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "T" standard format string. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "T" standard format string. We recommend that you set the time separator in the long time pattern to an exact string instead of using the time separator placeholder. For example, to obtain the pattern h-mm-ss, set the long date pattern to "h-mm-ss". @@ -1898,7 +1898,7 @@ property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "m" and "M" standard format strings. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "m" and "M" standard format strings. This property is affected if the value of the property changes. @@ -2013,7 +2013,7 @@ If you set the property, you must also set the property. - If the custom pattern includes the format pattern "MMMM", displays the value of in place of the "MMMM" in the format pattern. + If the custom pattern includes the format pattern "MMMM", displays the value of in place of the "MMMM" in the format pattern. This property is affected if the value of the property changes. @@ -2104,7 +2104,7 @@ ## Remarks The property is used for all times from 12:00:00 (noon) to 23:59:59.999. - If the custom pattern includes the format pattern "tt" and the time is after noon, displays the value of in place of the "tt" in the format pattern. If the custom pattern includes the format pattern "t", only the first character of is displayed. Your application should use "tt" for languages for which it is necessary to maintain the distinction between AM and PM. An example is Japanese, for which the AM and PM designators differ in the second character instead of the first character. + If the custom pattern includes the format pattern "tt" and the time is after noon, displays the value of in place of the "tt" in the format pattern. If the custom pattern includes the format pattern "t", only the first character of is displayed. Your application should use "tt" for languages for which it is necessary to maintain the distinction between AM and PM. An example is Japanese, for which the AM and PM designators differ in the second character instead of the first character. For cultures that do not use a PM designator, this property returns an empty string. @@ -2192,7 +2192,7 @@ property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "r" and "R" standard format strings. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "r" and "R" standard format strings. The RFC1123 pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture. The custom format string is "ddd, dd MMM yyyy HH':'mm':'ss 'GMT'". @@ -2250,7 +2250,7 @@ The method defines the custom format strings that correspond to a particular standard date and time format string. If a call to a date and time formatting method includes the standard date and time format string specified by `format`, the method uses the first element in the `patterns` array to define the format of the resulting string. > [!WARNING] -> The `Parse` and `TryParse` methods do not fully iterate all strings in `patterns` when parsing the string representation of a date and time. If you require a date and time string to have particular formats in a parsing operation, you should pass the array of valid formats to the , , , or method. +> The `Parse` and `TryParse` methods do not fully iterate all strings in `patterns` when parsing the string representation of a date and time. If you require a date and time string to have particular formats in a parsing operation, you should pass the array of valid formats to the , , , or method. You can define custom format strings that correspond to the "d", "D", "t", "T", and "y" or "Y" standard date and time format strings. If the value of `format` is any other standard format string, the method throws an . @@ -2310,7 +2310,7 @@ property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "d" standard format string. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "d" standard format string. This property is affected if the value of the property changes. @@ -2416,7 +2416,7 @@ property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "t" standard format string. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "t" standard format string. We recommend that you set the time separator in the short time pattern to an exact string instead of using the time separator placeholder. For example, to obtain the pattern h-mm-ss, set the short time pattern to "h-mm-ss". @@ -2468,7 +2468,7 @@ property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "s" standard format string. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "s" standard format string. The format string returned by the property reflects a defined standard (ISO 8601), and the property is read-only. Therefore, it is always the same, regardless of the culture. The custom format string is "yyyy'-'MM'-'dd'T'HH':'mm':'ss". @@ -2513,7 +2513,7 @@ displays the value of in place of the ":" in the format pattern. + If the custom pattern includes the format pattern ":", displays the value of in place of the ":" in the format pattern. The time separator is derived from the property. We recommend that you set the time separator in short or long time patterns to an exact string instead of using the time separator placeholder. For example, to obtain the pattern h-mm-ss, set the pattern to "h-mm-ss". This practice also enables you to set patterns such as "h'h 'mm'm 'ss's'" (3h 36m 12s) that include multiple types of separators. The property defines the string that replaces the time separator (":" custom date and time format specifier) in a result string in a formatting operation. It also defines the time separator string in a parsing operation. @@ -2564,7 +2564,7 @@ property defines the format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "u" standard format string. It can be used to display dates and times in a sortable order with the universal time designator "Z" at the end. The format is sortable because it uses leading zeros for year, month, day, hour, minute, and second. The custom format string ("yyyy'-'MM'-'dd HH':'mm':'ss'Z'") is the same regardless of culture or format provider. + The property defines the format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "u" standard format string. It can be used to display dates and times in a sortable order with the universal time designator "Z" at the end. The format is sortable because it uses leading zeros for year, month, day, hour, minute, and second. The custom format string ("yyyy'-'MM'-'dd HH':'mm':'ss'Z'") is the same regardless of culture or format provider. The format string returned by the property reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture. The custom format string is "yyyy'-'MM'-'dd HH':'mm':'ss'Z'". @@ -2614,7 +2614,7 @@ property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "y" and "Y" standard format strings. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "y" and "Y" standard format strings. This property is affected if the value of the property changes. diff --git a/xml/System.Globalization/DateTimeStyles.xml b/xml/System.Globalization/DateTimeStyles.xml index 705ca18c3cfc9..8c63795bac9b4 100644 --- a/xml/System.Globalization/DateTimeStyles.xml +++ b/xml/System.Globalization/DateTimeStyles.xml @@ -38,25 +38,25 @@ ## Remarks values can be used with any of the following date and time parsing methods that include a `styles` parameter to define the interpretation of the style elements that may be present in the string to be parsed: -- +- -- +- -- +- -- +- -- +- -- +- -- +- -- +- The `ParseExact` and `TryParseExact` methods can use any of the values. However, if none of the `Allow*` values is selected, the input string must have exactly the same white-space characters as the format string. - If the input string does not contain any indication of the time zone, the date and time parsing methods interpret the value of the date and time string based on the time zone setting for the operating system. To convert the date and time to the Universal Time or Greenwich Mean Time (GMT), the application should use the AdjustToUniversal value. The same effect can be achieved by calling the or method. However, using the AdjustToUniversal value with the date and time parsing method is more efficient. + If the input string does not contain any indication of the time zone, the date and time parsing methods interpret the value of the date and time string based on the time zone setting for the operating system. To convert the date and time to the Universal Time or Greenwich Mean Time (GMT), the application should use the AdjustToUniversal value. The same effect can be achieved by calling the or method. However, using the AdjustToUniversal value with the date and time parsing method is more efficient. ]]> diff --git a/xml/System.Globalization/DaylightTime.xml b/xml/System.Globalization/DaylightTime.xml index 786c269439621..622c01e86c55a 100644 --- a/xml/System.Globalization/DaylightTime.xml +++ b/xml/System.Globalization/DaylightTime.xml @@ -33,7 +33,7 @@ Daylight saving time is a period during the year when the clock is advanced, usually by an hour, to take advantage of extended daylight hours. At the end of the period, the clock is set back to the standard time. > [!WARNING] -> The object returned by the method recognizes only the time zone adjustment rule that is currently in effect, and ignores any previous adjustment rules for which the system has information. Instead, it applies the current adjustment rule backward in time to periods when it may not have been in effect. To retrieve information about all the known adjustment rules for a particular time zone, use the method. +> The object returned by the method recognizes only the time zone adjustment rule that is currently in effect, and ignores any previous adjustment rules for which the system has information. Instead, it applies the current adjustment rule backward in time to periods when it may not have been in effect. To retrieve information about all the known adjustment rules for a particular time zone, use the method. ]]> @@ -105,7 +105,7 @@ property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. + This property corresponds to the property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. If the property value is positive, at the start of daylight saving time, the clock time is advanced by the length of time specified by this property. At the end of daylight saving time, the clock time is set back by the length of time specified by this property. If the property value is negative, the clock time is set back at the start of daylight saving time and advanced at the end. @@ -141,7 +141,7 @@ property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. + This property corresponds to the property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. When the daylight saving period ends, the clock time is set back to standard time. @@ -177,7 +177,7 @@ property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. + This property corresponds to the property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. When the daylight saving period begins, the clock time is advanced by the number of ticks defined by the property to take advantage of the extended daylight hours. diff --git a/xml/System.Globalization/EastAsianLunisolarCalendar.xml b/xml/System.Globalization/EastAsianLunisolarCalendar.xml index 045823be2d7f7..ff85f9bfd27f2 100644 --- a/xml/System.Globalization/EastAsianLunisolarCalendar.xml +++ b/xml/System.Globalization/EastAsianLunisolarCalendar.xml @@ -91,7 +91,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -151,7 +151,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] diff --git a/xml/System.Globalization/GregorianCalendar.xml b/xml/System.Globalization/GregorianCalendar.xml index 34b89f11fe96a..5cb8ad4e87065 100644 --- a/xml/System.Globalization/GregorianCalendar.xml +++ b/xml/System.Globalization/GregorianCalendar.xml @@ -55,7 +55,7 @@ Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application can set the property to a new . - ignores punctuation in abbreviated era names, only if the is selected in and the culture uses "A.D." as the era name, that is, "A.D." is equivalent to "AD". + ignores punctuation in abbreviated era names, only if the is selected in and the culture uses "A.D." as the era name, that is, "A.D." is equivalent to "AD". @@ -99,7 +99,7 @@ value is . If the property of the is set to a that is created with this constructor, the dates and times are localized in the language associated with the . + The default value is . If the property of the is set to a that is created with this constructor, the dates and times are localized in the language associated with the . @@ -191,7 +191,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -260,7 +260,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] diff --git a/xml/System.Globalization/GregorianCalendarTypes.xml b/xml/System.Globalization/GregorianCalendarTypes.xml index 2450b2f24f550..9bf11ad440f42 100644 --- a/xml/System.Globalization/GregorianCalendarTypes.xml +++ b/xml/System.Globalization/GregorianCalendarTypes.xml @@ -33,11 +33,11 @@ vary depending on the language. If the is selected in , can be used to specify which date and time patterns to use in that . + The date and time patterns associated with the vary depending on the language. If the is selected in , can be used to specify which date and time patterns to use in that . For Arabic cultures, more language versions of the Gregorian calendar are available. For example, you can use the French version of using the MiddleEastFrench value. - A culture that supports might not support all language versions of . The and properties specify the calendars supported by that culture. If is supported, can be used to determine which language versions of are supported. + A culture that supports might not support all language versions of . The and properties specify the calendars supported by that culture. If is supported, can be used to determine which language versions of are supported. diff --git a/xml/System.Globalization/HebrewCalendar.xml b/xml/System.Globalization/HebrewCalendar.xml index f649a823943d2..4e4f83001608f 100644 --- a/xml/System.Globalization/HebrewCalendar.xml +++ b/xml/System.Globalization/HebrewCalendar.xml @@ -64,7 +64,7 @@ The date January 1, 2001 A.D. in the Gregorian calendar is equivalent to the sixth day of Tevet in the year 5761 A.M. in the Hebrew calendar. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . @@ -154,7 +154,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -225,7 +225,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] diff --git a/xml/System.Globalization/HijriCalendar.xml b/xml/System.Globalization/HijriCalendar.xml index f280aad47ba77..ac383bfd9940f 100644 --- a/xml/System.Globalization/HijriCalendar.xml +++ b/xml/System.Globalization/HijriCalendar.xml @@ -64,7 +64,7 @@ This implementation of the class adjusts the calendar date by adding or subtracting a value from zero to two days to accommodate the variances in the start and the end of Ramadan and to accommodate the date difference between countries/regions. That value is stored in the property. If is not set explicitly, it derives its value from the settings in the regional and language options portion of Control Panel and is stored in the registry value HKEY_CURRENT_USER\Control Panel\International\AddHijriDate. However, that information can change during the life of the . The class does not detect changes in the system settings automatically. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -142,7 +142,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -211,7 +211,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] diff --git a/xml/System.Globalization/IdnMapping.xml b/xml/System.Globalization/IdnMapping.xml index 4cc6a4ae92b80..20153526dca3c 100644 --- a/xml/System.Globalization/IdnMapping.xml +++ b/xml/System.Globalization/IdnMapping.xml @@ -41,7 +41,7 @@ > > See [Unicode Technical Standard #46: IDNA Compatibility Processing](http://go.microsoft.com/fwlink/?LinkId=232459) for the differences in the way these standards handle particular sets of characters. - The method normalizes a domain name, converts the normalized name to a representation that consists of displayable Unicode characters in the US-ASCII code point range (U+0020 to U+007E), and prepends an ASCII-compatible encoding (ACE) prefix ("xn--") to each label. The method restores the domain name labels converted by the method. + The method normalizes a domain name, converts the normalized name to a representation that consists of displayable Unicode characters in the US-ASCII code point range (U+0020 to U+007E), and prepends an ASCII-compatible encoding (ACE) prefix ("xn--") to each label. The method restores the domain name labels converted by the method. If the string to be converted includes the label separator characters IDEOGRAPHIC FULL STOP (U+3002), FULLWIDTH FULL STOP (U+FF0E), and HALFWIDTH IDEOGRAPHIC FULL STOP (U+FF61), the method converts them to the label separator FULL STOP (period, U+002E). The method, however, does not restore the original label separator character. @@ -86,7 +86,7 @@ and properties are initialized to `false`. A small subset of ASCII characters other than A-Z, 0-9, the hyphen (-) character (U+002D), and the period (.) character are permitted in domain names, but unassigned Unicode code points are not. + The and properties are initialized to `false`. A small subset of ASCII characters other than A-Z, 0-9, the hyphen (-) character (U+002D), and the period (.) character are permitted in domain names, but unassigned Unicode code points are not. ]]> @@ -504,7 +504,7 @@ method. + For more information about domain names, labels, and label separators, see the remarks for the method. @@ -560,7 +560,7 @@ method. + For more information about domain names, labels, and label separators, see the remarks for the method. ]]> @@ -616,7 +616,7 @@ method. + For more information about domain names, labels, and label separators, see the remarks for the method. ]]> diff --git a/xml/System.Globalization/JapaneseCalendar.xml b/xml/System.Globalization/JapaneseCalendar.xml index 01acab660284f..2afff73d4f41a 100644 --- a/xml/System.Globalization/JapaneseCalendar.xml +++ b/xml/System.Globalization/JapaneseCalendar.xml @@ -75,9 +75,9 @@ The date January 1, 2001 A.D. in the Gregorian calendar is equivalent to the first day of Ichigatsu in the year Heisei 13 in the Japanese calendar. - If the application is using the class, recognizes the era abbreviations in front of the year. The abbreviation is either the single-character case-insensitive Latin alphabet abbreviation or the single-character Kanji abbreviation. + If the application is using the class, recognizes the era abbreviations in front of the year. The abbreviation is either the single-character case-insensitive Latin alphabet abbreviation or the single-character Kanji abbreviation. - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -156,7 +156,7 @@ If `months` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -225,7 +225,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] @@ -896,11 +896,11 @@ ## Remarks This method can be used to determine the number of weeks in the year by setting the `time` parameter to the last day of the year. - The property contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. + The property contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. - The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . - The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . For example, in , the method for January 1 returns 1. @@ -1391,7 +1391,7 @@ . + This method implements . Because the year in the Japanese calendar is typically less than four digits long, this implementation always returns the value of the `year` parameter. @@ -1435,7 +1435,7 @@ . + This property implements . Because the year in the Japanese calendar is typically less than four digits long, this implementation returns 99 by default and does not affect the return value of . diff --git a/xml/System.Globalization/JapaneseLunisolarCalendar.xml b/xml/System.Globalization/JapaneseLunisolarCalendar.xml index 860bb40410e16..b6407c72ff932 100644 --- a/xml/System.Globalization/JapaneseLunisolarCalendar.xml +++ b/xml/System.Globalization/JapaneseLunisolarCalendar.xml @@ -38,7 +38,7 @@ Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Japanese lunisolar calendar. - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> diff --git a/xml/System.Globalization/JulianCalendar.xml b/xml/System.Globalization/JulianCalendar.xml index bd765bb769652..fccce90c80aca 100644 --- a/xml/System.Globalization/JulianCalendar.xml +++ b/xml/System.Globalization/JulianCalendar.xml @@ -49,7 +49,7 @@ Currently, the is not used by any of the cultures supported by the class. Therefore, the class can be used only to calculate dates in the Julian calendar. - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -127,7 +127,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -196,7 +196,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] diff --git a/xml/System.Globalization/KoreanCalendar.xml b/xml/System.Globalization/KoreanCalendar.xml index 53fa9c3f85b27..079ecfc0131b3 100644 --- a/xml/System.Globalization/KoreanCalendar.xml +++ b/xml/System.Globalization/KoreanCalendar.xml @@ -64,7 +64,7 @@ The date January 1, 2001 A.D. in the Gregorian calendar is equivalent to the first day of January in the year 4334 of the current era in the Korean calendar. - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -143,7 +143,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -211,7 +211,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] @@ -687,7 +687,7 @@ method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + In a calendar that supports the notion of a leap month, the leap month can occur either after a particular month or after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. ]]> @@ -840,11 +840,11 @@ ## Remarks This method can be used to determine the number of weeks in the year by setting the `time` parameter to the last day of the year. - contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. + contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. - The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . - The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . For example, in , for January 1 returns 1. diff --git a/xml/System.Globalization/KoreanLunisolarCalendar.xml b/xml/System.Globalization/KoreanLunisolarCalendar.xml index 7006f7f9724b5..3a58d457a6d4c 100644 --- a/xml/System.Globalization/KoreanLunisolarCalendar.xml +++ b/xml/System.Globalization/KoreanLunisolarCalendar.xml @@ -36,11 +36,11 @@ The class calculates years using the Gregorian calendar, and days and months using the class. - A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Korean lunisolar calendar. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> diff --git a/xml/System.Globalization/NumberFormatInfo.xml b/xml/System.Globalization/NumberFormatInfo.xml index 0ad71a1976b50..24366f031a666 100644 --- a/xml/System.Globalization/NumberFormatInfo.xml +++ b/xml/System.Globalization/NumberFormatInfo.xml @@ -80,7 +80,7 @@ ## Instantiating a NumberFormatInfo object for the current culture You can instantiate a object for the current thread culture in any of the following ways. In each case, the returned object is read-only. -- By retrieving a object that represents the current thread culture from the property, and retrieving the object from its property. +- By retrieving a object that represents the current thread culture from the property, and retrieving the object from its property. - By retrieving the object returned by the `static` (`Shared` in Visual Basic) property. @@ -95,19 +95,19 @@ - By retrieving a object in any of the ways illustrated in the previous code example, and calling the method on the returned object. This creates a copy of the original object, except that its property is `false`. -- By calling the method to create a object that represents the current culture, and then using its property to retrieve the object. +- By calling the method to create a object that represents the current culture, and then using its property to retrieve the object. The following example illustrates these two ways of instantiating a object, and displays the value of its property to illustrate that the object is not read-only. [!code-csharp[System.Globalization.NumberFormatInfo.Class.Instantiate#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class.instantiate/cs/instantiate2.cs#2)] [!code-vb[System.Globalization.NumberFormatInfo.Class.Instantiate#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class.instantiate/vb/instantiate2.vb#2)] - Note that the Windows operating system allows the user to override some of the property values used in numeric formatting and parsing operations through the **Region and Language** item in Control Panel. For example, a user whose culture is English (United States) might choose to display currency values as 1.1 USD instead of the default of $1.1. The objects retrieved in the ways discussed previously all reflect these user overrides. If this is undesirable, you can create a object that does not reflect user overrides (and that is also read/write rather than read-only) by calling the constructor and supplying a value of `false` for the `useUserOverride` argument. The following example provides an illustration for a system whose current culture is English (United States) and whose currency symbol has been changed from the default of $ to USD. + Note that the Windows operating system allows the user to override some of the property values used in numeric formatting and parsing operations through the **Region and Language** item in Control Panel. For example, a user whose culture is English (United States) might choose to display currency values as 1.1 USD instead of the default of $1.1. The objects retrieved in the ways discussed previously all reflect these user overrides. If this is undesirable, you can create a object that does not reflect user overrides (and that is also read/write rather than read-only) by calling the constructor and supplying a value of `false` for the `useUserOverride` argument. The following example provides an illustration for a system whose current culture is English (United States) and whose currency symbol has been changed from the default of $ to USD. [!code-csharp[System.Globalization.NumberFormatInfo.Class.Instantiate#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class.instantiate/cs/instantiate3.cs#3)] [!code-vb[System.Globalization.NumberFormatInfo.Class.Instantiate#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class.instantiate/vb/instantiate3.vb#3)] - If the property is set to `true`, the properties , , and are also retrieved from the user settings. If the user settings are incompatible with the culture associated with the object (for example, if the selected calendar is not one of the calendars listed by the property), the results of the methods and the values of the properties are undefined. + If the property is set to `true`, the properties , , and are also retrieved from the user settings. If the user settings are incompatible with the culture associated with the object (for example, if the selected calendar is not one of the calendars listed by the property), the results of the methods and the values of the properties are undefined. ## Instantiating a NumberFormatInfo object for the invariant culture @@ -117,7 +117,7 @@ - By retrieving the value of the property. The returned object is read-only. -- By retrieving the value of the property from the object that is returned by the property. The returned object is read-only. +- By retrieving the value of the property from the object that is returned by the property. The returned object is read-only. - By calling the parameterless class constructor. The returned object is read/write. @@ -130,13 +130,13 @@ ## Instantiating a NumberFormatInfo object for a specific culture A specific culture represents a language that is spoken in a particular country/region. For example, en-US is a specific culture that represents the English language spoken in the United States, and en-CA is a specific culture that represents the English language spoken in Canada. You can instantiate a object that represents the formatting conventions of a specific culture in the following ways: -- By calling the method and retrieving the value of the returned object's property. The returned object is read-only. +- By calling the method and retrieving the value of the returned object's property. The returned object is read-only. - By passing a object that represents the culture whose object you want to retrieve to the static method. The returned object is read/write. -- By calling the method and retrieving the value of the returned object's property. The returned object is read/write. +- By calling the method and retrieving the value of the returned object's property. The returned object is read/write. -- By calling one of the class constructors and retrieving the value of the returned object's property. The returned object is read/write. +- By calling one of the class constructors and retrieving the value of the returned object's property. The returned object is read/write. The following example uses these four ways to create a object that reflects the formatting conventions of the Indonesian (Indonesia) culture. It also indicates whether each object is read-only. @@ -167,7 +167,7 @@ - **Cascading changes to property values.** A number of culture-related properties can change at run time, which, in turn, causes data to change. For example, the current culture can be changed either programmatically or through user action. When this happens, the object returned by the property changes to an object associated with the current culture. -- **User preferences.** Users of your application might override some of the values associated with the current system culture through the region and language options in Control Panel. For example, users might choose a different currency symbol or a different decimal separator symbol. If the property is set to `true` (its default value), the properties of the object are also retrieved from the user settings. +- **User preferences.** Users of your application might override some of the values associated with the current system culture through the region and language options in Control Panel. For example, users might choose a different currency symbol or a different decimal separator symbol. If the property is set to `true` (its default value), the properties of the object are also retrieved from the user settings. Starting with the .NET Framework 2.0, all user-overridable properties of a object are initialized when the object is created. There is still a possibility of inconsistency, because neither object creation nor the user override process is atomic, and the relevant values may change during object creation. However, these inconsistencies should be extremely rare. @@ -176,11 +176,11 @@ |Source of CultureInfo and NumberFormatInfo object|Reflects user overrides| |-------------------------------------------------------|-----------------------------| |`CultureInfo.CurrentCulture.NumberFormat` property|Yes| -| property|Yes| -| method|Yes| -| method|No| +| property|Yes| +| method|Yes| +| method|No| | constructor|Yes| -| constructor|Depends on value of `useUserOverride` parameter| +| constructor|Depends on value of `useUserOverride` parameter| Unless there is a compelling reason to do otherwise, you should respect user overrides when you use the object in client applications to format and parse user input or to display numeric data. For server applications or unattended applications, you should not respect user overrides. However, if you are using the object either explicitly or implicitly to persist numeric data in string form, you should either use a object that reflects the formatting conventions of the invariant culture, or you should specify a custom numeric format string that you use regardless of culture. @@ -188,21 +188,21 @@ ## IFormatProvider, NumberFormatInfo, and numeric formatting A object is used implicitly or explicitly in all numeric formatting operations. These include calls to the following methods: -- All numeric formatting methods, such as , , and . +- All numeric formatting methods, such as , , and . -- The major composite formatting method, . +- The major composite formatting method, . -- Other composite formatting methods, such as and . +- Other composite formatting methods, such as and . All numeric formatting operations make use of an implementation. The interface includes a single method, . This is a callback method that is passed a object that represents the type needed to provide formatting information. The method is responsible for returning either an instance of that type or `null`, if it cannot provide an instance of the type. The .NET Framework provides two implementations for formatting numbers: -- The class, which represents a specific culture (or a specific language in a specific country/region). In a numeric formatting operation, the method returns the object associated with its property. +- The class, which represents a specific culture (or a specific language in a specific country/region). In a numeric formatting operation, the method returns the object associated with its property. -- The class, which provides information about the formatting conventions of its associated culture. The method returns an instance of itself. +- The class, which provides information about the formatting conventions of its associated culture. The method returns an instance of itself. - If an implementation is not provided to a formatting method explicitly, a object returned by the property that represents the current thread culture is used. + If an implementation is not provided to a formatting method explicitly, a object returned by the property that represents the current thread culture is used. - The following example illustrates the relationship between the interface and the class in formatting operations by defining a custom implementation. Its method displays the type name of the object requested by the formatting operation. If the interface is requesting a object, this method provides the object for the current thread culture. As the output from the example shows, the method requests a object to provide formatting information, whereas the method requests and objects as well as an implementation. + The following example illustrates the relationship between the interface and the class in formatting operations by defining a custom implementation. Its method displays the type name of the object requested by the formatting operation. If the interface is requesting a object, this method provides the object for the current thread culture. As the output from the example shows, the method requests a object to provide formatting information, whereas the method requests and objects as well as an implementation. [!code-csharp[System.Globalization.NumberFormatInfo.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class/cs/formatprovider1.cs#1)] [!code-vb[System.Globalization.NumberFormatInfo.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class/vb/formatprovider1.vb#1)] @@ -211,12 +211,12 @@ ## Format strings and NumberFormatInfo properties - Every formatting operation uses either a standard or a custom numeric format string to produce a result string from a number. In some cases, the use of a format string to produce a result string is explicit, as in the following example. This code calls the method to convert a value to a number of different string representations by using the formatting conventions of the en-US culture. + Every formatting operation uses either a standard or a custom numeric format string to produce a result string from a number. In some cases, the use of a format string to produce a result string is explicit, as in the following example. This code calls the method to convert a value to a number of different string representations by using the formatting conventions of the en-US culture. [!code-csharp[System.Globalization.NumberFormatInfo.Class#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class/cs/properties1.cs#2)] [!code-vb[System.Globalization.NumberFormatInfo.Class#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class/vb/properties1.vb#2)] - In other cases, the use of a format string is implicit. For example, in the following method calls to the default or parameterless method, the value of the instance is formatted by using the general ("G") format specifier and the conventions of the current culture, which in this case is the en-US culture. + In other cases, the use of a format string is implicit. For example, in the following method calls to the default or parameterless method, the value of the instance is formatted by using the general ("G") format specifier and the conventions of the current culture, which in this case is the en-US culture. [!code-csharp[System.Globalization.NumberFormatInfo.Class#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class/cs/properties2.cs#3)] [!code-vb[System.Globalization.NumberFormatInfo.Class#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.numberformatinfo.class/vb/properties2.vb#3)] @@ -277,7 +277,7 @@ The parsing methods implicitly or explicitly use a enumeration value to determine what style elements (such as group separators, a decimal separator, or a currency symbol) can be present in a string if the parsing operation is to succeed. If a value is not provided in the method call, the default is a value that includes the and flags, which specifies that the parsed string can include group symbols, a decimal separator, a negative sign, and white-space characters, or it can be the string representation of a number in exponential notation. - The parsing methods also implicitly or explicitly use a object that defines the specific symbols and patterns that can occur in the string to be parsed. If a object is not provided, the default is the for the current thread culture. For more information about parsing, see the individual parsing methods, such as , , , , , and . + The parsing methods also implicitly or explicitly use a object that defines the specific symbols and patterns that can occur in the string to be parsed. If a object is not provided, the default is the for the current thread culture. For more information about parsing, see the individual parsing methods, such as , , , , , and . The following example illustrates the culture-sensitive nature of parsing strings. It tries to parse a string that include thousands separators by using the conventions of the en-US, fr-FR, and invariant cultures. A string that includes the comma as a group separator and the period as a decimal separator fails to parse in the fr-FR culture, and a string with white space as a group separator and a comma as a decimal separator fails to parse in the en-US and invariant cultures. @@ -917,7 +917,7 @@ is passed as the parameter. This method implements . + The `Format(String, IFormatProvider)` methods supported by the base data types invoke this method when the current is passed as the parameter. This method implements . ]]> @@ -964,11 +964,11 @@ method of `formatProvider` using as the Type parameter. If `formatProvider` is `null` or if returns `null`, this method returns . + This method uses the method of `formatProvider` using as the Type parameter. If `formatProvider` is `null` or if returns `null`, this method returns . Your application gets a object for a specific culture using one of the following methods: -- Through the property. +- Through the property. - Through the method where `provider` is a . diff --git a/xml/System.Globalization/NumberStyles.xml b/xml/System.Globalization/NumberStyles.xml index 81b8ea461301e..8825046cea308 100644 --- a/xml/System.Globalization/NumberStyles.xml +++ b/xml/System.Globalization/NumberStyles.xml @@ -44,7 +44,7 @@ Except for AllowHexSpecifier, the individual field flags in the enumeration define style elements that are used when parsing the string representation of a decimal number. None indicates that only digits can be present in the parsed string. The remaining individual field flags define style elements that may be, but do not have to be, present in the string representation of a decimal number for the parse operation to succeed. In contrast, the AllowHexSpecifier flag indicates that the string to be parsed is always interpreted as a hexadecimal value. The only individual field flags that can be used with AllowHexSpecifier are AllowLeadingWhite and AllowTrailingWhite. The enumeration includes a composite number style, HexNumber, that consists of all three flags. - The symbols (such as the currency symbol, the group separator, the decimal separator, and the positive and negative signs) that can appear in the string to be parsed are defined by the members of the object that is passed either implicitly or explicitly to the `Parse` method. The members table in this topic provides a description of each individual flag and indicates its relationship to properties. + The symbols (such as the currency symbol, the group separator, the decimal separator, and the positive and negative signs) that can appear in the string to be parsed are defined by the members of the object that is passed either implicitly or explicitly to the `Parse` method. The members table in this topic provides a description of each individual flag and indicates its relationship to properties. The following table lists the composite number styles and indicates which individual field flags they include. A "1" in a cell indicates that the composite number style includes the individual number style in that row. A "0" indicates that the composite number style does not include the individual number style. diff --git a/xml/System.Globalization/PersianCalendar.xml b/xml/System.Globalization/PersianCalendar.xml index d5ca2b588c57b..eb6558657727f 100644 --- a/xml/System.Globalization/PersianCalendar.xml +++ b/xml/System.Globalization/PersianCalendar.xml @@ -58,12 +58,12 @@ ## Using the PersianCalendar class Applications use a object to calculate dates in the Persian calendar or convert Persian dates to and from Gregorian dates. - You cannot use a object as the default calendar for a culture. The default calendar is specified by the property and must be one of the calendars returned by the property. Currently, the class is not an optional calendar for any culture supported by the class and consequently cannot be a default calendar. + You cannot use a object as the default calendar for a culture. The default calendar is specified by the property and must be one of the calendars returned by the property. Currently, the class is not an optional calendar for any culture supported by the class and consequently cannot be a default calendar. ## Examples - The following example instantiates objects by using the property, a constructor, and the Persian calendar's method. It then displays these dates in both the Gregorian and Persian calendars. It also displays the date range of the Persian calendar. + The following example instantiates objects by using the property, a constructor, and the Persian calendar's method. It then displays these dates in both the Gregorian and Persian calendars. It also displays the date range of the Persian calendar. [!code-csharp[sys.glob.PersianCal#3](~/samples/snippets/csharp/VS_Snippets_CLR/sys.glob.persianCal/cs/calendar2.cs#3)] [!code-vb[sys.glob.PersianCal#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/sys.glob.persianCal/vb/calendar2.vb#3)] @@ -153,7 +153,7 @@ property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -211,7 +211,7 @@ property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] diff --git a/xml/System.Globalization/RegionInfo.xml b/xml/System.Globalization/RegionInfo.xml index 787fb729b66c2..5b0c39b0e1955 100644 --- a/xml/System.Globalization/RegionInfo.xml +++ b/xml/System.Globalization/RegionInfo.xml @@ -512,7 +512,7 @@ . + This method overrides . @@ -611,7 +611,7 @@ . + This method overrides . This method generates the same hash code for two objects that are equal according to the method. @@ -862,9 +862,9 @@ object is created with the constructor that takes a culture identifier parameter, the property value is one of the two-letter codes defined in ISO 3166 for the country/region and is formatted in uppercase. For example, the two-letter code for the United States is "US". + If the current object is created with the constructor that takes a culture identifier parameter, the property value is one of the two-letter codes defined in ISO 3166 for the country/region and is formatted in uppercase. For example, the two-letter code for the United States is "US". - If the current object is created with the constructor and is passed a full culture name such as "en-US", the property value is a full culture name and not just the region name. + If the current object is created with the constructor and is passed a full culture name such as "en-US", the property value is a full culture name and not just the region name. @@ -1058,7 +1058,7 @@ . + This method overrides . This method returns the value of the property. diff --git a/xml/System.Globalization/SortKey.xml b/xml/System.Globalization/SortKey.xml index cf4ab6ce6122f..78095d048d060 100644 --- a/xml/System.Globalization/SortKey.xml +++ b/xml/System.Globalization/SortKey.xml @@ -32,29 +32,29 @@ ## Remarks A culture-sensitive comparison of two strings depends on each character in the strings having several categories of sort weights, including script, alphabetic, case, and diacritic weights. A sort key serves as the repository of these weights for a particular string. - The method returns an instance of the class that reflects the culture-sensitive mapping of characters in a specified string. The value of a object is its key data, which is returned by the property. This key data consists of a series of bytes that encode the string, culture-specific sorting rules, and user-specified comparison options. A comparison using sort keys consists of a bitwise comparison of the corresponding key data in each sort key. For example, if you create a sort key by calling the method with a value of , a string comparison operation that uses the sort key is case-insensitive. + The method returns an instance of the class that reflects the culture-sensitive mapping of characters in a specified string. The value of a object is its key data, which is returned by the property. This key data consists of a series of bytes that encode the string, culture-specific sorting rules, and user-specified comparison options. A comparison using sort keys consists of a bitwise comparison of the corresponding key data in each sort key. For example, if you create a sort key by calling the method with a value of , a string comparison operation that uses the sort key is case-insensitive. - After you create a sort key for a string, you compare sort keys by calling the static method. This method performs a simple byte-by-byte comparison, so it is much faster than the or method. + After you create a sort key for a string, you compare sort keys by calling the static method. This method performs a simple byte-by-byte comparison, so it is much faster than the or method. ## Performance considerations - When performing a string comparison, the and methods yield the same results, but they target different scenarios. + When performing a string comparison, the and methods yield the same results, but they target different scenarios. - At a high level, the method generates the sort key for each string, performs the comparison, and then discards the sort key and returns the result of the comparison. However, the method actually doesn't generate an entire sort key to perform the comparison. Instead, the method generates the key data for each text element (that is, base character, surrogate pair, or combining character sequence) in each string. The method then compares the key data for the corresponding text elements. The operation terminates as soon as the ultimate result of the comparison is determined. Sort key information is computed, but no object is created. This strategy is economical in terms of performance if both strings are compared once, but becomes expensive if the same strings are compared many times. + At a high level, the method generates the sort key for each string, performs the comparison, and then discards the sort key and returns the result of the comparison. However, the method actually doesn't generate an entire sort key to perform the comparison. Instead, the method generates the key data for each text element (that is, base character, surrogate pair, or combining character sequence) in each string. The method then compares the key data for the corresponding text elements. The operation terminates as soon as the ultimate result of the comparison is determined. Sort key information is computed, but no object is created. This strategy is economical in terms of performance if both strings are compared once, but becomes expensive if the same strings are compared many times. The method requires generation of a object for each string before performing the comparison. This strategy is expensive in terms of performance for the first comparison because of the time and memory invested to generate the objects. However, it becomes economical if the same sort keys are compared many times. For example, suppose you write an application that searches a database table for the row in which the string-based index column matches a specified search string. The table contains thousands of rows, and comparing the search string to the index in each row will take a long time. Therefore, when the application stores a row and its index column, it also generates and stores the sort key for the index in a column dedicated to improving search performance. When the application searches for a target row, it compares the sort key for the search string to the sort key for the index string, instead of comparing the search string to the index string. ## Security considerations - The method returns a object with the value based on a specified string and value, and the culture associated with the underlying object. If a security decision depends on a string comparison or case change, you should use the method of the invariant culture to ensure that the behavior of the operation is consistent, regardless of the culture settings of the operating system. + The method returns a object with the value based on a specified string and value, and the culture associated with the underlying object. If a security decision depends on a string comparison or case change, you should use the method of the invariant culture to ensure that the behavior of the operation is consistent, regardless of the culture settings of the operating system. Use the following steps to obtain a sort key: -1. Retrieve the invariant culture from the property. +1. Retrieve the invariant culture from the property. -2. Retrieve a object for the invariant culture from the property. +2. Retrieve a object for the invariant culture from the property. -3. Call the method. +3. Call the method. Working with the value of a object is equivalent to calling the Windows `LCMapString` method with the LCMAP_SORTKEY value specified. However, for the object, the sort keys for English characters precede the sort keys for Korean characters. @@ -71,7 +71,7 @@ [!code-csharp[System.Globalization.SortKey.Compare#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Globalization.SortKey.Compare/CS/sortkey_compare.cs#1)] [!code-vb[System.Globalization.SortKey.Compare#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.SortKey.Compare/VB/sortkey_compare.vb#1)] - The following example shows how you can use the class to improve performance in an application that relies extensively on sorting and searching a large array. The example creates an unordered array of names, which in this case has 13 elements. It then stores the sort key of each name in a parallel array, which it passes to the method. The result is a sorted array. The example then searches the array for three strings. For each search string, it calls the method to retrieve the string's sort key, and then calls the method to retrieve the index of that sort key in the array of sort keys. Because the name and sort key arrays are parallel, the returned index is also the index of the name in the `names` array. + The following example shows how you can use the class to improve performance in an application that relies extensively on sorting and searching a large array. The example creates an unordered array of names, which in this case has 13 elements. It then stores the sort key of each name in a parallel array, which it passes to the method. The result is a sorted array. The example then searches the array for three strings. For each search string, it calls the method to retrieve the string's sort key, and then calls the method to retrieve the index of that sort key in the array of sort keys. Because the name and sort key arrays are parallel, the returned index is also the index of the name in the `names` array. [!code-csharp[System.Globalization.SortKey.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.sortkey.class/cs/sortkey1.cs#1)] [!code-vb[System.Globalization.SortKey.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.sortkey.class/vb/sortkey1.vb#1)] @@ -132,14 +132,14 @@ method compares the properties of the `sortkey1` and `sortkey2` parameters. The method yields the same results as the method. + The method compares the properties of the `sortkey1` and `sortkey2` parameters. The method yields the same results as the method. For more information about the method and the comparison of sort keys, see the class topic. ## Examples - The following code example compares two strings using the method and the equivalent method. + The following code example compares two strings using the method and the equivalent method. [!code-csharp[sys.glob.sortkey.compare#1](~/samples/snippets/csharp/VS_Snippets_CLR/sys.glob.sortkey.compare/cs/skcmp.cs#1)] [!code-vb[sys.glob.sortkey.compare#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/sys.glob.sortkey.compare/vb/skcmp.vb#1)] @@ -185,7 +185,7 @@ ## Remarks Two objects are considered equal if their properties are equal. - This method overrides . + This method overrides . @@ -233,7 +233,7 @@ ## Remarks This method generates the same hash code for two objects that are equal according to the method. - This method overrides . + This method overrides . ]]> @@ -349,7 +349,7 @@ ## Remarks The return value is the concatenation of the string "SortKey - ", the culture identifier and compare options of the current object, and the value of the property. - This method overrides . + This method overrides . diff --git a/xml/System.Globalization/SortVersion.xml b/xml/System.Globalization/SortVersion.xml index a3ff78f4c906f..b271b406009c7 100644 --- a/xml/System.Globalization/SortVersion.xml +++ b/xml/System.Globalization/SortVersion.xml @@ -51,7 +51,7 @@ - By calling the constructor, which instantiates a new object based on a version number and sort ID. This constructor is most useful when recreating a object from saved data. -- By retrieving the value of the property. This property provides information about the Unicode version used by the .NET Framework on which the application is running. +- By retrieving the value of the property. This property provides information about the Unicode version used by the .NET Framework on which the application is running. The class has two properties, and , that indicate the Unicode version and the specific culture used for string comparison. The property is an arbitrary numeric value that reflects the Unicode version used for string comparison, and the property is an arbitrary that reflects the culture whose conventions are used for string comparison. The values of these two properties are important only when you compare two objects by using the method, the operator, or the operator. diff --git a/xml/System.Globalization/StringInfo.xml b/xml/System.Globalization/StringInfo.xml index 8c82ba4df841d..7f6fe9f5dc439 100644 --- a/xml/System.Globalization/StringInfo.xml +++ b/xml/System.Globalization/StringInfo.xml @@ -597,7 +597,7 @@ ## Remarks When a object is instantiated, its property is set to one of the following values: -- if the default is called. You should then use the property to assign the string that this object rperesents. +- if the default is called. You should then use the property to assign the string that this object rperesents. - The string supplied as the `value` argument to the constructor. diff --git a/xml/System.Globalization/TaiwanCalendar.xml b/xml/System.Globalization/TaiwanCalendar.xml index 364ed921aea0b..1b94691bf8bf0 100644 --- a/xml/System.Globalization/TaiwanCalendar.xml +++ b/xml/System.Globalization/TaiwanCalendar.xml @@ -62,7 +62,7 @@ The date January 1, 2001 C.E. in the Gregorian calendar is equivalent to the first day of January in the year 90 of the current era in the Taiwan calendar. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -144,7 +144,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -213,7 +213,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] @@ -841,11 +841,11 @@ ## Remarks This method can be used to determine the number of weeks in the year by setting the `time` parameter to the last day of the year. - The property contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. + The property contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. - The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . - The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . For example, in , the method for January 1 returns 1. @@ -1329,7 +1329,7 @@ . + This method implements . Because the year in the Taiwan calendar is typically less than four digits long, this implementation always returns the value of the `year` parameter. @@ -1373,7 +1373,7 @@ . + This property implements . Because the year in the Taiwan calendar is typically less than four digits long, this implementation returns 99 by default and does not affect the return value of . diff --git a/xml/System.Globalization/TaiwanLunisolarCalendar.xml b/xml/System.Globalization/TaiwanLunisolarCalendar.xml index b868b3303a355..a09b620751f19 100644 --- a/xml/System.Globalization/TaiwanLunisolarCalendar.xml +++ b/xml/System.Globalization/TaiwanLunisolarCalendar.xml @@ -36,11 +36,11 @@ The class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. - A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Taiwan lunisolar calendar. - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> diff --git a/xml/System.Globalization/TextElementEnumerator.xml b/xml/System.Globalization/TextElementEnumerator.xml index 87637ff36bb0c..c2c73e15c7cb6 100644 --- a/xml/System.Globalization/TextElementEnumerator.xml +++ b/xml/System.Globalization/TextElementEnumerator.xml @@ -49,7 +49,7 @@ The class allows you to work with the text elements in a string rather than with single objects. - You instantiate a object that represents a particular string by passing the string to the method. This returns an enumerator that is positioned before the first text element in the string. Calling the method also brings the enumerator back to this position. Because this represents an invalid state, you must call to advance the enumerator to the first text element of the string before reading the value of the property to return the current text element. + You instantiate a object that represents a particular string by passing the string to the method. This returns an enumerator that is positioned before the first text element in the string. Calling the method also brings the enumerator back to this position. Because this represents an invalid state, you must call to advance the enumerator to the first text element of the string before reading the value of the property to return the current text element. When working with a object, you are responsible for positioning the enumerator. The property returns the same text element until you call either or . The enumerator is in an invalid state if it is positioned before the first text element or after the last text element in the string. When the enumerator is in an invalid state, attempting to retrieve the value of the property throws an exception. You can determine whether the enumerator is in an invalid state by testing whether the return value of the property is `false`. @@ -61,7 +61,7 @@ - A object enumerates the text elements present in the string at the time that the object was instantiated. It does not reflect any subsequent changes to the string variable if that variable is modified afterward. -- Because the class does not override , two objects that represent the same string will be considered unequal. +- Because the class does not override , two objects that represent the same string will be considered unequal. diff --git a/xml/System.Globalization/TextInfo.xml b/xml/System.Globalization/TextInfo.xml index c245f1d14e957..c32b3574ddfb0 100644 --- a/xml/System.Globalization/TextInfo.xml +++ b/xml/System.Globalization/TextInfo.xml @@ -44,10 +44,10 @@ ## Remarks A writing system is the collection of scripts and orthographic rules required to represent a language as text. The class represents a writing system. - The application should use the property to obtain the object for a particular object. If a security decision depends on a string comparison or a case-change operation, the application should use the property of the object returned by the property to ensure that the behavior of the operation is consistent regardless of the operating system culture settings. + The application should use the property to obtain the object for a particular object. If a security decision depends on a string comparison or a case-change operation, the application should use the property of the object returned by the property to ensure that the behavior of the operation is consistent regardless of the operating system culture settings. ## Overrides - The user might use the regional and language options portion of Control Panel to override the values associated with the current culture of Windows. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the property is set to `true`, the property values of the objects returned by the , , and properties are also retrieved from the user settings. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + The user might use the regional and language options portion of Control Panel to override the values associated with the current culture of Windows. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the property is set to `true`, the property values of the objects returned by the , , and properties are also retrieved from the user settings. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. ]]> @@ -168,9 +168,9 @@ ## Remarks A object is created from a specific culture, and the property returns the name of that culture. - The property always reflects a specific culture rather than a neutral culture. If has a neutral culture as its value, then the corresponding has as its value an arbitrary specific culture that uses the same language. For example, the property returns "en" for the English neutral culture, but the corresponding property might return "en-US" for the English (United States) culture. If the object is associated with a specific culture instead of a neutral culture, the value of its property is always identical to the property value of its associated object. + The property always reflects a specific culture rather than a neutral culture. If has a neutral culture as its value, then the corresponding has as its value an arbitrary specific culture that uses the same language. For example, the property returns "en" for the English neutral culture, but the corresponding property might return "en-US" for the English (United States) culture. If the object is associated with a specific culture instead of a neutral culture, the value of its property is always identical to the property value of its associated object. - Similarly, the property never reflects a particular sort. It always corresponds to a default sort order. For example, the default sort order for Spanish (Spain) is the international sort order. If is es-ES_tradnl (Spanish with the traditional sort order) then the corresponding is es-ES (Spanish with the default international sort order). + Similarly, the property never reflects a particular sort. It always corresponds to a default sort order. For example, the default sort order for Spanish (Spain) is the international sort order. If is es-ES_tradnl (Spanish with the traditional sort order) then the corresponding is es-ES (Spanish with the default international sort order). ]]> @@ -241,7 +241,7 @@ . + This method overrides . ]]> @@ -281,7 +281,7 @@ . + This method overrides . This method generates the same hash code for two objects that are equal according to the method. @@ -411,11 +411,11 @@ namespace, as well as the Windows API. The detailed culture information is defined in the [National Language Support (NLS) API Reference topic at the Go Global Developer Center](http://msdn.microsoft.com/goglobal/bb896001.aspx). + Certain predefined culture names and identifiers are used by this and other classes in the namespace, as well as the Windows API. The detailed culture information is defined in the [National Language Support (NLS) API Reference topic at the Go Global Developer Center](http://msdn.microsoft.com/goglobal/bb896001.aspx). - The property always reflects a specific culture identifier instead of a neutral culture identifier. If is set to a neutral culture identifier, the corresponding has as its value an arbitrary specific culture identifier that uses the same language. For example, the property returns 0x0009 for the English neutral culture, named "en". However, the corresponding property might return 0x0409 for the English (United States) culture, named en-US. + The property always reflects a specific culture identifier instead of a neutral culture identifier. If is set to a neutral culture identifier, the corresponding has as its value an arbitrary specific culture identifier that uses the same language. For example, the property returns 0x0009 for the English neutral culture, named "en". However, the corresponding property might return 0x0409 for the English (United States) culture, named en-US. - Similarly, the property always corresponds to a default sort order, and never reflects a specific sort order. For example, the default sort order for Spanish (Spain) is the international sort order. If is set to "0x040A" (Spanish with the traditional sort order), the corresponding value is "0x0C0A" (Spanish with the default international sort order). + Similarly, the property always corresponds to a default sort order, and never reflects a specific sort order. For example, the default sort order for Spanish (Spain) is the international sort order. If is set to "0x040A" (Spanish with the traditional sort order), the corresponding value is "0x0C0A" (Spanish with the default international sort order). ]]> @@ -759,7 +759,7 @@ . + This method overrides . ]]> diff --git a/xml/System.Globalization/ThaiBuddhistCalendar.xml b/xml/System.Globalization/ThaiBuddhistCalendar.xml index b1ce127d8ac43..d98c1dd1fbb8f 100644 --- a/xml/System.Globalization/ThaiBuddhistCalendar.xml +++ b/xml/System.Globalization/ThaiBuddhistCalendar.xml @@ -64,7 +64,7 @@ The date January 1, 2001 A.D. in the Gregorian calendar is equivalent to the first day of January in the year 2544 of the current era in the Thai Buddhist calendar. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -142,7 +142,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -211,7 +211,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] @@ -686,7 +686,7 @@ method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + In a calendar that supports the notion of a leap month, the leap month can occur either after a particular month or after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. ]]> @@ -839,11 +839,11 @@ ## Remarks This method can be used to determine the number of weeks in the year by setting the `time` parameter to the last day of the year. - contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. + contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. - The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . - The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . For example, in , for January 1 returns 1. diff --git a/xml/System.Globalization/UmAlQuraCalendar.xml b/xml/System.Globalization/UmAlQuraCalendar.xml index 6b9d4196cf261..3b8a1b869854c 100644 --- a/xml/System.Globalization/UmAlQuraCalendar.xml +++ b/xml/System.Globalization/UmAlQuraCalendar.xml @@ -116,7 +116,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#5)] [!code-vb[System.Globalization.Calendar.AddMethods#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#5)] @@ -184,7 +184,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. [!code-csharp[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/cs/add1.cs#8)] [!code-vb[System.Globalization.Calendar.AddMethods#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.globalization.calendar.addmethods/vb/add1.vb#8)] @@ -673,7 +673,7 @@ method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + In a calendar that supports the notion of a leap month, the leap month can occur either after a particular month or after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. ]]> diff --git a/xml/System.Globalization/UnicodeCategory.xml b/xml/System.Globalization/UnicodeCategory.xml index 478333cc7486b..e5d21a13076f9 100644 --- a/xml/System.Globalization/UnicodeCategory.xml +++ b/xml/System.Globalization/UnicodeCategory.xml @@ -34,7 +34,7 @@ enumeration is returned by the and methods. The enumeration is also used to support methods, such as . Such methods determine whether a specified character is a member of a particular Unicode general category. A Unicode general category defines the broad classification of a character, that is, designation as a type of letter, decimal digit, separator, mathematical symbol, punctuation, and so on. + A member of the enumeration is returned by the and methods. The enumeration is also used to support methods, such as . Such methods determine whether a specified character is a member of a particular Unicode general category. A Unicode general category defines the broad classification of a character, that is, designation as a type of letter, decimal digit, separator, mathematical symbol, punctuation, and so on. This enumeration is based on The Unicode Standard, version 5.0. For more information, see the "UCD File Format" and "General Category Values" subtopics at the [Unicode Character Database](http://go.microsoft.com/fwlink/?LinkId=57650). diff --git a/xml/System.IO.Compression/CompressionLevel.xml b/xml/System.IO.Compression/CompressionLevel.xml index f15bc916d7281..a2012af633815 100644 --- a/xml/System.IO.Compression/CompressionLevel.xml +++ b/xml/System.IO.Compression/CompressionLevel.xml @@ -30,19 +30,19 @@ The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: -- +- -- +- -- +- -- +- -- +- -- +- -- +- diff --git a/xml/System.IO.Compression/GZipStream.xml b/xml/System.IO.Compression/GZipStream.xml index 6312cb7f01654..20da02334d03c 100644 --- a/xml/System.IO.Compression/GZipStream.xml +++ b/xml/System.IO.Compression/GZipStream.xml @@ -344,7 +344,7 @@ method. The method is still available in [!INCLUDE[net_v45](~/includes/net-v45-md.md)] to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see . + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can perform asynchronous read operations by using the method. The method is still available in [!INCLUDE[net_v45](~/includes/net-v45-md.md)] to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see . Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . @@ -413,7 +413,7 @@ method. The method is still available in [!INCLUDE[net_v45](~/includes/net-v45-md.md)] to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see . + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can perform asynchronous write operations by using the method. The method is still available in [!INCLUDE[net_v45](~/includes/net-v45-md.md)] to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see . The method starts an asynchronous write operation to a stream object. @@ -607,7 +607,7 @@ method. The method is still available in [!INCLUDE[net_v45](~/includes/net-v45-md.md)] to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see . + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can perform asynchronous read operations by using the method. The method is still available in [!INCLUDE[net_v45](~/includes/net-v45-md.md)] to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see . Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . @@ -661,7 +661,7 @@ method. The method is still available in [!INCLUDE[net_v45](~/includes/net-v45-md.md)] to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see . + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can perform asynchronous write operations by using the method. The method is still available in [!INCLUDE[net_v45](~/includes/net-v45-md.md)] to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see . The method completes the asynchronous write operation started in the method. diff --git a/xml/System.IO.Compression/ZipArchive.xml b/xml/System.IO.Compression/ZipArchive.xml index 20dce9e080aaf..d3cf931b76481 100644 --- a/xml/System.IO.Compression/ZipArchive.xml +++ b/xml/System.IO.Compression/ZipArchive.xml @@ -31,13 +31,13 @@ |To|Use| |--------|---------| -|Create a zip archive from a directory|| -|Extract the contents of a zip archive to a directory|| -|Add new files to an existing zip archive|| -|Retrieve a file from a zip archive|| -|Retrieve all the files from a zip archive|| -|Open a stream to a single file contained in a zip archive|| -|Delete a file from a zip archive|| +|Create a zip archive from a directory|| +|Extract the contents of a zip archive to a directory|| +|Add new files to an existing zip archive|| +|Retrieve a file from a zip archive|| +|Retrieve all the files from a zip archive|| +|Open a stream to a single file contained in a zip archive|| +|Delete a file from a zip archive|| When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. diff --git a/xml/System.IO.Compression/ZipArchiveEntry.xml b/xml/System.IO.Compression/ZipArchiveEntry.xml index 86d4c7c46520f..f27f477193923 100644 --- a/xml/System.IO.Compression/ZipArchiveEntry.xml +++ b/xml/System.IO.Compression/ZipArchiveEntry.xml @@ -29,13 +29,13 @@ |To…|Use…| |---------|----------| -|Create a zip archive from a directory|| -|Extract the contents of a zip archive to a directory|| -|Add new files to an existing zip archive|| -|Retrieve an file in a zip archive|| -|Retrieve all of the files in a zip archive|| -|To open a stream to an individual file contained in a zip archive|| -|Delete a file from a zip archive|| +|Create a zip archive from a directory|| +|Extract the contents of a zip archive to a directory|| +|Add new files to an existing zip archive|| +|Retrieve an file in a zip archive|| +|Retrieve all of the files in a zip archive|| +|To open a stream to an individual file contained in a zip archive|| +|Delete a file from a zip archive|| If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in [!INCLUDE[win8](~/includes/win8-md.md)]. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps, you can decompress the contents of an archive by using or , or you can use the [!INCLUDE[wrt](~/includes/wrt-md.md)] types [Compressor](http://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor](http://go.microsoft.com/fwlink/?LinkId=246358) to compress and decompress files. diff --git a/xml/System.IO.Compression/ZipArchiveMode.xml b/xml/System.IO.Compression/ZipArchiveMode.xml index b703edbcb294f..a1d699e384cab 100644 --- a/xml/System.IO.Compression/ZipArchiveMode.xml +++ b/xml/System.IO.Compression/ZipArchiveMode.xml @@ -30,16 +30,16 @@ The following methods include a parameter named `mode` that lets you specify the archive mode: -- +- -- +- -- +- ## Examples - The following example shows how to specify a value when creating a object. + The following example shows how to specify a value when creating a object. [!code-csharp[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/cs/program1.cs#1)] [!code-vb[System.IO.Compression.ZipArchiveMode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.compression.ziparchivemode/vb/program1.vb#1)] diff --git a/xml/System.IO.Compression/ZipFile.xml b/xml/System.IO.Compression/ZipFile.xml index 81e064a2d085f..46a388323d0df 100644 --- a/xml/System.IO.Compression/ZipFile.xml +++ b/xml/System.IO.Compression/ZipFile.xml @@ -34,13 +34,13 @@ |To…|Use…| |---------|----------| -|Create a zip archive from a directory|| -|Extract the contents of a zip archive to a directory|| -|Add new files to an existing zip archive|| -|Retrieve an file in a zip archive|| -|Retrieve all of the files in a zip archive|| -|To open a stream to an individual file contained in a zip archive|| -|Delete a file from a zip archive|| +|Create a zip archive from a directory|| +|Extract the contents of a zip archive to a directory|| +|Add new files to an existing zip archive|| +|Retrieve an file in a zip archive|| +|Retrieve all of the files in a zip archive|| +|To open a stream to an individual file contained in a zip archive|| +|Delete a file from a zip archive|| You cannot use the or classes in [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps. In [!INCLUDE[win8_appname_long](~/includes/win8-appname-long-md.md)] apps, you should use the following classes to work with compressed files. @@ -575,9 +575,9 @@ ## Remarks When you set the `mode` parameter to , the archive is opened with from the enumeration as the file mode value. If the archive does not exist, a exception is thrown. Setting the `mode` parameter to is equivalent to calling the method. - When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. + When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. - When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. + When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. @@ -663,11 +663,11 @@ , the archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. Setting the `mode` parameter to is equivalent to calling the method. + When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. Setting the `mode` parameter to is equivalent to calling the method. - When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. + When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive already exists, an is thrown. - When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. + When you set the `mode` parameter to , the archive is opened with as the file mode value. If the archive exists, it is opened. The existing entries can be modified and new entries can be created. If the archive does not exist, a new archive is created; however, creating a zip archive in mode is not as efficient as creating it in mode. When you open a zip archive file for reading and `entryNameEncoding` is set to `null`, entry names are decoded according to the following rules: @@ -765,7 +765,7 @@ method and setting the `mode` parameter to . The archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. + This method is equivalent to calling the method and setting the `mode` parameter to . The archive is opened with as the file mode value. If the archive does not exist, a exception is thrown. diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorage.xml b/xml/System.IO.IsolatedStorage/IsolatedStorage.xml index 97726196a223c..0e1cd12c124de 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorage.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorage.xml @@ -164,7 +164,7 @@ property overrides this property. + The property overrides this property. ]]> @@ -207,7 +207,7 @@ implements this property. In the case of objects, this value is in bytes. In the case of implementations of other storage objects, such as a database, this value might be in other units of storage. + This property represents the total usage of all storage resources within the isolated storage scope. implements this property. In the case of objects, this value is in bytes. In the case of implementations of other storage objects, such as a database, this value might be in other units of storage. ]]> @@ -312,7 +312,7 @@ method overrides this method. + The method overrides this method. ]]> @@ -462,9 +462,9 @@ property returns the value of , which is expressed in bytes. Derived classes can express the value in other units of measure. A potential example of such an implementation is an isolated storage database. + The default implementation of the property returns the value of , which is expressed in bytes. Derived classes can express the value in other units of measure. A potential example of such an implementation is an isolated storage database. - You cannot set , but the quota is configured in the security policy, and can be set. Code receives a quota of space on the basis of its evidence, so the same code can receive a different quota if it is run with different evidence (for example, the same application run locally and from a share on an intranet can receive different quotas). implements this property. + You cannot set , but the quota is configured in the security policy, and can be set. Code receives a quota of space on the basis of its evidence, so the same code can receive a different quota if it is run with different evidence (for example, the same application run locally and from a share on an intranet can receive different quotas). implements this property. ]]> @@ -504,7 +504,7 @@ property overrides this property. + The property overrides this property. ]]> @@ -539,7 +539,7 @@ implements this method. + implements this method. ]]> @@ -686,7 +686,7 @@ property overrides this property. + The property overrides this property. ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml index 80d90f6a7ab2d..a94c0cd9c866c 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml @@ -171,7 +171,7 @@ method overload to overwrite an existing file. + `sourceFileName` and `destinationFileName` must specify different file names. Use the method overload to overwrite an existing file. ]]> @@ -353,7 +353,7 @@ constructor. + This method is equivalent to using the constructor. ]]> @@ -775,7 +775,7 @@ method with "*" specified for the search pattern. + This method is equivalent to using the method with "*" specified for the search pattern. ]]> @@ -921,7 +921,7 @@ method with "*" specified for the search pattern. + This method is equivalent to using the method with "*" specified for the search pattern. ]]> @@ -962,7 +962,7 @@ . + The `searchPattern` "Project\Data*.txt" will give all ".txt" files beginning with Data in the Project directory of the isolated storage scope. For complete description of search pattern strings, see . For information about how to find directory names, see the method. @@ -1326,7 +1326,7 @@ ## Remarks > [!NOTE] -> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . +> If the `scope` parameter is and the application domain in which the assembly is installed does not have , the method will return an object without a quota. Later attempts to create an object using the object that does not have a quota will fail with an . ]]> @@ -2158,7 +2158,7 @@ constructor. + This method is equivalent to using the constructor. ]]> @@ -2217,7 +2217,7 @@ constructor. + This method is equivalent to using the constructor. ]]> @@ -2278,7 +2278,7 @@ constructor. + This method is equivalent to using the constructor. ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml index 6d6e78203b96c..c4170c7d69984 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml @@ -16,9 +16,9 @@ property gets this enumeration to determine which operations can be performed in isolated storage. + The property gets this enumeration to determine which operations can be performed in isolated storage. - A host application can override the method to perform policy decisions based on a object, and then allow or prevent the increase in the quota size for isolated storage. + A host application can override the method to perform policy decisions based on a object, and then allow or prevent the increase in the quota size for isolated storage. ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityState.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityState.xml index 11236ce6c73ae..04235e7c0f3da 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityState.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityState.xml @@ -17,7 +17,7 @@ method. + This class provides a host application with settings to perform policy decisions in the host's implementation of the method. ]]> @@ -64,7 +64,7 @@ enumeration value, which is the only value in the enumeration. + This property is equal to the enumeration value, which is the only value in the enumeration. ]]> diff --git a/xml/System.IO.Log/SequenceNumber.xml b/xml/System.IO.Log/SequenceNumber.xml index 8a0f5d697ac70..7a5f5ed3f5798 100644 --- a/xml/System.IO.Log/SequenceNumber.xml +++ b/xml/System.IO.Log/SequenceNumber.xml @@ -211,7 +211,7 @@ if both instances are equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.IO.MemoryMappedFiles/MemoryMappedFileRights.xml b/xml/System.IO.MemoryMappedFiles/MemoryMappedFileRights.xml index d501fcb3d065f..0b49bb853af8c 100644 --- a/xml/System.IO.MemoryMappedFiles/MemoryMappedFileRights.xml +++ b/xml/System.IO.MemoryMappedFiles/MemoryMappedFileRights.xml @@ -30,7 +30,7 @@ method to open an existing memory-mapped file. + You can specify access rights when you use the method to open an existing memory-mapped file. ]]> diff --git a/xml/System.IO.MemoryMappedFiles/MemoryMappedViewStream.xml b/xml/System.IO.MemoryMappedFiles/MemoryMappedViewStream.xml index 01833c44c242e..2615a6d7bcf33 100644 --- a/xml/System.IO.MemoryMappedFiles/MemoryMappedViewStream.xml +++ b/xml/System.IO.MemoryMappedFiles/MemoryMappedViewStream.xml @@ -33,7 +33,7 @@ ## Examples The following example obtains a of a memory-mapped file and writes a value to the stream for inter-process communication. - This code example is part of a larger example provided for the method. + This code example is part of a larger example provided for the method. [!code-csharp[system.io.memorymappedfiles_IPC_X#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_x/cs/program.cs#2)] [!code-vb[system.io.memorymappedfiles_IPC_X#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.memorymappedfiles_ipc_x/vb/program.vb#2)] diff --git a/xml/System.IO.Packaging/PackUriHelper.xml b/xml/System.IO.Packaging/PackUriHelper.xml index 61eddfcddf3c1..01f8783748050 100644 --- a/xml/System.IO.Packaging/PackUriHelper.xml +++ b/xml/System.IO.Packaging/PackUriHelper.xml @@ -439,7 +439,7 @@ normalizes `partUri` by case-folding to uppercase () and returning the result. + normalizes `partUri` by case-folding to uppercase () and returning the result. ]]> diff --git a/xml/System.IO.Packaging/Package.xml b/xml/System.IO.Packaging/Package.xml index b48944cdc53e1..7ed0b2fe0b2ee 100644 --- a/xml/System.IO.Packaging/Package.xml +++ b/xml/System.IO.Packaging/Package.xml @@ -37,13 +37,13 @@ A ("relationship") defines an association between a source or and a target object. A can be one of two types, each of which can be one of two forms: -- A package-level relationship (created by the method) relates a to either: +- A package-level relationship (created by the method) relates a to either: - A target part in the package. - A target resource outside the package. -- A part-level relationship (created by the method) relates a source to either: +- A part-level relationship (created by the method) relates a source to either: - Another target part in the package. @@ -179,7 +179,7 @@ initializes an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. + initializes an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. For more information about package parts, see section 1.1 of the Open Packaging Conventions (OPC) specification available for download at [http://go.microsoft.com/fwlink/?LinkID=71255](http://go.microsoft.com/fwlink/?LinkID=71255). @@ -229,9 +229,9 @@ initializes an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. + initializes an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. - The part is . + The part is . For additional information about package parts, see section 1.1 in the Open Packaging Conventions (OPC) specification available for download at [http://go.microsoft.com/fwlink/?LinkID=71255](http://go.microsoft.com/fwlink/?LinkID=71255). @@ -292,7 +292,7 @@ ## Remarks For the default derived class, the method only supports two `compressionOption` values, or compression. Other values of , , or use compression. - creates an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. + creates an empty for the new part. The method can be used to obtain a reference to the stream instance associated with the part. For additional information, see the Open Packaging Conventions (OPC) specification available for download at [http://go.microsoft.com/fwlink/?LinkID=71255](http://go.microsoft.com/fwlink/?LinkID=71255). diff --git a/xml/System.IO.Packaging/PackageDigitalSignature.xml b/xml/System.IO.Packaging/PackageDigitalSignature.xml index cf45012245c3f..d3161a2a1c254 100644 --- a/xml/System.IO.Packaging/PackageDigitalSignature.xml +++ b/xml/System.IO.Packaging/PackageDigitalSignature.xml @@ -262,7 +262,7 @@ property specifies the format of the date. The format of the string is based on the property in effect when the signature was created. + The property specifies the format of the date. The format of the string is based on the property in effect when the signature was created. is based on the system time of the computer where the signing took place. diff --git a/xml/System.IO.Packaging/PackagePartCollection.xml b/xml/System.IO.Packaging/PackagePartCollection.xml index dfe59f4e0b825..c00dfc1d699c8 100644 --- a/xml/System.IO.Packaging/PackagePartCollection.xml +++ b/xml/System.IO.Packaging/PackagePartCollection.xml @@ -25,7 +25,7 @@ class has no public constructor. This class is created and returned by the method. + The class has no public constructor. This class is created and returned by the method. ]]> @@ -56,7 +56,7 @@ method or method is called. + The collection accessed by the enumerator is invalidated after any change occurs to the underlying collection. The underlying collection can change when the method or method is called. ]]> diff --git a/xml/System.IO.Packaging/PackageStore.xml b/xml/System.IO.Packaging/PackageStore.xml index 518d770f39b88..164fb6b5197b3 100644 --- a/xml/System.IO.Packaging/PackageStore.xml +++ b/xml/System.IO.Packaging/PackageStore.xml @@ -31,13 +31,13 @@ To improve performance and minimize the overhead of repeated file open/close operations, the is used to manage instances of packages accessed by and directly by the application. When accessing data in a package, the address of a requested is first checked to see if the package is already defined and open in the . If the package is defined as open in the , requested parts can be accessed directly without repeatedly opening and closing the package for each request. - If your application opens a package with , can be called to add the package to the . should later be called to remove the package from the prior to calling . + If your application opens a package with , can be called to add the package to the . should later be called to remove the package from the prior to calling . XPS packages opened with an constructor are automatically added and removed from the when the document is created and disposed. (You do not need to call or separately for XPS packages opened with constructors.) The file I/O permissions of a package accessed through the remains the same as the I/O permissions set on the package when it is opened. The only provides references to the packages that have been added the store. It is up to the application to correctly open, update, and close each package. - Packages added to the can be accessed in multithreaded environments when they are used in combination with a [!INCLUDE[TLA2#tla_xaml](~/includes/tla2sharptla-xaml-md.md)] parser such as . When operating in a multithreaded environment, the application must lock the package before access. + Packages added to the can be accessed in multithreaded environments when they are used in combination with a [!INCLUDE[TLA2#tla_xaml](~/includes/tla2sharptla-xaml-md.md)] parser such as . When operating in a multithreaded environment, the application must lock the package before access. ]]> diff --git a/xml/System.IO.Pipes/NamedPipeServerStream.xml b/xml/System.IO.Pipes/NamedPipeServerStream.xml index 53fe92539dca1..c7da4f71c17ff 100644 --- a/xml/System.IO.Pipes/NamedPipeServerStream.xml +++ b/xml/System.IO.Pipes/NamedPipeServerStream.xml @@ -1200,7 +1200,7 @@ ## Remarks Because it is asynchronous, this method returns immediately, but the connection process is completed when the client calls or . - Cancellation requests using the cancellation token will only work if the object was created with a pipe option value of or if the cancellation occurs before the method is called. + Cancellation requests using the cancellation token will only work if the object was created with a pipe option value of or if the cancellation occurs before the method is called. ]]> diff --git a/xml/System.IO.Ports/SerialPort.xml b/xml/System.IO.Ports/SerialPort.xml index b5226f4eb5fd2..95da5f9e6484a 100644 --- a/xml/System.IO.Ports/SerialPort.xml +++ b/xml/System.IO.Ports/SerialPort.xml @@ -584,7 +584,7 @@ object and clears both the receive and transmit buffers. This method calls the method, which invokes the protected method with the `disposing` parameter set to `true`. + Calling this method closes the object and clears both the receive and transmit buffers. This method calls the method, which invokes the protected method with the `disposing` parameter set to `true`. The best practice for any application is to wait for some amount of time after calling the method before attempting to call the method, as the port may not be closed instantly. @@ -1820,7 +1820,7 @@ If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. > [!NOTE] -> The class buffers data, but the stream object contained in the property does not. Therefore, the object and the stream object might differ on the number of bytes that are available to read. When bytes are buffered to the object, the property includes these bytes in its value; however, these bytes might not be accessible to the stream contained in the property. +> The class buffers data, but the stream object contained in the property does not. Therefore, the object and the stream object might differ on the number of bytes that are available to read. When bytes are buffered to the object, the property includes these bytes in its value; however, these bytes might not be accessible to the stream contained in the property. ]]> @@ -2108,7 +2108,7 @@ ## Remarks The default value for is . - The value is not supported. + The value is not supported. diff --git a/xml/System.IO/BinaryReader.xml b/xml/System.IO/BinaryReader.xml index 925b52aeb2ba0..2a6e8362fb63d 100644 --- a/xml/System.IO/BinaryReader.xml +++ b/xml/System.IO/BinaryReader.xml @@ -713,7 +713,7 @@ ## Remarks does not restore the file position after an unsuccessful read. - If the integer will fit in seven bits, the integer takes only one byte of space. The integer is expected to have been written through . + If the integer will fit in seven bits, the integer takes only one byte of space. The integer is expected to have been written through . For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). diff --git a/xml/System.IO/BinaryWriter.xml b/xml/System.IO/BinaryWriter.xml index 5e0bb9704228d..99aa67a96934f 100644 --- a/xml/System.IO/BinaryWriter.xml +++ b/xml/System.IO/BinaryWriter.xml @@ -855,11 +855,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -924,11 +924,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -1043,11 +1043,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| diff --git a/xml/System.IO/BufferedStream.xml b/xml/System.IO/BufferedStream.xml index 83c6732765dc3..23e8c1201e8f8 100644 --- a/xml/System.IO/BufferedStream.xml +++ b/xml/System.IO/BufferedStream.xml @@ -927,7 +927,7 @@ ## Remarks If `offset` is negative, the new position will precede the position specified by `origin` by the number of bytes specified by `offset`. If `offset` is 0, the new position will be the position specified by `origin`. If `offset` is positive, the new position will follow the position specified by `origin` by the number of bytes specified by `offset`. - When a object is the base stream for a object, calling the method can cause the position of the stream to no longer match the position of the internal buffer in the reader. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. + When a object is the base stream for a object, calling the method can cause the position of the stream to no longer match the position of the internal buffer in the reader. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. Seeking to any location beyond the length of the stream is supported. diff --git a/xml/System.IO/Directory.xml b/xml/System.IO/Directory.xml index 39cf403aa1796..936a5aa03f5d3 100644 --- a/xml/System.IO/Directory.xml +++ b/xml/System.IO/Directory.xml @@ -1366,7 +1366,7 @@ Directory::CreateDirectory("Public\\Html"); > [!NOTE] > This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - This method is equivalent to . + This method is equivalent to . If the directory described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. @@ -2351,7 +2351,7 @@ Directory::CreateDirectory("Public\\Html"); > [!NOTE] > This method may return an inaccurate value, because it uses native functions whose values may not be continuously updated by the operating system. - This method is identical to . + This method is identical to . If the directory described in the `path` parameter does not exist, this method returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. diff --git a/xml/System.IO/DirectoryInfo.xml b/xml/System.IO/DirectoryInfo.xml index da20a3f1ed379..f7299cf2fe956 100644 --- a/xml/System.IO/DirectoryInfo.xml +++ b/xml/System.IO/DirectoryInfo.xml @@ -774,7 +774,7 @@ ## Examples The following example enumerates the files under a specified directory and uses a LINQ query to return the names of all files that were created before 2009 by checking the value of the property. - If you only need the names of the files, use the static class for better performance. For an example, see the method. + If you only need the names of the files, use the static class for better performance. For an example, see the method. [!code-csharp[System.IO.DirectoryInfo.EnumFiles#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/cs/program.cs#1)] [!code-vb[System.IO.DirectoryInfo.EnumFiles#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.io.directoryinfo.enumfiles/vb/module1.vb#1)] @@ -1293,7 +1293,7 @@ method overload and specifying the access control sections | | (`Or``Or` in Visual Basic). + Calling this method overload is equivalent to calling the method overload and specifying the access control sections | | (`Or``Or` in Visual Basic). Use the method to retrieve the access control list (ACL) entries for the current file. @@ -1934,7 +1934,7 @@ ## Remarks If there are no files or directories in the , this method returns an empty array. This method is not recursive. - For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. This method pre-populates the values of the following properties: @@ -2009,7 +2009,7 @@ This method is not recursive. - For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. Wild cards are permitted. For example, the `searchPattern` string "*t" searches for all directory names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all directory names in `path` beginning with the letter "s". @@ -2094,7 +2094,7 @@ Characters other than the wildcard are literal characters. For example, the string "*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. This method pre-populates the values of the following properties: diff --git a/xml/System.IO/DirectoryNotFoundException.xml b/xml/System.IO/DirectoryNotFoundException.xml index 71d1701e15db1..ede08e16c64cb 100644 --- a/xml/System.IO/DirectoryNotFoundException.xml +++ b/xml/System.IO/DirectoryNotFoundException.xml @@ -75,9 +75,9 @@ property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message takes into account the current system culture. - The property of the new instance is initialized to `null`. + The property of the new instance is initialized to `null`. @@ -121,9 +121,9 @@ property of the new instance using `message`. + This constructor initializes the property of the new instance using `message`. - The property of the new instance is initialized to `null`. + The property of the new instance is initialized to `null`. ]]> diff --git a/xml/System.IO/DriveNotFoundException.xml b/xml/System.IO/DriveNotFoundException.xml index d5c4b030b6a6d..2cd37780ce9d4 100644 --- a/xml/System.IO/DriveNotFoundException.xml +++ b/xml/System.IO/DriveNotFoundException.xml @@ -63,9 +63,9 @@ property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message is localized based on the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message is localized based on the current system culture. - The property of the new instance is initialized to `null`. + The property of the new instance is initialized to `null`. ]]> @@ -100,9 +100,9 @@ property of the new instance using the `message` parameter. + This constructor initializes the property of the new instance using the `message` parameter. - The property of the new instance is initialized to `null`. + The property of the new instance is initialized to `null`. ]]> diff --git a/xml/System.IO/ErrorEventArgs.xml b/xml/System.IO/ErrorEventArgs.xml index 059ef432fa49c..1ef3f39f403cc 100644 --- a/xml/System.IO/ErrorEventArgs.xml +++ b/xml/System.IO/ErrorEventArgs.xml @@ -26,7 +26,7 @@ contains the that caused the event. This class provides the method to retrieve the exception. + contains the that caused the event. This class provides the method to retrieve the exception. diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index 37d8c1272ec60..104625d429ebd 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -35,7 +35,7 @@ > [!NOTE] > To view the .NET Framework source code for this type, see the [Reference Source](http://referencesource.microsoft.com/#mscorlib/system/io/file.cs#1c7421e464f67b7e). You can browse through the source code online, download the reference for offline viewing, and step through the sources (including patches and updates) during debugging; see [instructions](http://referencesource.microsoft.com/). - Use the class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to a single file at a time. You can also use the class to get and set file attributes or information related to the creation, access, and writing of a file. If you want to perform operations on multiple files, see or . + Use the class for typical operations such as copying, moving, renaming, creating, opening, deleting, and appending to a single file at a time. You can also use the class to get and set file attributes or information related to the creation, access, and writing of a file. If you want to perform operations on multiple files, see or . Many of the methods return other I/O types when you create or open files. You can use these other types to further manipulate a file. For more information, see specific members such as , , or . @@ -585,7 +585,7 @@ ## Remarks This method is equivalent to the method overload with the `overwrite` parameter set to `false`. - The `sourceFileName` and `destFileName` parameters can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see the method. This method does not support wildcard characters in the parameters. + The `sourceFileName` and `destFileName` parameters can specify relative or absolute path information. Relative path information is interpreted as relative to the current working directory. To obtain the current working directory, see the method. This method does not support wildcard characters in the parameters. The attributes of the original file are retained in the copied file. @@ -594,9 +594,9 @@ ## Examples The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: -- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. +- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. -- It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. +- It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. [!code-csharp[FileCopyDelete#1](~/samples/snippets/csharp/VS_Snippets_CLR/filecopydelete/cs/program.cs#1)] [!code-vb[FileCopyDelete#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb#1)] @@ -675,9 +675,9 @@ ## Examples The following example copies files to the C:\archives\2008 backup folder. It uses the two overloads of the method as follows: -- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. +- It first uses the method overload to copy text (.txt) files. The code demonstrates that this overload does not allow overwriting files that were already copied. - It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. + It then uses the method overload to copy pictures (.jpg files). The code demonstrates that this overload does allow overwriting files that were already copied. [!code-csharp[FileCopyDelete#1](~/samples/snippets/csharp/VS_Snippets_CLR/filecopydelete/cs/program.cs#1)] [!code-vb[FileCopyDelete#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/filecopydelete/vb/program.vb#1)] @@ -1312,7 +1312,7 @@ ## Remarks The method should not be used for path validation, this method merely checks if the file specified in `path` exists. Passing an invalid path to returns `false`. To check whether the path contains any invalid characters, you can call the method to retrieve the characters that are invalid for the file system. You can also create a regular expression to test the whether the path is valid for your environment. For examples of acceptable paths, see . - To check if a directory exists, see . + To check if a directory exists, see . Be aware that another process can potentially do something with the file in between the time you call the method and perform another operation on the file, such as . @@ -2829,7 +2829,7 @@ The file handle is guaranteed to be closed by this method, even if exceptions are raised. - To use the encoding settings as configured for your operating system, specify the property for the `encoding` parameter. + To use the encoding settings as configured for your operating system, specify the property for the `encoding` parameter. @@ -2958,7 +2958,7 @@ - Perform [LINQ to Objects](http://msdn.microsoft.com/library/73cafe73-37cf-46e7-bfa7-97c7eea7ced9) queries on a file to obtain a filtered set of its lines. -- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. +- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. - Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . @@ -3049,7 +3049,7 @@ - Perform [LINQ to Objects](http://msdn.microsoft.com/library/73cafe73-37cf-46e7-bfa7-97c7eea7ced9) queries on a file to obtain a filtered set of its lines. -- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. +- Write the returned collection of lines to a file with the method, or append them to an existing file with the method. - Create an immediately populated instance of a collection that takes an collection of strings for its constructor, such as a or a . diff --git a/xml/System.IO/FileAttributes.xml b/xml/System.IO/FileAttributes.xml index 8a4e7ab42306b..2e9c0a1032191 100644 --- a/xml/System.IO/FileAttributes.xml +++ b/xml/System.IO/FileAttributes.xml @@ -38,7 +38,7 @@ ## Remarks You can get attributes for files and directories by calling the method, and you can set them by calling the method. - It is not possible to change the compression status of a object by using the method. Instead, you must actually compress the file using either a compression tool or one of the classes in the namespace. + It is not possible to change the compression status of a object by using the method. Instead, you must actually compress the file using either a compression tool or one of the classes in the namespace. diff --git a/xml/System.IO/FileInfo.xml b/xml/System.IO/FileInfo.xml index 843c4716dda1e..4d4da18771098 100644 --- a/xml/System.IO/FileInfo.xml +++ b/xml/System.IO/FileInfo.xml @@ -387,7 +387,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. ## Remarks By default, full read/write access to new files is granted to all users. - This method is a wrapper for the functionality provided by . + This method is a wrapper for the functionality provided by . diff --git a/xml/System.IO/FileStream.xml b/xml/System.IO/FileStream.xml index 7392905ca0536..041a1bbf347bc 100644 --- a/xml/System.IO/FileStream.xml +++ b/xml/System.IO/FileStream.xml @@ -1813,17 +1813,17 @@ . + This method overrides . - When you call the method, the operating system I/O buffer is also flushed. + When you call the method, the operating system I/O buffer is also flushed. - A stream’s encoder is not flushed unless you explicitly call or dispose of the object. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. + A stream’s encoder is not flushed unless you explicitly call or dispose of the object. Setting to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. Because a buffer can be used for either reading or writing, performs the following two functions: - Any data previously written to the buffer is copied to the file and the buffer is cleared except for its encoder state. -- If is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. +- If is `true` and data was previously copied from the file to the buffer for reading, the current position within the file is decremented by the number of unread bytes in the buffer. The buffer is then cleared. Use the method overload when you want to ensure that all buffered data in intermediate file buffers is written to disk. @@ -1952,7 +1952,7 @@ class and can be used to retrieve the access control list (ACL) entries of an existing file, consider using method, as it is easier to use. + While the class and can be used to retrieve the access control list (ACL) entries of an existing file, consider using method, as it is easier to use. Use the method to retrieve the ACL entries for a file. @@ -2557,10 +2557,10 @@ . + This method overrides . > [!NOTE] -> Use the property to determine whether the current instance supports seeking. For additional information, see . +> Use the property to determine whether the current instance supports seeking. For additional information, see . You can seek to any location beyond the length of the stream. When you seek beyond the length of the file, the file size grows. In Windows NT and later versions, data added to the end of the file is set to zero. In Windows 98 or earlier versions, data added to the end of the file is not set to zero, which means that previously deleted data is visible to the stream. @@ -2611,7 +2611,7 @@ class and can be used on an existing file, consider using the method as it is easier to use. + While the class and can be used on an existing file, consider using the method as it is easier to use. The method applies access control list (ACL) entries to a file that represents the noninherited ACL list. diff --git a/xml/System.IO/IOException.xml b/xml/System.IO/IOException.xml index 3a83dc19468fe..8439ccf91ec6e 100644 --- a/xml/System.IO/IOException.xml +++ b/xml/System.IO/IOException.xml @@ -58,7 +58,7 @@ ## Examples - This code example is part of a larger example provided for the method. + This code example is part of a larger example provided for the method. [!code-cpp[System.IO.FileStream3#6](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.IO.FileStream3/CPP/fstreamlock.cpp#6)] [!code-csharp[System.IO.FileStream3#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.FileStream3/CS/fstreamlock.cs#6)] diff --git a/xml/System.IO/InternalBufferOverflowException.xml b/xml/System.IO/InternalBufferOverflowException.xml index df35326c4135e..8d4d4e8ca6c2c 100644 --- a/xml/System.IO/InternalBufferOverflowException.xml +++ b/xml/System.IO/InternalBufferOverflowException.xml @@ -25,7 +25,7 @@ , when you are notified of file changes, the system stores those changes in a buffer the component creates and passes to the Application Programming Interfaces (APIs). If there are many changes in a short time, the buffer can easily overflow, resulting in an exception being thrown, which essentially loses all changes. To keep the buffer from overflowing, use the and properties to filter out your unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + In a , when you are notified of file changes, the system stores those changes in a buffer the component creates and passes to the Application Programming Interfaces (APIs). If there are many changes in a short time, the buffer can easily overflow, resulting in an exception being thrown, which essentially loses all changes. To keep the buffer from overflowing, use the and properties to filter out your unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. @@ -64,7 +64,7 @@ and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + These constructors are used by the component to signify an error. Only use them if extending the class or the .NET Framework. This exception indicates an internal buffer has overflowed and users should take appropriate steps in their code to ensure it recovers properly. The cause of the overflow is often too many changes in a short period of time, causing the internal notification buffer to overflow. To resolve this, use the and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. ]]> @@ -98,7 +98,7 @@ and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + These constructors are used by the component to signify an error. Only use them if extending the class or the .NET Framework. This exception indicates an internal buffer has overflowed and users should take appropriate steps in their code to ensure it recovers properly. The cause of the overflow is often too many changes in a short period of time, causing the internal notification buffer to overflow. To resolve this, use the and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. ]]> @@ -163,7 +163,7 @@ and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + These constructors are used by the component to signify an error. Only use them if extending the class or the .NET Framework. This exception indicates an internal buffer has overflowed and users should take appropriate steps in their code to ensure it recovers properly. The cause of the overflow is often too many changes in a short period of time, causing the internal notification buffer to overflow. To resolve this, use the and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. ]]> diff --git a/xml/System.IO/MemoryStream.xml b/xml/System.IO/MemoryStream.xml index 7090d9a15cea6..0fe063ca3593b 100644 --- a/xml/System.IO/MemoryStream.xml +++ b/xml/System.IO/MemoryStream.xml @@ -856,7 +856,7 @@ method. + This method overrides the method. Because any data written to a object is written into RAM, this method is redundant. @@ -1285,7 +1285,7 @@ . + This method overrides . Seeking to any location beyond the length of the stream is supported. @@ -1686,7 +1686,7 @@ on the underlying buffer of this stream. + When the current stream is open, this method is equivalent to calling on the underlying buffer of this stream. ]]> diff --git a/xml/System.IO/Path.xml b/xml/System.IO/Path.xml index 126399fcd05b3..c986bba97443d 100644 --- a/xml/System.IO/Path.xml +++ b/xml/System.IO/Path.xml @@ -41,7 +41,7 @@ A path is a string that provides the location of a file or directory. A path does not necessarily point to a location on disk; for example, a path might map to a location in memory or on a device. The exact format of a path is determined by the current platform. For example, on some systems, a path can start with a drive or volume letter, while this element is not present in other systems. On some systems, file paths can contain extensions, which indicate the type of information stored in the file. The format of a file name extension is platform-dependent; for example, some systems limit extensions to three characters, and others do not. The current platform also determines the set of characters used to separate the elements of a path, and the set of characters that cannot be used when specifying paths. Because of these differences, the fields of the `Path` class as well as the exact behavior of some members of the `Path` class are platform-dependent. - A path can contain absolute or relative location information. Absolute paths fully specify a location: the file or directory can be uniquely identified regardless of the current location. Relative paths specify a partial location: the current location is used as the starting point when locating a file specified with a relative path. To determine the current directory, call . + A path can contain absolute or relative location information. Absolute paths fully specify a location: the file or directory can be uniquely identified regardless of the current location. Relative paths specify a partial location: the current location is used as the starting point when locating a file specified with a relative path. To determine the current directory, call . Most members of the `Path` class do not interact with the file system and do not verify the existence of the file specified by a path string. `Path` class members that modify a path string, such as , have no effect on names of files in the file system. `Path` members do, however, validate the contents of a specified path string, and throw an exception if the string contains characters that are not valid in path strings, as defined in the characters returned from the method. For example, on Windows-based desktop platforms, invalid path characters might include quote ("), less than (\<), greater than (>), pipe (|), backspace (\b), null (\0), and Unicode characters 16 through 18 and 20 through 25. diff --git a/xml/System.IO/PathTooLongException.xml b/xml/System.IO/PathTooLongException.xml index c6bf781515c57..17c8510768de8 100644 --- a/xml/System.IO/PathTooLongException.xml +++ b/xml/System.IO/PathTooLongException.xml @@ -32,7 +32,7 @@ permission, the error message for this exception may contain only file or directory names instead of full paths. + If your code does not have permission, the error message for this exception may contain only file or directory names instead of full paths. In apps that run under versions of the .NET Framework prior to the [!INCLUDE[net_v462](~/includes/net-v462-md.md)], full paths must not exceed 260 characters to maintain compatibility with Windows operating systems. Any path in excess of 260 characters automatically throws a . For more information about this restriction, see the entry [Long Paths in .NET](http://go.microsoft.com/fwlink/?LinkID=163666) in the BCL Team blog. @@ -46,7 +46,7 @@ - The operating system returns `COR_E_PATHTOOLONG` or its equivalent. -- The length of the path exceeds (32,767) characters. +- The length of the path exceeds (32,767) characters. **Apps that target the [!INCLUDE[net_v461](~/includes/net-v461-md.md)] and earlier versions** Long paths are disabled by default, and the legacy behavior is maintained. The runtime throws a whenever a path exceeds 260 characters. diff --git a/xml/System.IO/StreamReader.xml b/xml/System.IO/StreamReader.xml index 0b2bce816dc20..d76e380c5dbfb 100644 --- a/xml/System.IO/StreamReader.xml +++ b/xml/System.IO/StreamReader.xml @@ -47,9 +47,9 @@ defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system. If you get the current character encoding using the property, the value is not reliable until after the first method, since encoding auto detection is not done until the first call to a method. - By default, a is not thread safe. See for a thread-safe wrapper. + By default, a is not thread safe. See for a thread-safe wrapper. - The and method overloads read and write the number of characters specified by the `count` parameter. These are to be distinguished from and , which read and write the number of bytes specified by the `count` parameter. Use the methods only for reading and writing an integral number of byte array elements. + The and method overloads read and write the number of characters specified by the `count` parameter. These are to be distinguished from and , which read and write the number of bytes specified by the `count` parameter. Use the methods only for reading and writing an integral number of byte array elements. > [!NOTE] > When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. @@ -110,7 +110,7 @@ ## Remarks This constructor initializes the encoding to , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -232,9 +232,9 @@ ## Remarks This constructor initializes the encoding to , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. See the method for more information. + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. See the method for more information. - The object calls on the provided object when is called. + The object calls on the provided object when is called. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -291,9 +291,9 @@ object attempts to detect the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + The character encoding is set by the `encoding` parameter, and the buffer size is set to 1024 bytes. The object attempts to detect the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -353,7 +353,7 @@ The `path` parameter is not required to be a file stored on disk; it can be any part of a system that supports access using streams. - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the is used. See the method for more information. + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the is used. See the method for more information. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -408,7 +408,7 @@ object attempts to detect the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + This constructor initializes the encoding as specified by the `encoding` parameter, and the internal buffer size to 1024 bytes. The object attempts to detect the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -480,9 +480,9 @@ ## Remarks This constructor initializes the encoding as specified by the `encoding` parameter, the property using the `stream` parameter, and the internal buffer size to 1024 bytes. - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -540,7 +540,7 @@ ## Remarks This constructor initializes the encoding as specified by the `encoding` parameter, and the internal buffer size to 1024 bytes. - The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -614,9 +614,9 @@ ## Remarks The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used. - This constructor allows you to change the encoding the first time you read from the object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + This constructor allows you to change the encoding the first time you read from the object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!NOTE] > When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. @@ -685,7 +685,7 @@ ## Remarks This constructor initializes the encoding as specified by the `encoding` parameter. - This constructor allows you to change the encoding the first time you read from the object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + This constructor allows you to change the encoding the first time you read from the object. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used. @@ -765,11 +765,11 @@ object calls on the provided object when is called. + Unless you set the `leaveOpen` parameter to `true`, the object calls on the provided object when is called. The buffer size, in number of 16-bit characters, is set by the `bufferSize` parameter. If `bufferSize` is less than the minimum allowable size (128 characters), the minimum allowable size is used. - This constructor enables you to change the encoding the first time you read from the object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. + This constructor enables you to change the encoding the first time you read from the object. If the `detectEncodingFromByteOrderMarks` parameter is `true`, the constructor detects the encoding by looking at the first three bytes of the stream. It automatically recognizes UTF-8, little-endian Unicode, and big-endian Unicode text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. > [!NOTE] > When reading from a , it is more efficient to use a buffer that is the same size as the internal buffer of the stream. @@ -851,7 +851,7 @@ method. + This method overrides the method. This implementation of calls the method passing a `true` value. @@ -1128,7 +1128,7 @@ ## Remarks The method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. - This method overrides . + This method overrides . The current position of the object is not changed by . @@ -1181,7 +1181,7 @@ . + This method overrides . This method returns an integer so that it can return -1 if the end of the stream has been reached. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. @@ -1249,7 +1249,7 @@ . + This method overrides . This method returns an integer so that it can return 0 if the end of the stream has been reached. @@ -1500,7 +1500,7 @@ ## Remarks A line is defined as a sequence of characters followed by a line feed ("\n"), a carriage return ("\r"), or a carriage return immediately followed by a line feed ("\r\n"). The string that is returned does not contain the terminating carriage return or line feed. The returned value is `null` if the end of the input stream is reached. - This method overrides . + This method overrides . If the current method throws an , the reader's position in the underlying object is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. If you manipulate the position of the underlying stream after reading data into the buffer, the position of the underlying stream might not match the position of the internal buffer. To reset the internal buffer, call the method; however, this method slows performance and should be called only when absolutely necessary. @@ -1608,7 +1608,7 @@ . + This method overrides . works best when you need to read all the input from the current position to the end of the stream. If more control is needed over how many characters are read from the stream, use the method overload, which generally results in better performance. diff --git a/xml/System.IO/StreamWriter.xml b/xml/System.IO/StreamWriter.xml index 57df54efe4f09..34a562a5854c1 100644 --- a/xml/System.IO/StreamWriter.xml +++ b/xml/System.IO/StreamWriter.xml @@ -45,9 +45,9 @@ > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . + defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . - By default, a is not thread safe. See for a thread-safe wrapper. + By default, a is not thread safe. See for a thread-safe wrapper. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -97,9 +97,9 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The property is initialized using the `stream` parameter. The position of the stream is not reset. + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The property is initialized using the `stream` parameter. The position of the stream is not reset. - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable and could cause an exception to be thrown. @@ -150,7 +150,7 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. If the file exists, it is overwritten; otherwise, a new file is created. @@ -226,7 +226,7 @@ ## Remarks This constructor initializes the property using the encoding parameter, and the property using the stream parameter. The position of the stream is not reset. For additional information, see . - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -280,7 +280,7 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -358,7 +358,7 @@ ## Remarks This constructor initializes the property using the `encoding` parameter, and the property using the `stream` parameter. The position of the stream is not reset. For additional information, see . - The object calls on the provided object when is called. + The object calls on the provided object when is called. > [!CAUTION] > When you compile a set of characters with a particular cultural setting and retrieve those same characters with a different cultural setting, the characters might not be interpretable, and could cause an exception to be thrown. @@ -495,7 +495,7 @@ object calls on the provided object when is called. + Unless you set the `leaveOpen` parameter to `true`, the object calls on the provided object when is called. This constructor initializes the property by using the `encoding` parameter, and initializes the property by using the `stream` parameter. The position of the stream is not reset. For additional information, see the property. @@ -639,7 +639,7 @@ When `AutoFlush` is set to `false`, `StreamWriter` will do a limited amount of buffering, both internally and potentially in the encoder from the encoding you passed in. You can get better performance by setting `AutoFlush` to `false`, assuming that you always call `Close` (or at least `Flush`) when you're done writing with a `StreamWriter`. - For example, set `AutoFlush` to `true` when you are writing to a device where the user expects immediate feedback. `Console.Out` is one of these cases: The `StreamWriter` used internally for writing to `Console` flushes all its internal state except the encoder state after every call to . + For example, set `AutoFlush` to `true` when you are writing to a device where the user expects immediate feedback. `Console.Out` is one of these cases: The `StreamWriter` used internally for writing to `Console` flushes all its internal state except the encoder state after every call to . For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -724,7 +724,7 @@ . + This method overrides . This implementation of calls the method passing a `true` value. @@ -882,7 +882,7 @@ . + This method overrides . Flushing the stream will not flush its underlying encoder unless you explicitly call `Flush` or . Setting to `true` means that data will be flushed from the buffer to the stream after each write operation, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can only be encoded after the encoder receives the adjacent character or characters. @@ -1024,7 +1024,7 @@ . + This method overrides . The specified character is written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. @@ -1076,7 +1076,7 @@ . + This method overrides . The specified characters are written to the underlying stream unless the end of the stream is reached prematurely. If is `true`, is invoked automatically. @@ -1130,7 +1130,7 @@ . + This method overrides . The specified is written to the underlying stream unless the end of the stream is reached prematurely. @@ -1188,7 +1188,7 @@ . + This method overrides . The characters are read from `buffer` beginning at `index` and continuing through `index` + (`count` - 1). All characters are written to the underlying stream unless the end of the underlying stream is reached prematurely. is invoked automatically if is `true`. @@ -1428,7 +1428,7 @@ property. + The line terminator is defined by the property. ]]> @@ -1479,7 +1479,7 @@ property. + The line terminator is defined by the property. @@ -1538,7 +1538,7 @@ property. + The line terminator is defined by the property. @@ -1601,7 +1601,7 @@ property. + The line terminator is defined by the property. diff --git a/xml/System.IO/StringReader.xml b/xml/System.IO/StringReader.xml index c49d98c957c7f..58f95609fc8bc 100644 --- a/xml/System.IO/StringReader.xml +++ b/xml/System.IO/StringReader.xml @@ -47,11 +47,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -108,11 +108,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -160,7 +160,7 @@ ## Remarks For an example of creating a file and writing text to a file, see [How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md). For an example of reading text from a file, see [How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md). For an example of reading from and writing to a binary file, see [How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md). - This method overrides the method. + This method overrides the method. This implementation of `Close` calls the method passing a `true` value. @@ -257,7 +257,7 @@ ## Remarks The method returns an integer value in order to determine whether the end of the file, or another error has occurred. This allows a user to first check if the returned value is -1 before casting it to a type. - This method overrides the method. + This method overrides the method. The current position of the `StringReader` is not changed by this operation. @@ -268,7 +268,7 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Get the size of a file.|| +|Get the size of a file.|| ]]> @@ -310,7 +310,7 @@ method. + This method overrides the method. The following table lists examples of other typical or related I/O tasks. @@ -319,11 +319,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -383,7 +383,7 @@ . + This method overrides . The method will read up to `count` characters from the into the `buffer` character array starting at position `index`. Returns the actual number of characters read, or zero if the end of the string has been reached and no characters are read. @@ -394,11 +394,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -575,7 +575,7 @@ method. + This method overrides the method. A line is defined as a sequence of characters followed by a line feed ("\n"), a carriage return ("\r"), or a carriage return immediately followed by a line feed ("\r\n"). The string that is returned does not contain the terminating carriage return or line feed. The returned value is `null` if the end of the string has been reached. @@ -588,11 +588,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -698,7 +698,7 @@ method. + This method overrides the method. If the current method throws an , the reader's position in the underlying string is advanced by the number of characters the method was able to read, but the characters already read into the internal buffer are discarded. Because the position of the reader in the string cannot be changed, the characters already read are unrecoverable, and can be accessed only by reinitializing the . To avoid such a situation, use the method and store the read characters in a preallocated buffer. @@ -709,11 +709,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| diff --git a/xml/System.IO/StringWriter.xml b/xml/System.IO/StringWriter.xml index 7d6cf3b24f4f8..8d51775ffcaf7 100644 --- a/xml/System.IO/StringWriter.xml +++ b/xml/System.IO/StringWriter.xml @@ -47,11 +47,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -99,7 +99,7 @@ object is automatically created and associated with the new instance of the class. Since a format control is not specified for this constructor, the new instance will be initialized with . + A new object is automatically created and associated with the new instance of the class. Since a format control is not specified for this constructor, the new instance will be initialized with . The following table lists examples of other typical or related I/O tasks. @@ -108,11 +108,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -172,11 +172,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -227,7 +227,7 @@ . + Since a format control is not specified for this constructor, the new instance will be initialized with . The following table lists examples of other typical or related I/O tasks. @@ -236,11 +236,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -302,11 +302,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -346,7 +346,7 @@ ## Remarks For an example of creating a file and writing text to a file, see [How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md). For an example of reading text from a file, see [How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md). For an example of reading from and writing to a binary file, see [How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md). - This method overrides . + This method overrides . This implementation of `Close` calls the method passing a `true` value. @@ -660,7 +660,7 @@ . + This method overrides . The following table lists examples of other typical or related I/O tasks. @@ -669,11 +669,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -728,7 +728,7 @@ . + This method overrides . If the specified string is `null`, nothing is written. @@ -739,11 +739,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -802,7 +802,7 @@ . + This method overrides . This method writes `count` characters of data to this `StringWriter` from `buffer`, starting at position `index`. @@ -813,11 +813,11 @@ |Create a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Write to a text file.|[How to: Write Text to a File](~/docs/standard/io/how-to-write-text-to-a-file.md)| |Read from a text file.|[How to: Read Text from a File](~/docs/standard/io/how-to-read-text-from-a-file.md)| -|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| -|Get the size of a file.|| -|Get the attributes of a file.|| -|Set the attributes of a file.|| -|Determine if a file exists.|| +|Append text to a file.|[How to: Open and Append to a Log File](~/docs/standard/io/how-to-open-and-append-to-a-log-file.md)



| +|Get the size of a file.|| +|Get the attributes of a file.|| +|Set the attributes of a file.|| +|Determine if a file exists.|| |Read from a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| |Write to a binary file.|[How to: Read and Write to a Newly Created Data File](~/docs/standard/io/how-to-read-and-write-to-a-newly-created-data-file.md)| @@ -1054,7 +1054,7 @@ property. + The line terminator is defined by the property. @@ -1113,7 +1113,7 @@ property. + The line terminator is defined by the property. @@ -1176,7 +1176,7 @@ property. + The line terminator is defined by the property. diff --git a/xml/System.IO/TextReader.xml b/xml/System.IO/TextReader.xml index 476a1c3c30bb5..828d4275d6deb 100644 --- a/xml/System.IO/TextReader.xml +++ b/xml/System.IO/TextReader.xml @@ -49,7 +49,7 @@ ## Examples - The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for reading from a stream. The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. + The class is an abstract class. Therefore, you do not instantiate it in your code. The class derives from and provides implementations of the members for reading from a stream. The following example shows how to read all the characters in a file by using the method. It checks whether each character is a letter, digit, or white space before adding the character to an instance of the class. [!code-csharp[System.IO.StreamReader#42](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.IO.StreamReader/CS/example42.cs#42)] [!code-vb[System.IO.StreamReader#42](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.IO.StreamReader/VB/example42.vb#42)] @@ -126,12 +126,12 @@ method and passes it a `true` value. + This implementation of `Close` calls the method and passes it a `true` value. - Flushing the text reader will not flush its underlying encoder unless you explicitly call `Close`. Setting the property to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. + Flushing the text reader will not flush its underlying encoder unless you explicitly call `Close`. Setting the property to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. > [!NOTE] -> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. +> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. ]]> @@ -320,7 +320,7 @@ The current position of the is not changed by this operation. The returned value is -1 if no more characters are available. The default implementation returns -1. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -363,7 +363,7 @@ class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -415,7 +415,7 @@ ## Remarks This method returns after either `count` characters are read or the end of the file is reached. is a blocking version of this method. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -477,7 +477,7 @@ ## Remarks The task completes after either the number of characters specified by the `count` parameter are read or the end of the file is reached. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -642,13 +642,13 @@ , or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The return value is `null` if the end of the input stream has been reached. + A line is defined as a sequence of characters followed by a carriage return (0x000d), a line feed (0x000a), a carriage return followed by a line feed, , or the end-of-stream marker. The string that is returned does not contain the terminating carriage return or line feed. The return value is `null` if the end of the input stream has been reached. If the method throws an exception, the reader's position in the underlying is advanced by the number of characters the method was able to read, but the characters that were already read into the internal buffer are discarded. Because the position of the reader in the stream cannot be changed, the characters that were already read are unrecoverable and can be accessed only by reinitializing the object. If the initial position within the stream is unknown or the stream does not support seeking, the underlying also needs to be reinitialized. To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -698,9 +698,9 @@ class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - If the current represents the standard input stream returned by the property, the method executes synchronously rather than asynchronously. + If the current represents the standard input stream returned by the property, the method executes synchronously rather than asynchronously. ]]> @@ -748,7 +748,7 @@ To avoid such a situation and produce robust code you should use the method and store the read characters in a preallocated buffer. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -804,7 +804,7 @@ class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> diff --git a/xml/System.IO/TextWriter.xml b/xml/System.IO/TextWriter.xml index 308f6b115b201..7b824331831a1 100644 --- a/xml/System.IO/TextWriter.xml +++ b/xml/System.IO/TextWriter.xml @@ -45,7 +45,7 @@ All the `Write` methods of having primitive data types as parameters write out the values as strings. - By default, a is not thread safe. See for a thread-safe wrapper. + By default, a is not thread safe. See for a thread-safe wrapper. > [!IMPORTANT] > This type implements the interface. When you have finished using any type that derives from this type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see Dispose and the "Using an Object that Implements IDisposable" section in the interface topic. @@ -180,12 +180,12 @@ method and passes it a `true` value. + This implementation of `Close` calls the method and passes it a `true` value. - Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property to `true` means that data will be flushed from the buffer to the stream, but the encoder state will not be flushed. This allows the encoder to keep its state (partial characters) so that it can encode the next block of characters correctly. This scenario affects UTF8 and UTF7 where certain characters can be encoded only after the encoder receives the adjacent character or characters. > [!NOTE] -> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. +> In derived classes, do not override the method. Instead, override the method to add code for releasing resources. ]]> @@ -574,7 +574,7 @@ ## Remarks Use `Null` to redirect output to a stream that will not consume any operating system resources. - When the methods are invoked on `Null`, the call simply returns, and no data is actually written to any backing store. + When the methods are invoked on `Null`, the call simply returns, and no data is actually written to any backing store. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -661,9 +661,9 @@ method. + The text representation of the specified value is produced by calling the method. - This method outputs either or . + This method outputs either or . For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -851,7 +851,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -898,7 +898,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -945,7 +945,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -1043,7 +1043,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -1092,7 +1092,7 @@ ## Remarks This overload is equivalent to the overload. - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If `value` is `null`, nothing is written to the text stream. @@ -1146,7 +1146,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -1198,7 +1198,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md). @@ -1268,13 +1268,13 @@ |Element|Description| |-------------|-----------------| -|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| +|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - . This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + . This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -1361,13 +1361,13 @@ |Element|Description| |-------------|-----------------| -|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| +|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -1506,13 +1506,13 @@ |Element|Description| |-------------|-----------------| -|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| +|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -1596,13 +1596,13 @@ |Element|Description| |-------------|-----------------| -|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| +|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". - This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . + This method does not search the specified string for individual newline characters (hexadecimal 0x000a) and replace them with . If a specified object is not referenced in the format string, it is ignored. @@ -1665,7 +1665,7 @@ class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -1760,7 +1760,7 @@ class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -1815,7 +1815,7 @@ class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -1909,9 +1909,9 @@ method. + The text representation of the specified value is produced by calling the method. - This method outputs either or . + This method outputs either or . The line terminator is defined by the field. @@ -2154,7 +2154,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -2203,7 +2203,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -2404,7 +2404,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -2458,7 +2458,7 @@ method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -2530,9 +2530,9 @@ |Element|Description| |-------------|-----------------| -|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| +|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has only a single object in its parameter list, the value of *index* must always be 0. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". @@ -2625,9 +2625,9 @@ |Element|Description| |-------------|-----------------| -|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| +|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has an array in its parameter list, the value of *index* must always be less than the length of the array. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". @@ -2773,9 +2773,9 @@ |Element|Description| |-------------|-----------------| -|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| +|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has two objects in its parameter list, the value of *index* must always be 0 or 1. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". @@ -2865,9 +2865,9 @@ |Element|Description| |-------------|-----------------| -|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| +|index|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . Because this overload has three objects in its parameter list, the value of *index* must always be 0, 1, or 2. If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| -|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| +|:*formatString*|A standard or custom format string that is supported by the object to be formatted. Possible values for *formatString* are the same as the values supported by the object's `ToString(string format)` method. If *formatString* is not specified and the object to be formatted implements the interface, `null` is passed as the value of the `format` parameter that is used as the format string.| The leading and trailing brace characters, "{" and "}", are required. To specify a single literal brace character in `format`, specify two leading or trailing brace characters; that is, "{{" or "}}". @@ -2986,7 +2986,7 @@ ## Remarks The line terminator is defined by the field. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -3090,7 +3090,7 @@ ## Remarks The line terminator is defined by the field. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> @@ -3147,7 +3147,7 @@ ## Remarks The line terminator is defined by the field. - The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. + The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. ]]> diff --git a/xml/System.IO/UnmanagedMemoryStream.xml b/xml/System.IO/UnmanagedMemoryStream.xml index 9ad3658d31daf..32081ae698e90 100644 --- a/xml/System.IO/UnmanagedMemoryStream.xml +++ b/xml/System.IO/UnmanagedMemoryStream.xml @@ -995,7 +995,7 @@ of the property of the returned task. + If an exception occurs during the read operation, it will be set as the of the property of the returned task. ]]> @@ -1291,7 +1291,7 @@ of the property of the returned task. + If an exception occurs during the write operation, it will be set as the of the property of the returned task. ]]> diff --git a/xml/System.IdentityModel.Configuration/CustomTypeElement.xml b/xml/System.IdentityModel.Configuration/CustomTypeElement.xml index 5ef1a0b4e85ea..a4198e0f58b73 100644 --- a/xml/System.IdentityModel.Configuration/CustomTypeElement.xml +++ b/xml/System.IdentityModel.Configuration/CustomTypeElement.xml @@ -16,7 +16,7 @@ class represents an attribute or an element that specifies a custom type in a configuration file. For example, the [<claimsAuthenticationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthenticationmanager.md) element that is used to specify the claims identity manager contains `type` attribute that specifies the of the claims authentication manager; ``. The property that represents this element as configured under an [<identityConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element gets and sets an instance of . + The class represents an attribute or an element that specifies a custom type in a configuration file. For example, the [<claimsAuthenticationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthenticationmanager.md) element that is used to specify the claims identity manager contains `type` attribute that specifies the of the claims authentication manager; ``. The property that represents this element as configured under an [<identityConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element gets and sets an instance of . ]]> diff --git a/xml/System.IdentityModel.Configuration/SecurityTokenServiceConfiguration.xml b/xml/System.IdentityModel.Configuration/SecurityTokenServiceConfiguration.xml index 9718480c8ea5e..883824abb2231 100644 --- a/xml/System.IdentityModel.Configuration/SecurityTokenServiceConfiguration.xml +++ b/xml/System.IdentityModel.Configuration/SecurityTokenServiceConfiguration.xml @@ -20,7 +20,7 @@ [!code-csharp[WIFCustomTokenSTS#2](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/customsecuritytokenserviceconfiguration.cs#2)] - The following code shows how to invoke a custom passive STS to process a WS-Federation request by calling the method from the code behind in the `default.aspx.cs` file. The method initializes an instance of the `PassiveSTS.CustomSecurityTokenService` class using the properties set on the `CustomSecurityTokenServiceConfiguration` class shown in the previous example. + The following code shows how to invoke a custom passive STS to process a WS-Federation request by calling the method from the code behind in the `default.aspx.cs` file. The method initializes an instance of the `PassiveSTS.CustomSecurityTokenService` class using the properties set on the `CustomSecurityTokenServiceConfiguration` class shown in the previous example. [!code-csharp[WIFCustomTokenSTS#1](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/default.aspx.cs#1)] @@ -242,7 +242,7 @@ ## Examples The code examples that are used in the topics are taken from the `Custom Token` sample. This sample provides custom classes that enable processing of Simple Web Tokens (SWT) and it includes an implementation of a passive STS that is capable of serving an SWT token. For an example of how to implement an active STS, you can see the `Federation Metadata` sample. For information about these samples and other samples available for WIF and about where to download them, see [WIF Code Sample Index](~/docs/framework/security/wif-code-sample-index.md). The following code shows a custom implementation of the class to support a passive STS that processes SWT tokens. The configuration is initialized and stored in the HTTP application state the first time the static `Current` property is accessed. The constructor initializes the properties of the custom configuration with the type of the custom STS, a custom issuer token resolver, and the default token type (the URI of the SWT token type). It also adds an SWT token handler to the default handler collection. - The following code shows how to invoke a custom passive STS to process a WS-Federation request by calling the method from the code behind in the `default.aspx.cs` file. The method initializes an instance of the `PassiveSTS.CustomSecurityTokenService` class using the properties set on the current `CustomSecurityTokenServiceConfiguration` object. The `CustomSecurityTokenServiceConfiguration.Current` property is implemented by the `CustomSecurityTokenServiceConfiguration` class and returns the instance of the class that is saved in the HTTP application state. + The following code shows how to invoke a custom passive STS to process a WS-Federation request by calling the method from the code behind in the `default.aspx.cs` file. The method initializes an instance of the `PassiveSTS.CustomSecurityTokenService` class using the properties set on the current `CustomSecurityTokenServiceConfiguration` object. The `CustomSecurityTokenServiceConfiguration.Current` property is implemented by the `CustomSecurityTokenServiceConfiguration` class and returns the instance of the class that is saved in the HTTP application state. [!code-csharp[WIFCustomTokenSTS#1](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/default.aspx.cs#1)] diff --git a/xml/System.IdentityModel.Metadata/MetadataSerializer.xml b/xml/System.IdentityModel.Metadata/MetadataSerializer.xml index c985a761d033a..b49105bf05fa2 100644 --- a/xml/System.IdentityModel.Metadata/MetadataSerializer.xml +++ b/xml/System.IdentityModel.Metadata/MetadataSerializer.xml @@ -31,7 +31,7 @@ and properties are initialized to the following values: , , and . + The and properties are initialized to the following values: , , and . ]]> @@ -56,7 +56,7 @@ and properties are initialized to the following values: , , and . + The and properties are initialized to the following values: , , and . ]]> diff --git a/xml/System.IdentityModel.Protocols.WSTrust/RequestClaim.xml b/xml/System.IdentityModel.Protocols.WSTrust/RequestClaim.xml index a754898eab460..b20d6b60f043d 100644 --- a/xml/System.IdentityModel.Protocols.WSTrust/RequestClaim.xml +++ b/xml/System.IdentityModel.Protocols.WSTrust/RequestClaim.xml @@ -16,7 +16,7 @@ which is a collection of objects. The contents of the wst:Claims element is accessed through the property. + Represents a single claim inside a wst:Claims element in a wst:RequestSecurityToken message. The entire contents of the wst:Claims element is represented by a which is a collection of objects. The contents of the wst:Claims element is accessed through the property. A object represents a request for a claim, identified by its claim type (the property), to be present in the security token issued by the STS. The property indicates whether the claim is required in the in the issued token. diff --git a/xml/System.IdentityModel.Protocols.WSTrust/RequestSecurityToken.xml b/xml/System.IdentityModel.Protocols.WSTrust/RequestSecurityToken.xml index 3c6d1220131e5..b39ec8c7b6b22 100644 --- a/xml/System.IdentityModel.Protocols.WSTrust/RequestSecurityToken.xml +++ b/xml/System.IdentityModel.Protocols.WSTrust/RequestSecurityToken.xml @@ -27,7 +27,7 @@ ## Examples The code example that is used in this topic is taken from the `Custom Token` sample. This sample provides custom classes that enable processing of Simple Web Tokens (SWT) and it includes an implementation of a passive STS that is capable of serving an SWT token. The STS is implemented by a class that is derived from . Many of the methods of the class that are called from its token issuance pipeline take a object as one if their parameters. For information about this sample and other samples available for WIF and about where to download them, see [WIF Code Sample Index](~/docs/framework/security/wif-code-sample-index.md). - The following code example shows an implementation of the method. The method takes a as one of its parameters and properties of this parameter are used to set properties on the object that is returned by the method. + The following code example shows an implementation of the method. The method takes a as one of its parameters and properties of this parameter are used to set properties on the object that is returned by the method. [!code-csharp[WIFCustomTokenSTS#4](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/customsecuritytokenservice.cs#4)] [!code-csharp[WIFCustomTokenSTS#5](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/customsecuritytokenservice.cs#5)] diff --git a/xml/System.IdentityModel.Services.Configuration/FederationConfiguration.xml b/xml/System.IdentityModel.Services.Configuration/FederationConfiguration.xml index d756838965030..cb4f277839adb 100644 --- a/xml/System.IdentityModel.Services.Configuration/FederationConfiguration.xml +++ b/xml/System.IdentityModel.Services.Configuration/FederationConfiguration.xml @@ -16,7 +16,7 @@ object that is accessed through the property. The first time the property is accessed a new instance is initialized from settings in the configuration file and the event is raised. You can use the properties and methods exposed by the class to modify or replace the object initialized from configuration in an event handler. This object is available through the property inside the event handler. + By default web applications have a single object that is accessed through the property. The first time the property is accessed a new instance is initialized from settings in the configuration file and the event is raised. You can use the properties and methods exposed by the class to modify or replace the object initialized from configuration in an event handler. This object is available through the property inside the event handler. ]]> @@ -57,7 +57,7 @@ ` configuration section. This constructor calls the constructor with the `loadConfig` parameter `true`. + The properties in the new instance are initialized by loading settings from the `` configuration section. This constructor calls the constructor with the `loadConfig` parameter `true`. > [!WARNING] > Before the new instance is used by any of the configured HTTP modules, call the method to ensure that the instance is properly initialized. @@ -265,7 +265,7 @@ ## Remarks This method ensures that the current instance is properly initialized before it is used by the HTTP Modules to process incoming requests. It should only be called once. Check the property before calling the method. This method sets the property is set `true`. - The default implementation creates a default cookie handler if there is not one already configured through the property and calls the method on the identity configuration object that is configured through the property. You can override this method to modify this behavior or to provide additional initialization in derived classes. + The default implementation creates a default cookie handler if there is not one already configured through the property and calls the method on the identity configuration object that is configured through the property. You can override this method to modify this behavior or to provide additional initialization in derived classes. This method should be invoked before the class is used by the HTTP Modules to process incoming requests. diff --git a/xml/System.IdentityModel.Services.Configuration/FederationConfigurationCreatedEventArgs.xml b/xml/System.IdentityModel.Services.Configuration/FederationConfigurationCreatedEventArgs.xml index 6fd1b4c16585e..11d7074c62c4f 100644 --- a/xml/System.IdentityModel.Services.Configuration/FederationConfigurationCreatedEventArgs.xml +++ b/xml/System.IdentityModel.Services.Configuration/FederationConfigurationCreatedEventArgs.xml @@ -16,7 +16,7 @@ event is raised when the first HTTP module in the web application references the property. The first access of the this property causes a object to be created and initialized from configuration. The event is then raised. You can access the newly created object through the property in an event handler in order to examine or modify it. + The event is raised when the first HTTP module in the web application references the property. The first access of the this property causes a object to be created and initialized from configuration. The event is then raised. You can access the newly created object through the property in an event handler in order to examine or modify it. ]]> diff --git a/xml/System.IdentityModel.Services.Configuration/FederationConfigurationElementCollection.xml b/xml/System.IdentityModel.Services.Configuration/FederationConfigurationElementCollection.xml index 27b9960559072..e1cbe19e835cb 100644 --- a/xml/System.IdentityModel.Services.Configuration/FederationConfigurationElementCollection.xml +++ b/xml/System.IdentityModel.Services.Configuration/FederationConfigurationElementCollection.xml @@ -98,7 +98,7 @@ ` element is specified through its `name` attribute ( property). + The name of a `` element is specified through its `name` attribute ( property). ]]> diff --git a/xml/System.IdentityModel.Services.Configuration/SystemIdentityModelServicesSection.xml b/xml/System.IdentityModel.Services.Configuration/SystemIdentityModelServicesSection.xml index a4cc3cf4cb0c4..1300ffe5539df 100644 --- a/xml/System.IdentityModel.Services.Configuration/SystemIdentityModelServicesSection.xml +++ b/xml/System.IdentityModel.Services.Configuration/SystemIdentityModelServicesSection.xml @@ -74,7 +74,7 @@ ` element does not have its `name` attribute set ( property is `null`). + The unnamed `` element does not have its `name` attribute set ( property is `null`). ]]> diff --git a/xml/System.IdentityModel.Services.Configuration/WsFederationConfiguration.xml b/xml/System.IdentityModel.Services.Configuration/WsFederationConfiguration.xml index 6977d413f6089..1ca2e9e67ea5e 100644 --- a/xml/System.IdentityModel.Services.Configuration/WsFederationConfiguration.xml +++ b/xml/System.IdentityModel.Services.Configuration/WsFederationConfiguration.xml @@ -16,7 +16,7 @@ class that is set on the object accessed through the property contains the settings that are used to initialize the properties of the WS-Federation Authentication Module (WSFAM) and control its behavior. These settings are typically loaded from the `` element in the configuration file. + An instance of the class that is set on the object accessed through the property contains the settings that are used to initialize the properties of the WS-Federation Authentication Module (WSFAM) and control its behavior. These settings are typically loaded from the `` element in the configuration file. ]]> @@ -43,7 +43,7 @@ ## Remarks The properties of the new instance are initialized according to the settings of the specified `` element. - Some validation is performed on the object specified by `federationElement`. Both the property and the property must specify non-null, non-empty values. If the property is set `true`, the property must specify a URI that has an HTTPS scheme. The property cannot be negative. If any of these conditions are not met, an exception is thrown. + Some validation is performed on the object specified by `federationElement`. Both the property and the property must specify non-null, non-empty values. If the property is set `true`, the property must specify a URI that has an HTTPS scheme. The property cannot be negative. If any of these conditions are not met, an exception is thrown. ]]> diff --git a/xml/System.IdentityModel.Services/ClaimsAuthorizationModule.xml b/xml/System.IdentityModel.Services/ClaimsAuthorizationModule.xml index 9a1b21159842f..9f0b46566bedd 100644 --- a/xml/System.IdentityModel.Services/ClaimsAuthorizationModule.xml +++ b/xml/System.IdentityModel.Services/ClaimsAuthorizationModule.xml @@ -142,7 +142,7 @@ property from the claims authorization manager that is specified in configuration by the property on the object set on the object that is set on the property. You can specify the claims authentication manager in a configuration file through the [<claimsAuthorizationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager.md) element. + Initializes the property from the claims authorization manager that is specified in configuration by the property on the object set on the object that is set on the property. You can specify the claims authentication manager in a configuration file through the [<claimsAuthorizationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager.md) element. ]]> diff --git a/xml/System.IdentityModel.Services/ClaimsPrincipalPermission.xml b/xml/System.IdentityModel.Services/ClaimsPrincipalPermission.xml index f2a73de2e0b55..86eadd862c852 100644 --- a/xml/System.IdentityModel.Services/ClaimsPrincipalPermission.xml +++ b/xml/System.IdentityModel.Services/ClaimsPrincipalPermission.xml @@ -26,15 +26,15 @@ The class provides the capability to perform imperative access checks by using the that is configured for an application. By invoking the method or the static method, you can provide protection to resources from within the execution path of your code according to the authorization policy defined for your claims authentication manager. Declarative access checks can be performed by using the class. > [!IMPORTANT] -> The class uses the claims authorization manager configured by the that is set under the property. This is true in all cases, even in scenarios where WS-Federation is not used; for example, active (WCF) Web applications and Console applications. You can specify the claims authorization manager either in configuration or programmatically. To specify the claims authorization manager in a configuration file, set the [<claimsAuthorizationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager.md) element under an [<identityConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element and ensure that this identity configuration is referenced by the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element that is loaded by the runtime (for example, by setting the `identityConfigurationName` attribute). To set the claims authorization manager programmatically, provide a handler for the event. +> The class uses the claims authorization manager configured by the that is set under the property. This is true in all cases, even in scenarios where WS-Federation is not used; for example, active (WCF) Web applications and Console applications. You can specify the claims authorization manager either in configuration or programmatically. To specify the claims authorization manager in a configuration file, set the [<claimsAuthorizationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager.md) element under an [<identityConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element and ensure that this identity configuration is referenced by the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element that is loaded by the runtime (for example, by setting the `identityConfigurationName` attribute). To set the claims authorization manager programmatically, provide a handler for the event. On one level, the functionality provided by is similar to the role-based access checks (RBAC) provided through the class; however, the class performs checks based on the claims presented by the active principal. This enables far more granularity than is available through pure RBAC, where many permissions are typically collected under a single role. Perhaps, more importantly, claims-based authorization enables better separation of business logic and authorization policy because permission can be demanded for a specific action on a resource in code and back-end policy can be used to configure which claims the presenting entity must possess in order to satisfy the demand. Like RBAC, performs a user-based access check, that is, unlike code access security implemented by classes that derive from the class and use a stack walk to ensure that all callers of the code have been granted a permission, performs its check only on the current principal. The static method checks access for a specified action on a specified resource. The resource and action are both strings and are typically URIs. You can also initialize an instance of with an action and a resource and call the method. Although the constructor only takes a single resource and action, objects can be combined through the and methods. A permission created by using these methods may contain multiple resource-action pairs. - Both methods determine access by invoking the method of the configured claims authorization manager with an composed of the active principal (), the resource, and the action. They throw a if the current principal is not authorized to perform the action on the resource; otherwise, execution proceeds. + Both methods determine access by invoking the method of the configured claims authorization manager with an composed of the active principal (), the resource, and the action. They throw a if the current principal is not authorized to perform the action on the resource; otherwise, execution proceeds. - In the case of a that contains multiple resource-action pairs, the method is invoked for each of the resource-action pairs contained in the permission. For the call to to succeed, the active principal must be authorized for all of the resource-action pairs contained in the permission. + In the case of a that contains multiple resource-action pairs, the method is invoked for each of the resource-action pairs contained in the permission. For the call to to succeed, the active principal must be authorized for all of the resource-action pairs contained in the permission. @@ -135,7 +135,7 @@ ## Remarks The principal must be authorized for the specified action on the specified resource or the exception is thrown. - The method of the configured claims authorization manager is invoked with an composed of the active principal (), the resource, and the action. + The method of the configured claims authorization manager is invoked with an composed of the active principal (), the resource, and the action. @@ -201,7 +201,7 @@ Although the constructor only takes a single resource and action, objects can be combined through the and methods. The permission created through these methods may contain multiple resource-action pairs. - The method invokes the method of the configured claims authorization manager with an composed of the active principal (), the resource, and the action for each of the resource-action pairs contained in the permission. For the to succeed the active principal must be authorized for all of the resource-action pairs that are contained in the permission. + The method invokes the method of the configured claims authorization manager with an composed of the active principal (), the resource, and the action for each of the resource-action pairs contained in the permission. For the to succeed the active principal must be authorized for all of the resource-action pairs that are contained in the permission. diff --git a/xml/System.IdentityModel.Services/ClaimsPrincipalPermissionAttribute.xml b/xml/System.IdentityModel.Services/ClaimsPrincipalPermissionAttribute.xml index eb44924f844aa..4fa0843b4cd00 100644 --- a/xml/System.IdentityModel.Services/ClaimsPrincipalPermissionAttribute.xml +++ b/xml/System.IdentityModel.Services/ClaimsPrincipalPermissionAttribute.xml @@ -23,10 +23,10 @@ ## Remarks The is used to declaratively request an access check using the configured . - You must specify one of the values, a `Resource` and an `Operation` in your declaration. The `Resource` and `Operation` properties specify the resource and action for which the current principal () must be authorized for execution to proceed. If the current principal is not authorized to perform the specified action (operation) on the specified resource, a is thrown. + You must specify one of the values, a `Resource` and an `Operation` in your declaration. The `Resource` and `Operation` properties specify the resource and action for which the current principal () must be authorized for execution to proceed. If the current principal is not authorized to perform the specified action (operation) on the specified resource, a is thrown. > [!IMPORTANT] -> The class uses the claims authorization manager configured by the that is set under the property. This is true in all cases, even in scenarios where WS-Federation is not used; for example, active (WCF) Web applications and Console applications. You can specify the claims authorization manager either in configuration or programmatically. To specify the claims authorization manager in a configuration file, set the [<claimsAuthorizationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager.md) element under an [<identityConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element and ensure that this identity configuration is referenced by the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element that is loaded by the runtime (for example, by setting the `identityConfigurationName` attribute). To set the claims authorization manager programmatically, provide a handler for the event. +> The class uses the claims authorization manager configured by the that is set under the property. This is true in all cases, even in scenarios where WS-Federation is not used; for example, active (WCF) Web applications and Console applications. You can specify the claims authorization manager either in configuration or programmatically. To specify the claims authorization manager in a configuration file, set the [<claimsAuthorizationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager.md) element under an [<identityConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element and ensure that this identity configuration is referenced by the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element that is loaded by the runtime (for example, by setting the `identityConfigurationName` attribute). To set the claims authorization manager programmatically, provide a handler for the event. diff --git a/xml/System.IdentityModel.Services/CookieHandler.xml b/xml/System.IdentityModel.Services/CookieHandler.xml index b9764023cf32e..783c97b8f9a1d 100644 --- a/xml/System.IdentityModel.Services/CookieHandler.xml +++ b/xml/System.IdentityModel.Services/CookieHandler.xml @@ -20,11 +20,11 @@ Windows Identity Foundation (WIF) ships with a cookie handler called the chunked cookie handler that is implemented by the class. The chunked cookie handler splits the session token across one or more cookies according to a specified chunk size. This is to meet size limitations on individual cookies imposed by many browsers. - You can derive from to create your own cookie handler. When you do so, you must override the , , and methods to perform the actual work of deleting, reading, and writing the session cookie. These methods typically read the cookie from the collection and write or delete cookies through the collection. The object through which you can access the request and response is provided as a parameter to each of these methods. In addition to the required methods, you can optionally override other virtual methods properties exposed by the class to customize the behavior of your handler. + You can derive from to create your own cookie handler. When you do so, you must override the , , and methods to perform the actual work of deleting, reading, and writing the session cookie. These methods typically read the cookie from the collection and write or delete cookies through the collection. The object through which you can access the request and response is provided as a parameter to each of these methods. In addition to the required methods, you can optionally override other virtual methods properties exposed by the class to customize the behavior of your handler. Several properties are exposed by the class that specify default behavior and properties for the session cookie. The , , and properties supply the base name for the cookie, the domain in which it is valid and the path under which it is stored on the client. The property specifies whether the cookie is accessible to client-side scripts. The property specifies whether the cookie should be transmitted only over secure (HTTPS) connections. If set, the property is used to set the expiration time for persistent sessions, that is for sessions that remain valid even after the browser is closed. All of these properties have equivalent properties that are typically set on the underlying object (or objects) by the "core" methods of the handler. For more information see the documentation for each property. - The cookie handler that is used by the SAM can be specified in configuration through the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element. The cookie handler set by this element can be modified in an event delegate for the event or it can be set or accessed directly through the property. + The cookie handler that is used by the SAM can be specified in configuration through the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element. The cookie handler set by this element can be modified in an event delegate for the event or it can be set or accessed directly through the property. @@ -75,7 +75,7 @@ , , and properties. The request is specified by + The name, domain and path are specified by the , , and properties. The request is specified by ]]> @@ -103,7 +103,7 @@ and properties. The request is specified by + The domain and path are specified by the and properties. The request is specified by ]]> @@ -256,7 +256,7 @@ property. + Corresponds to the property. The property can be initialized by specifying the `domain` attribute on the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element in configuration. @@ -286,7 +286,7 @@ ## Remarks Controls whether the "HttpOnly" flag is emitted in the Set-Cookie header for cookies written by the handler. Some web browsers honor this flag by keeping client-side script from accessing the cookie value. - This property corresponds to the property. + This property corresponds to the property. The property can be initialized by specifying the `hideFromScript` attribute on the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element in configuration. @@ -337,7 +337,7 @@ property. + This property corresponds to the property. The property can be initialized by specifying the `name` attribute on the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element in configuration. @@ -365,7 +365,7 @@ property. + This property corresponds to the property. The property can be initialized by specifying the `path` attribute on the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element in configuration. @@ -395,7 +395,7 @@ ## Remarks Tickets for persistent sessions are stored in file-based cookies, meaning that the sign-in session may continue after the web browser is closed and reopened. - This property is used to set the property. + This property is used to set the property. The property can be initialized by specifying the `persistentSessionLifetime` attribute on the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element in configuration. @@ -424,7 +424,7 @@ property. The request is specified by . + The name of the cookie is specified by the property. The request is specified by . ]]> @@ -453,7 +453,7 @@ + The request is specified by ]]> @@ -572,7 +572,7 @@ ## Remarks Controls whether the "Secure" flag in the Set-Cookie header is emitted for any cookies written. If this value is `true`, the session cookies will only be available over HTTPS. - This property corresponds to the property. + This property corresponds to the property. The property can be initialized by specifying the `requireSSL` attribute on the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element in configuration. @@ -607,7 +607,7 @@ . If the `isPersistent` parameter is `true`, the cookie expiration time is set to the value of the property if it is not `null` or, if the property is `null`, the expiration time is set to the value of the `tokenExpirationTime` parameter. + If the `isPersistent` parameter is `false`, the cookie expiration time is set to . If the `isPersistent` parameter is `true`, the cookie expiration time is set to the value of the property if it is not `null` or, if the property is `null`, the expiration time is set to the value of the `tokenExpirationTime` parameter. The cookie name, domain and path are specified by the , , and properties. The request is specified by . Whether the cookie should be sent only over SSL is specified by the property and whether the cookie should be hidden from client-side scripts is specified by the property. @@ -643,7 +643,7 @@ and properties. The request is specified by . The request is specified by . Whether the cookie should be sent only over SSL is specified by the property and whether the cookie should be hidden from client-side scripts is specified by the property. + The cookie domain and path are specified by the and properties. The request is specified by . The request is specified by . Whether the cookie should be sent only over SSL is specified by the property and whether the cookie should be hidden from client-side scripts is specified by the property. ]]> diff --git a/xml/System.IdentityModel.Services/CookieHandlerElement.xml b/xml/System.IdentityModel.Services/CookieHandlerElement.xml index e6e7781d8c561..05e0ead184743 100644 --- a/xml/System.IdentityModel.Services/CookieHandlerElement.xml +++ b/xml/System.IdentityModel.Services/CookieHandlerElement.xml @@ -16,7 +16,7 @@ ` element is a child element of the `` element; the property is set to an instance of the class. The `` element is used to configure the cookie handler used by the Session Authentication Module (SAM), which is represented by the class. + The `` element is a child element of the `` element; the property is set to an instance of the class. The `` element is used to configure the cookie handler used by the Session Authentication Module (SAM), which is represented by the class. A cookie handler can be configured in one of the following ways: @@ -69,7 +69,7 @@ ` child element of the `` element. It specifies a chunked cookie handler, an instance of the class, to use. If it is set, the property should be set to either or . If the property is set to either of these values but the property is not set, a chunked cookie handler with the default chunk size () is configured. + This property is equivalent to the `` child element of the `` element. It specifies a chunked cookie handler, an instance of the class, to use. If it is set, the property should be set to either or . If the property is set to either of these values but the property is not set, a chunked cookie handler with the default chunk size () is configured. Either the property or the property may be set, but not both. diff --git a/xml/System.IdentityModel.Services/FederatedAuthentication.xml b/xml/System.IdentityModel.Services/FederatedAuthentication.xml index 6d20eef274bd8..07a83105376f1 100644 --- a/xml/System.IdentityModel.Services/FederatedAuthentication.xml +++ b/xml/System.IdentityModel.Services/FederatedAuthentication.xml @@ -18,10 +18,10 @@ ## Remarks You can access the modules that are configured for the web application through the static properties exposed by the class. The method provides an extension point through which other application-defined modules that derive from and that are configured for the application can be accessed. - The property references a singleton instance of that provides configuration settings for the HTTP modules. The first time the property is accessed by one of the HTTP modules, a instance is initialized from the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element in the configuration file and the is raised to provide an application with the opportunity to modify the configuration object before it is used to initialize module properties. The same instance is returned on each subsequent access of the property. + The property references a singleton instance of that provides configuration settings for the HTTP modules. The first time the property is accessed by one of the HTTP modules, a instance is initialized from the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element in the configuration file and the is raised to provide an application with the opportunity to modify the configuration object before it is used to initialize module properties. The same instance is returned on each subsequent access of the property. > [!IMPORTANT] -> The claims authorization manager () that is used to evaluate claims based access checks when using the class or the class is configured on the object that is set on the federation configuration object referenced through the property. This is true for all applications whether they are ASP.NET applications or not. +> The claims authorization manager () that is used to evaluate claims based access checks when using the class or the class is configured on the object that is set on the federation configuration object referenced through the property. This is true for all applications whether they are ASP.NET applications or not. ]]> @@ -64,14 +64,14 @@ object is created and initialized from the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element in the configuration file the first time this property is accessed by one of the HTTP modules. Just after the configuration object has been initialized, the event is raised to provide a developer with an opportunity to modify the newly created configuration object before it is used to initialize any of the configured HTTP modules. It can be accessed from the property in an event handler. + A object is created and initialized from the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element in the configuration file the first time this property is accessed by one of the HTTP modules. Just after the configuration object has been initialized, the event is raised to provide a developer with an opportunity to modify the newly created configuration object before it is used to initialize any of the configured HTTP modules. It can be accessed from the property in an event handler. On subsequent accesses, the same configuration instance is returned. - Depending on whether specific modules are present, the property is accessed from within the following methods during initialization: , , and . + Depending on whether specific modules are present, the property is accessed from within the following methods during initialization: , , and . > [!IMPORTANT] -> The claims authorization manager () that is used to evaluate claims based access checks when using the class or the class is configured on the object that is set on the federation configuration object referenced through the property. This is true for all applications whether they are ASP.NET applications or not. +> The claims authorization manager () that is used to evaluate claims based access checks when using the class or the class is configured on the object that is set on the federation configuration object referenced through the property. This is true for all applications whether they are ASP.NET applications or not. ]]> @@ -96,7 +96,7 @@ event is raised when the first HTTP module in the web application references property. The first access of the this property causes a object to be created and initialized from the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element in the configuration file. You can access the newly created object through the property in an event handler in order to examine or modify it before it is used to provide initialization for any of the HTTP modules configured for the application. + The event is raised when the first HTTP module in the web application references property. The first access of the this property causes a object to be created and initialized from the [<federationConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/federationconfiguration.md) element in the configuration file. You can access the newly created object through the property in an event handler in order to examine or modify it before it is used to provide initialization for any of the HTTP modules configured for the application. ]]> diff --git a/xml/System.IdentityModel.Services/HttpModuleBase.xml b/xml/System.IdentityModel.Services/HttpModuleBase.xml index 6d819509ad5b8..bde663fbf1906 100644 --- a/xml/System.IdentityModel.Services/HttpModuleBase.xml +++ b/xml/System.IdentityModel.Services/HttpModuleBase.xml @@ -100,7 +100,7 @@ method by initializing the property to the value of the property, invoking the method, and then invoking the method. + This method implements the method by initializing the property to the value of the property, invoking the method, and then invoking the method. Derived classes override the and methods. diff --git a/xml/System.IdentityModel.Services/ServiceCertificateElement.xml b/xml/System.IdentityModel.Services/ServiceCertificateElement.xml index 9d80bf1ebae82..f5350a9b1fb8d 100644 --- a/xml/System.IdentityModel.Services/ServiceCertificateElement.xml +++ b/xml/System.IdentityModel.Services/ServiceCertificateElement.xml @@ -18,7 +18,7 @@ ## Remarks The `` element is a child element of the `` element and configures the X.509 certificate, if any, that is used to encrypt and decrypt tokens when using WS-Federation. - The property is an instance of . + The property is an instance of . ]]> diff --git a/xml/System.IdentityModel.Services/SessionAuthenticationModule.xml b/xml/System.IdentityModel.Services/SessionAuthenticationModule.xml index d7e6f93417bf5..9d32ac57c2c54 100644 --- a/xml/System.IdentityModel.Services/SessionAuthenticationModule.xml +++ b/xml/System.IdentityModel.Services/SessionAuthenticationModule.xml @@ -18,7 +18,7 @@ ## Remarks When present in the ASP.NET pipeline, the (SAM) processes session cookies in WS-Federation scenarios. It uses the cookie handler specified by the property to read the raw session cookie from the HTTP request and write it to the HTTP response. It uses the that is configured for an application to deserialize the raw session cookie into objects. The session security token contains the claims () and principal () associated with the entity for which the request is being served. - The SAM adds its event handler to the event in the ASP.NET pipeline. This handler intercepts sign-in requests, and, if there is a session cookie, deserializes it into a session token, and sets the and properties to the claims principal contained in the session token. It invokes several of the other methods exposed by the SAM during this process. + The SAM adds its event handler to the event in the ASP.NET pipeline. This handler intercepts sign-in requests, and, if there is a session cookie, deserializes it into a session token, and sets the and properties to the claims principal contained in the session token. It invokes several of the other methods exposed by the SAM during this process. The method can be invoked to sign the user out of a session (for example, in a SignOut.aspx.cs code-behind file). @@ -98,7 +98,7 @@ method is called from the method. It calls the method to validate the incoming token and update the and the properties. If the `writeCookie` parameter is `true`, the method is invoked to write the session token to a cookie. + The method is called from the method. It calls the method to validate the incoming token and update the and the properties. If the `writeCookie` parameter is `true`, the method is invoked to write the session token to a cookie. ]]> @@ -166,7 +166,7 @@ property is initialized by the method. This method initializes the property based on the cookie handler specified on the object that is set on the property. You can set the cookie handler in a configuration file through the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element. + The property is initialized by the method. This method initializes the property based on the cookie handler specified on the object that is set on the property. You can set the cookie handler in a configuration file through the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element. ]]> @@ -251,7 +251,7 @@ and the handlers to the and events of the application object specified by the `context` parameter. + Adds the and the handlers to the and events of the application object specified by the `context` parameter. ]]> @@ -276,7 +276,7 @@ property from the handler specified in configuration by the object that is set on the property. You can specify the cookie handler in a configuration file through the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element. + Initializes the property from the handler specified in configuration by the object that is set on the property. You can specify the cookie handler in a configuration file through the [<cookieHandler>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/cookiehandler.md) element. ]]> @@ -305,7 +305,7 @@ In reference mode, the is stored in a server-side cache (an object that derives from ). The issued cookie just contains a context identifier that is used to retrieve the token from the cache. > [!IMPORTANT] -> To operate in reference mode, Microsoft recommends providing a handler for the event in the global.asax.cs file and setting the property on the token passed in the property. This will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. +> To operate in reference mode, Microsoft recommends providing a handler for the event in the global.asax.cs file and setting the property on the token passed in the property. This will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. ]]> @@ -341,15 +341,15 @@ 2. If a session security token cannot be read (most likely because a session has not been established), return. -3. Invokes the method to raise the event. This provides an opportunity for the token read from the cookie to be modified or for the request to be canceled. The handler can also specify that the token should be reissued, by setting the property. +3. Invokes the method to raise the event. This provides an opportunity for the token read from the cookie to be modified or for the request to be canceled. The handler can also specify that the token should be reissued, by setting the property. -4. If the token is to be reissued, removes it from the cache and invokes the method to raise the event. This provides opportunity for the token to again be modified. The reissue behavior can also be modified by setting the property in the event handler. +4. If the token is to be reissued, removes it from the cache and invokes the method to raise the event. This provides opportunity for the token to again be modified. The reissue behavior can also be modified by setting the property in the event handler. -5. Invokes the method to authenticate the user. If successful, this has the effect of setting the property to the principal that is contained in the property of the incoming token. +5. Invokes the method to authenticate the user. If successful, this has the effect of setting the property to the principal that is contained in the property of the incoming token. 6. If the session has expired, invokes the method. - The method is added to the handlers for the event in the method. + The method is added to the handlers for the event in the method. ]]> @@ -382,7 +382,7 @@ ## Remarks The default implementation is empty. - The handler is added to the handlers for the event in the method. + The handler is added to the handlers for the event in the method. ]]> @@ -575,7 +575,7 @@ You can use this event to modify properties of the session token before it is passed further along the pipeline and is used to authenticate the entity making the request (user). - In an event handler, you can access the token through the property. After modifying the token, you can ensure that it is written back to the cookie by setting the property to `true`. Unlike, the event, is not a cancelable event. + In an event handler, you can access the token through the property. After modifying the token, you can ensure that it is written back to the cookie by setting the property to `true`. Unlike, the event, is not a cancelable event. @@ -608,9 +608,9 @@ ## Remarks The event is raised from within the method after a session token () has been successfully read from the session cookie. - You can use this event to modify properties of the session token before it is passed further along the pipeline and is used to authenticate the entity making the request (user). One of the most common scenarios involves modifying the session expiration time (accessible through the property) to override the session expiration time set in configuration through the `lifetime` attribute of the [<sessionTokenRequirement>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/sessiontokenrequirement.md) element. By modifying this property on each request, you can implement a sliding session; that is, a session in which the lifetime is extended each time the user accesses the site. + You can use this event to modify properties of the session token before it is passed further along the pipeline and is used to authenticate the entity making the request (user). One of the most common scenarios involves modifying the session expiration time (accessible through the property) to override the session expiration time set in configuration through the `lifetime` attribute of the [<sessionTokenRequirement>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/sessiontokenrequirement.md) element. By modifying this property on each request, you can implement a sliding session; that is, a session in which the lifetime is extended each time the user accesses the site. - In an event handler, you can access the token through the property. After modifying the token, you can ensure that it is written back to the cookie by setting the to `true`. Finally, the event is a cancelable event, and you can set the property of the to abort further processing of the request. + In an event handler, you can access the token through the property. After modifying the token, you can ensure that it is written back to the cookie by setting the to `true`. Finally, the event is a cancelable event, and you can set the property of the to abort further processing of the request. @@ -645,7 +645,7 @@ method and sets the property and the property on using the identities that are returned. + Invokes the method and sets the property and the property on using the identities that are returned. This method is called from the method. @@ -773,7 +773,7 @@ ## Remarks Raised from the method when an error occurs during sign-out. - In an event handler, you can get the exception that resulted in the event being raised from the property. You can cancel further processing of the exception, which has the result of not propagating the exception to the client, by setting the property of the to `true`. + In an event handler, you can get the exception that resulted in the event being raised from the property. You can cancel further processing of the exception, which has the result of not propagating the exception to the client, by setting the property of the to `true`. This event is not guaranteed to be called for every session. For example, the cookies may be deleted at the client-side, in which case, this event would never be raised because there is no server-side event for deleting the session. @@ -841,7 +841,7 @@ method. It invokes the method of the configured session token handler to validate the token and extract its identities. + This method is called from the method. It invokes the method of the configured session token handler to validate the token and extract its identities. ]]> diff --git a/xml/System.IdentityModel.Services/SessionSecurityTokenCreatedEventArgs.xml b/xml/System.IdentityModel.Services/SessionSecurityTokenCreatedEventArgs.xml index 07c8b85b2f8d6..7634b825b3e71 100644 --- a/xml/System.IdentityModel.Services/SessionSecurityTokenCreatedEventArgs.xml +++ b/xml/System.IdentityModel.Services/SessionSecurityTokenCreatedEventArgs.xml @@ -18,7 +18,7 @@ ## Remarks By default: -- In the session authentication module (SAM) the event is raised from within the method after a session token () has been created. This happens, for example, if an event handler for the event modifies the token. You can use the to modify the session token before it is passed further along the pipeline and is used to authenticate the entity making the request (user). +- In the session authentication module (SAM) the event is raised from within the method after a session token () has been created. This happens, for example, if an event handler for the event modifies the token. You can use the to modify the session token before it is passed further along the pipeline and is used to authenticate the entity making the request (user). - In the WS-Federation authentication module (WSFAM), the event is raised from the request processing pipeline just after a session token has been created from the WS-Federation sign-in response message received from the STS and just before the SAM is called to set the thread principal and write the session cookie. diff --git a/xml/System.IdentityModel.Services/SessionSecurityTokenReceivedEventArgs.xml b/xml/System.IdentityModel.Services/SessionSecurityTokenReceivedEventArgs.xml index c92dc21e64c31..482f2c28b7ab5 100644 --- a/xml/System.IdentityModel.Services/SessionSecurityTokenReceivedEventArgs.xml +++ b/xml/System.IdentityModel.Services/SessionSecurityTokenReceivedEventArgs.xml @@ -16,7 +16,7 @@ event is raised from within the method after a session token () has been successfully read from the session cookie. In the event handler, you can modify properties of the session token before it is passed further along the pipeline and is used to authenticate the entity making the request (user). + By default, the event is raised from within the method after a session token () has been successfully read from the session cookie. In the event handler, you can modify properties of the session token before it is passed further along the pipeline and is used to authenticate the entity making the request (user). You can access the token through the property. After modifying the token, you can ensure that it is written back to the cookie by setting the to `true`. Finally, the event is a cancelable event, and you can set the property (inherited from ) to abort further processing of the request. diff --git a/xml/System.IdentityModel.Services/WSFederationAuthenticationModule.xml b/xml/System.IdentityModel.Services/WSFederationAuthenticationModule.xml index e86dd4275cdcc..99c59cdc66d27 100644 --- a/xml/System.IdentityModel.Services/WSFederationAuthenticationModule.xml +++ b/xml/System.IdentityModel.Services/WSFederationAuthenticationModule.xml @@ -20,7 +20,7 @@ ## Remarks The class implements an HTTP module known as the WS-Federation Authentication Module (WSFAM). The WSFAM is implemented out of the box by Windows Identity Foundation (WIF). The WSFAM is added to the ASP.NET pipeline by making an entry in the web.config file. It derives from , which implements . It registers with the ASP.NET runtime to listen for the and events. Listening to the event, lets the WSFAM redirect clients to a security token service (STS) to obtain a security token when authorization fails on a requested resource. Listening to the event enables the WSFAM to monitor HTTP requests for a response from the STS that contains the requested token. When such a token is present and valid, it creates an instance of for the authenticated user using the claims that are present in the token. - When using the WSFAM, session management is provided by a session authentication module (SAM), which is an instance of the class, or a class derived from it. The SAM is also added to the ASP.NET pipeline in the configuration file. The SAM monitors requests for authentication (session) cookies. When these cookies are present and valid, the module extracts the for the authenticated user from the and sets the property and the thread principal properties. + When using the WSFAM, session management is provided by a session authentication module (SAM), which is an instance of the class, or a class derived from it. The SAM is also added to the ASP.NET pipeline in the configuration file. The SAM monitors requests for authentication (session) cookies. When these cookies are present and valid, the module extracts the for the authenticated user from the and sets the property and the thread principal properties. The WSFAM provides: @@ -166,7 +166,7 @@ ## Remarks The event is raised when authorization has failed for an HTTP request. It is raised from within the event-handler delegate through a call to the method. - You can set the property to control whether the request is redirected to the identity provider. The framework initializes this property to `false` if the user has already been authenticated. In this case, setting the property to `true` may cause a circular loop with the STS. + You can set the property to control whether the request is redirected to the identity provider. The framework initializes this property to `false` if the user has already been authenticated. In this case, setting the property to `true` may cause a circular loop with the STS. > [!NOTE] > The event can be used to modify the URL or cancel the redirect. @@ -225,7 +225,7 @@ ## Remarks This method is invoked from the request processing pipeline to determine whether the incoming HTTP request is a FORM post that contains a WS-Federation sign-in response message. - It invokes the overload with the `onPage` parameter set `false` to indicate that the call did not originate while processing a page. + It invokes the overload with the `onPage` parameter set `false` to indicate that the call did not originate while processing a page. ]]> @@ -260,13 +260,13 @@ overload to determine whether the incoming HTTP request is a form POST that contains a WS-Federation sign-in response message. + This method is invoked from the request processing pipeline through the overload to determine whether the incoming HTTP request is a form POST that contains a WS-Federation sign-in response message. The default implementation performs the following: - If the incoming request is a form POST, it calls the method to determine whether the form POST contains a sign-in response. -- If the incoming request is not a form POST, and the request contains a WS-Federation sign-out clean-up request (the wa parameter is "wsignoutcleanup1.0"), sign-out clean-up is performed. In this case, the method is invoked (with the parameter set to `true` to indicate a sign-out clean-up) to sign out of the session. This also causes the sign-out events to be raised. +- If the incoming request is not a form POST, and the request contains a WS-Federation sign-out clean-up request (the wa parameter is "wsignoutcleanup1.0"), sign-out clean-up is performed. In this case, the method is invoked (with the parameter set to `true` to indicate a sign-out clean-up) to sign out of the session. This also causes the sign-out events to be raised. Next, if the sign-out clean-up request contains a wreply parameter, the client is redirected to the URL returned by the method; otherwise, an image of a green check mark is returned to the STS. The receipt of this image can be used by the STS as a confirmation that the sign-out clean-up request was received and successfully processed by the RP. @@ -360,14 +360,14 @@ 1. Creates a WS-Federation sign-out request message by using the specified parameters. -2. Calls the method on the SAM to delete the session cookie. +2. Calls the method on the SAM to delete the session cookie. 3. Redirects to the STS using the sign-out request message from the first step. None of the sign-out events: , , or are raised by this method. To delete the session without sending a sign-out request message to the STS, call one of the overloaded methods. > [!NOTE] -> To perform passive sign-out by using the session token, the module relies on a value that was stored in the property during sign-in, for more information, see the method. +> To perform passive sign-out by using the session token, the module relies on a value that was stored in the property during sign-in, for more information, see the method. ]]> @@ -466,7 +466,7 @@ method from inside the processing pipeline to resolve the URL specified in the wresultptr parameter in the sign-in response message received from a security token service (STS). + Called by the method from inside the processing pipeline to resolve the URL specified in the wresultptr parameter in the sign-in response message received from a security token service (STS). By default this method throws a . Override this method in a derived class to support the wresultptr parameter. The URL points to the issuance result, which should be one of the following: a `` element, a `` element, a SOAP response, or a SOAP `` element. @@ -533,7 +533,7 @@ method to get the token and reads it by using the appropriate handler from the configured security token handlers. + The default implementation invokes the method to get the token and reads it by using the appropriate handler from the configured security token handlers. ]]> @@ -566,7 +566,7 @@ ## Remarks Called from the request processing pipeline to get the WS-Federation sign-in request message as a object. - The default implementation invokes the method to get a object and then invokes the overload. + The default implementation invokes the method to get a object and then invokes the overload. Use a derived class to interpret a specific type of request. @@ -596,7 +596,7 @@ method is called from the request processing pipeline when processing a WS-Federation sign-in response message to get the value to store in the property inside the session cookie. + The method is called from the request processing pipeline when processing a WS-Federation sign-in response message to get the value to store in the property inside the session cookie. You can override this method to provide an application-specific value to be stored in the cookie. WSFAM does not expose any methods to retrieve the value from the cookie. You must provide the logic in your application to read the value back from the cookie if it is needed. @@ -628,7 +628,7 @@ method in the request processing pipeline to get a sign-in response message from the form POST contained in the HTTP request. + Called from the method in the request processing pipeline to get a sign-in response message from the form POST contained in the HTTP request. ]]> @@ -662,7 +662,7 @@ ## Remarks This method is called from the method in the request processing pipeline to determine the URL to redirect to after processing a WS-Federation sign-out clean-up request. It is only invoked if the message has a wreply parameter (the `signOutMessage` parameter has a property that is neither `null` nor empty). - The default implementation validates the reply URL contained in the message (the property) against the address of the security token service (STS) that is specified by the property. The following conditions must be true for the reply URL to be valid: + The default implementation validates the reply URL contained in the message (the property) against the address of the security token service (STS) that is specified by the property. The following conditions must be true for the reply URL to be valid: 1. The reply URL is an absolute URL. @@ -796,9 +796,9 @@ |Event|Handler| |-----------|-------------| -||| -||| -||| +||| +||| +||| > [!NOTE] > The module properties, such as , are initialized from the method. @@ -828,7 +828,7 @@ object specified by the property. + Module properties are initialized using the equivalent properties of the object specified by the property. You can specify settings in a configuration file through the [<wsFederation>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/wsfederation.md) element. @@ -928,7 +928,7 @@ method implements the WS-Federation request processing pipeline. It is added to the event in the [!INCLUDE[vstecasp](~/includes/vstecasp-md.md)] pipeline by the method. + The method implements the WS-Federation request processing pipeline. It is added to the event in the [!INCLUDE[vstecasp](~/includes/vstecasp-md.md)] pipeline by the method. The method performs the following: @@ -936,13 +936,13 @@ 2. Calls the method to deserialize a object from the request. -3. Raises the event. You can cancel further processing or modify the received security token in a handler for this event. A handler is typically used to modify the or properties. +3. Raises the event. You can cancel further processing or modify the received security token in a handler for this event. A handler is typically used to modify the or properties. 4. Validates the security token and creates a object from the claims in the security token. 5. Raises the event. You can cancel further processing or modify the claims principal in a handler for this event. -6. Uses the configured session authentication module (SAM) to create a object. (The configured SAM is the object returned by the property.) The session token is created by using the claims principal returned in step 5. The and properties are set by using the and properties of the returned in step 3 and are validated against the current time and the token lifetime specified by either the or the property of the object in the token handler collection being used by WSFAM. The token lifetime on the session token handler can be specified in configuration through the [<sessionTokenRequirement>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/sessiontokenrequirement.md) element. Note: The property on the cookie handler configured for the SAM is not used. +6. Uses the configured session authentication module (SAM) to create a object. (The configured SAM is the object returned by the property.) The session token is created by using the claims principal returned in step 5. The and properties are set by using the and properties of the returned in step 3 and are validated against the current time and the token lifetime specified by either the or the property of the object in the token handler collection being used by WSFAM. The token lifetime on the session token handler can be specified in configuration through the [<sessionTokenRequirement>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/sessiontokenrequirement.md) element. Note: The property on the cookie handler configured for the SAM is not used. 7. Calls the method with the session token to write the session cookie. The method first raises the event. You can change properties on the session token or change whether the cookie should be persisted in a handler for this event. After the event is raised, the method then writes the cookie using the SAM. @@ -981,7 +981,7 @@ ## Remarks Called from the event-handler delegate when authorization has failed. - Initializes the property before raising the event to prevent circular redirects if the user has already been authenticated. If the user is already authenticated, the property is initialized to `false` to prevent redirects; otherwise, it is initialized to `true`. + Initializes the property before raising the event to prevent circular redirects if the user has already been authenticated. If the user is already authenticated, the property is initialized to `false` to prevent redirects; otherwise, it is initialized to `true`. ]]> @@ -1132,7 +1132,7 @@ method just after the session is deleted. + Called from the method just after the session is deleted. ]]> @@ -1181,7 +1181,7 @@ method just before the session is deleted. + Called from the method just before the session is deleted. ]]> @@ -1209,7 +1209,7 @@ method if an exception occurs during processing. + Called from the method if an exception occurs during processing. ]]> @@ -1349,7 +1349,7 @@ property. For example, you can modify the property in the sign-in message to change the identity provider to which the request will be redirected. The event is a cancelable event and you can set the property to `true` to cancel the redirect. + You can access and modify the WS-Federation sign-in request through the property. For example, you can modify the property in the sign-in message to change the identity provider to which the request will be redirected. The event is a cancelable event and you can set the property to `true` to cancel the redirect. The event is raised from inside the method through a call to the method. @@ -1579,7 +1579,7 @@ property. The event is a cancelable event, you can set the property to `true` in an event handler to terminate processing of the WS-Federation sign-in response message. + You can add an event handler to modify the token before it is validated. In the event handler you can access the security token through the property. The event is a cancelable event, you can set the property to `true` in an event handler to terminate processing of the WS-Federation sign-in response message. This event is raised from inside the event-handler delegate when processing a WS-Federation sign-in response message ("wsignin1.0") received from the security token service (STS). It is raised just after a security token has been deserialized from the wresult or the wresultptr parameter in the sign-in response message, but before the security token is validated. @@ -1641,12 +1641,12 @@ property. You can specify whether a session cookie should be written by setting the property. + You can add an event handler to modify the session token before it is used to set the thread principal and is written to the session cookie. In the event handler, you can access the session token through the property. You can specify whether a session cookie should be written by setting the property. - This event is raised from inside the event-handler delegate when processing a WS-Federation sign-in response message ("wsignin1.0") received from the security token service (STS). It is raised just after the security token that was deserialized from the wresult or the wresultptr parameter in the sign-in response message has been validated, and before the claims principal is set on the (and on the property of ). + This event is raised from inside the event-handler delegate when processing a WS-Federation sign-in response message ("wsignin1.0") received from the security token service (STS). It is raised just after the security token that was deserialized from the wresult or the wresultptr parameter in the sign-in response message has been validated, and before the claims principal is set on the (and on the property of ). > [!IMPORTANT] -> To operate sessions in reference mode, Microsoft recommends providing a handler for the event in the global.asax.cs file and setting the property on the token passed in the property. This will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. +> To operate sessions in reference mode, Microsoft recommends providing a handler for the event in the global.asax.cs file and setting the property on the token passed in the property. This will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. @@ -1741,7 +1741,7 @@ method from inside the method while signing out of the session at the relying party (RP). The event is not raised when doing federated sign-out through the method. + This event is raised through a call to the method from inside the method while signing out of the session at the relying party (RP). The event is not raised when doing federated sign-out through the method. You can add an event handler to perform any additional processing that is needed by your application after the session cookie has been deleted. @@ -1850,7 +1850,7 @@ method from inside the method while signing out of the session at the relying party (RP). The event is not raised when doing federated sign-out through the method. + This event is raised through a call to the method from inside the method while signing out of the session at the relying party (RP). The event is not raised when doing federated sign-out through the method. You can add an event handler to perform any additional processing that is needed by your application before the session cookie is deleted. You can read the property in the event handler to determine whether the sign-out is the result of receiving a WS-Federation sign-out clean-up request message ("wsignoutcleanup1.0") from a security token service (STS) or whether it was initiated at the RP. @@ -1928,7 +1928,7 @@ ## Remarks Deletes the current session and redirects the browser back to the URL specified in the current HTTP request. - Invokes the method with the `redirectUrl` parameter set to the URL of the current request. + Invokes the method with the `redirectUrl` parameter set to the URL of the current request. No sign-out request message ("wsignout1.0") is sent to the security token service (STS). To sign-out at the STS using WS-Federation protocol, use the method. @@ -1961,15 +1961,15 @@ ## Remarks This method performs the actual work of deleting the current session and raising the appropriate sign-out events. The method does the following: -1. Invokes the method to raise the event. An event handler can provide any necessary processing before the session is deleted. The property is set according to the `isIPRequest` parameter. +1. Invokes the method to raise the event. An event handler can provide any necessary processing before the session is deleted. The property is set according to the `isIPRequest` parameter. -2. Calls the method on the current session authentication manager to delete the session cookie. +2. Calls the method on the current session authentication manager to delete the session cookie. Invokes the method to raise the event. 3. If an error occurs during sign-out processing, invokes the method to raise the event. An event handler can cancel the processing and prevent an exception from being returned to the caller of - You can call the method with the `isIPRequest` parameter set `false` to sign out of a session without performing a redirect. The method is ultimately called by all of the other overloaded methods (with the `isIPRequest` parameter set to `false`) to perform the sign out handling. The method is called from the method with the `isIPRequest` parameter set `true` to sign out of the session when it is processing a WS-Federation sign-out clean-up message ("wsignoutcleanup1.0"). + You can call the method with the `isIPRequest` parameter set `false` to sign out of a session without performing a redirect. The method is ultimately called by all of the other overloaded methods (with the `isIPRequest` parameter set to `false`) to perform the sign out handling. The method is called from the method with the `isIPRequest` parameter set `true` to sign out of the session when it is processing a WS-Federation sign-out clean-up message ("wsignoutcleanup1.0"). No sign-out request message ("wsignout1.0") is sent to the security token service (STS). To sign-out at the STS using WS-Federation protocol, use the method. @@ -2001,7 +2001,7 @@ ## Remarks Deletes the current session and redirects the browser back to the specified URL. - Invokes the method with the `redirectUrl` parameter and with the `initiateSignoutCleanup` set `false`. + Invokes the method with the `redirectUrl` parameter and with the `initiateSignoutCleanup` set `false`. No sign-out request message ("wsignout1.0") is sent to the security token service (STS). To sign-out at the STS using WS-Federation protocol, use the method. @@ -2037,7 +2037,7 @@ ## Remarks Deletes the current session and redirects the browser back to the specified URL. - Invokes the method with the `initiateSignoutCleanup` parameter set `false`. + Invokes the method with the `initiateSignoutCleanup` parameter set `false`. No sign-out request message ("wsignout1.0") is sent to the security token service (STS). To sign-out at the STS using WS-Federation protocol, use the method. @@ -2066,7 +2066,7 @@ method from inside the method while signing out of the session at the relying party (RP). The event is not raised when doing federated sign-out through the method. + This event is raised through a call to the method from inside the method while signing out of the session at the relying party (RP). The event is not raised when doing federated sign-out through the method. The event is a cancellable event. You can set the property in an event handler to prevent the exception that caused the error from being returned to the initiator of the sign-out. diff --git a/xml/System.IdentityModel.Tokens/BootstrapContext.xml b/xml/System.IdentityModel.Tokens/BootstrapContext.xml index a609277767c28..0bb1acc44b7eb 100644 --- a/xml/System.IdentityModel.Tokens/BootstrapContext.xml +++ b/xml/System.IdentityModel.Tokens/BootstrapContext.xml @@ -158,7 +158,7 @@ constructor was used; otherwise it is `null`. + This property is only set if the constructor was used; otherwise it is `null`. ]]> @@ -183,7 +183,7 @@ constructor was used; otherwise it is `null`. + This property is only set if the constructor was used; otherwise it is `null`. ]]> @@ -208,7 +208,7 @@ constructor was used; otherwise it is `null`. + This property is only set if the constructor was used; otherwise it is `null`. ]]> @@ -233,7 +233,7 @@ constructor was used; otherwise it is `null`. + This property is only set if the constructor was used; otherwise it is `null`. ]]> diff --git a/xml/System.IdentityModel.Tokens/IssuerNameRegistry.xml b/xml/System.IdentityModel.Tokens/IssuerNameRegistry.xml index 207839a976f64..d24baaf63365b 100644 --- a/xml/System.IdentityModel.Tokens/IssuerNameRegistry.xml +++ b/xml/System.IdentityModel.Tokens/IssuerNameRegistry.xml @@ -22,11 +22,11 @@ ## Remarks The issuer name registry is used to associate a mnemonic name to the cryptographic material needed to verify signatures of tokens produced by the corresponding issuer. This name is then used to set the or the property of a claim. The methods exposed by the class are called from the pipeline by the security token handler that is processing the token. Tokens signed by material that is not mapped by an issuer name registry are discarded as untrusted. The name returned by the issuer name registry should be unique within the context of an RP application. - In code, you can specify the issuer name registry to use by setting the property. In a configuration file, the issuer name registry can be specified by specifying the [<issuerNameRegistry>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/issuernameregistry.md) element under the [<securityTokenHandlerConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/securitytokenhandlerconfiguration.md) element. + In code, you can specify the issuer name registry to use by setting the property. In a configuration file, the issuer name registry can be specified by specifying the [<issuerNameRegistry>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/issuernameregistry.md) element under the [<securityTokenHandlerConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/securitytokenhandlerconfiguration.md) element. Windows Identity Foundation (WIF) provides an implementation of the class out of the box: the class. When you use this implementation you can specify the list of trusted issuers in the configuration file of the RP application under the [<trustedIssuers>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/trustedissuers.md) element, which is a child element of the `` element when the .class is referenced in that element’s `type` attribute. Under the `` element, each issuer name is mapped to the X.509 certificate that should be used to verify its signature. - To create a custom issuer name registry, you must override the method. This method returns the issuer name for the specified security token. You can optionally override the method to provide a hinting mechanism when retrieving issuer names and the method if you want to provide an issuer name for Windows tokens that is different from . Override the method to enable your issuer name registry to be initialized from a configuration file. + To create a custom issuer name registry, you must override the method. This method returns the issuer name for the specified security token. You can optionally override the method to provide a hinting mechanism when retrieving issuer names and the method if you want to provide an issuer name for Windows tokens that is different from . Override the method to enable your issuer name registry to be initialized from a configuration file. @@ -150,7 +150,7 @@ method. + The default implementation ignores the `requestedIssuerName` parameter and simply calls the method. Called from the processing pipeline by the security token handler that is processing the token. The method should return a unique name for the issuer within the context of the RP application. diff --git a/xml/System.IdentityModel.Tokens/Saml2Action.xml b/xml/System.IdentityModel.Tokens/Saml2Action.xml index a9cf16778990f..66737b4aa6e38 100644 --- a/xml/System.IdentityModel.Tokens/Saml2Action.xml +++ b/xml/System.IdentityModel.Tokens/Saml2Action.xml @@ -18,7 +18,7 @@ ## Remarks The class specifies an action on a resource for which authorization is either requested, granted, or denied in a . - The represents a claim about the ability of the subject of a SAML 2 assertion to perform a specified set of actions on a specified resource. A can be added to the property to specify the desired action. The property represents the action and the property specifies the XML namespace in which the action is defined. The property specifies the resource on which the access decision applies, and the property specifies the access decision. + The represents a claim about the ability of the subject of a SAML 2 assertion to perform a specified set of actions on a specified resource. A can be added to the property to specify the desired action. The property represents the action and the property specifies the XML namespace in which the action is defined. The property specifies the resource on which the access decision applies, and the property specifies the access decision. [!INCLUDE[wif_saml2_ref](~/includes/wif-saml2-ref-md.md)] diff --git a/xml/System.IdentityModel.Tokens/Saml2Assertion.xml b/xml/System.IdentityModel.Tokens/Saml2Assertion.xml index 7e571f710a900..2ec4a2a245831 100644 --- a/xml/System.IdentityModel.Tokens/Saml2Assertion.xml +++ b/xml/System.IdentityModel.Tokens/Saml2Assertion.xml @@ -41,7 +41,7 @@ property is set to the value of the property. + The property is set to the value of the property. ]]> diff --git a/xml/System.IdentityModel.Tokens/Saml2AuthorizationDecisionStatement.xml b/xml/System.IdentityModel.Tokens/Saml2AuthorizationDecisionStatement.xml index 80b08fd0eabc8..9291b0ed4d230 100644 --- a/xml/System.IdentityModel.Tokens/Saml2AuthorizationDecisionStatement.xml +++ b/xml/System.IdentityModel.Tokens/Saml2AuthorizationDecisionStatement.xml @@ -16,7 +16,7 @@ security tokens specify their claims using SAML assertions, which can specify whether a subject is authorized to access a specific resource. The claims in a SAML assertion are represented by SAML statements. The SAML 2.0 specification defines a set of SAML statement types and one of them is represented by the class. When specified in a SAML 2.0 assertion in the property, a asserts an authorization decision regarding access by the subject of the assertion to a specified resource. The subject of the SAML 2.0 assertion is specified by the property. The following table summarizes the properties that are associated with the authorization decision. + security tokens specify their claims using SAML assertions, which can specify whether a subject is authorized to access a specific resource. The claims in a SAML assertion are represented by SAML statements. The SAML 2.0 specification defines a set of SAML statement types and one of them is represented by the class. When specified in a SAML 2.0 assertion in the property, a asserts an authorization decision regarding access by the subject of the assertion to a specified resource. The subject of the SAML 2.0 assertion is specified by the property. The following table summarizes the properties that are associated with the authorization decision. |Property|Description| |--------------|-----------------| diff --git a/xml/System.IdentityModel.Tokens/Saml2SecurityToken.xml b/xml/System.IdentityModel.Tokens/Saml2SecurityToken.xml index 95498bd10d2db..a56c8e5a975b3 100644 --- a/xml/System.IdentityModel.Tokens/Saml2SecurityToken.xml +++ b/xml/System.IdentityModel.Tokens/Saml2SecurityToken.xml @@ -97,7 +97,7 @@ ## Remarks For security tokens, the claims are specified using a SAML assertion. - Use a constructor or the method to set the property. + Use a constructor or the method to set the property. ]]> diff --git a/xml/System.IdentityModel.Tokens/Saml2Statement.xml b/xml/System.IdentityModel.Tokens/Saml2Statement.xml index ed017f55e24a4..2b27c558b77c8 100644 --- a/xml/System.IdentityModel.Tokens/Saml2Statement.xml +++ b/xml/System.IdentityModel.Tokens/Saml2Statement.xml @@ -16,7 +16,7 @@ class, which represents a SAML Attribute Statement, derives from this class. This class is also used to declare collections of SAML Statements in classes as in the property. + This abstract class provides no operations; however, it is the base class from which all classes that represent SAML statements derive. For example, the class, which represents a SAML Attribute Statement, derives from this class. This class is also used to declare collections of SAML Statements in classes as in the property. For more information about the StatementAbstractType, see the SAML V2.0 Core specification. diff --git a/xml/System.IdentityModel.Tokens/SecurityTokenElement.xml b/xml/System.IdentityModel.Tokens/SecurityTokenElement.xml index cf6027195ca9d..70feac1a9fada 100644 --- a/xml/System.IdentityModel.Tokens/SecurityTokenElement.xml +++ b/xml/System.IdentityModel.Tokens/SecurityTokenElement.xml @@ -43,7 +43,7 @@ ## Remarks When this constructor is used, the method is not supported by the new instance unless the method is overridden. - If the `securityToken` parameter is an instance of then the property is set to the value of the property. + If the `securityToken` parameter is an instance of then the property is set to the value of the property. ]]> @@ -108,7 +108,7 @@ object by using the constructor, then the method is called to return the security token. + If the current instance was not constructed explicitly from a object by using the constructor, then the method is called to return the security token. ]]> @@ -157,7 +157,7 @@ constructor. + This property is `null` unless the current instance was initialized by using the constructor. ]]> diff --git a/xml/System.IdentityModel.Tokens/SecurityTokenHandler.xml b/xml/System.IdentityModel.Tokens/SecurityTokenHandler.xml index ca499f04944e8..2dc1cc2f7388a 100644 --- a/xml/System.IdentityModel.Tokens/SecurityTokenHandler.xml +++ b/xml/System.IdentityModel.Tokens/SecurityTokenHandler.xml @@ -147,7 +147,7 @@ ## Remarks The default implementation returns `false` to indicate that the key identifier clause cannot be read. - A derived class checks the element that the reader is referring to in order to determine whether the instance can deserialize a key identifier clause. This is typically accomplished through a call to the method with the appropriate element and namespace strings specified. If you override , you must also override the method to provide the logic to deserialize the key identifier clause. + A derived class checks the element that the reader is referring to in order to determine whether the instance can deserialize a key identifier clause. This is typically accomplished through a call to the method with the appropriate element and namespace strings specified. If you override , you must also override the method to provide the logic to deserialize the key identifier clause. ]]> @@ -179,7 +179,7 @@ ## Remarks The default implementation always returns `false`. - If you override this method, you must also override the method to provide the logic to deserialize the token. + If you override this method, you must also override the method to provide the logic to deserialize the token. ]]> @@ -211,7 +211,7 @@ ## Remarks The default implementation always returns `false`. - A derived class checks the element that the reader is referring to in order to determine whether the instance can deserialize a security token. This is typically accomplished through a call to the method with the appropriate element and namespace strings specified. If you override , you must also override the method or the method to provide the logic to deserialize the key identifier clause. + A derived class checks the element that the reader is referring to in order to determine whether the instance can deserialize a security token. This is typically accomplished through a call to the method with the appropriate element and namespace strings specified. If you override , you must also override the method or the method to provide the logic to deserialize the key identifier clause. @@ -343,7 +343,7 @@ ## Remarks The property is typically set by the configuration infrastructure from the [<securityTokenHandlerConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/securitytokenhandlerconfiguration.md) element in the configuration file during application start up. - In derived classes, you use the property to access configuration settings; for example, the issuer name registry to use in the method can be accessed from the property of the configuration object. + In derived classes, you use the property to access configuration settings; for example, the issuer name registry to use in the method can be accessed from the property of the configuration object. ]]> @@ -509,7 +509,7 @@ of the token processed by the current instance is accessed through the property. The method returns the set of acceptable identifiers that can be used in messages to refer to the token type. For example, the URI value used in the `` element under the `` element to request a specific kind of token (represented by the property in the object model). + The of the token processed by the current instance is accessed through the property. The method returns the set of acceptable identifiers that can be used in messages to refer to the token type. For example, the URI value used in the `` element under the `` element to request a specific kind of token (represented by the property in the object model). @@ -578,7 +578,7 @@ ## Remarks By default this method throws a exception. - Override this method to provide the logic to deserialize a key identifier clause from XML. If you override this method, you should also override the method. + Override this method to provide the logic to deserialize a key identifier clause from XML. If you override this method, you should also override the method. ]]> @@ -613,7 +613,7 @@ By default this method throws a exception. - Override this method to provide functionality that can deserialize a security token from a string. If you override, this method, you should also override the method. + Override this method to provide functionality that can deserialize a security token from a string. If you override, this method, you should also override the method. ]]> @@ -648,7 +648,7 @@ By default this method throws a exception. - Override this method to provide the logic to deserialize a security token from XML. If you override this method, you should also override the method. Typically, in derived classes, if the method cannot deserialize the token from the referenced XML, it throws an . + Override this method to provide the logic to deserialize a security token from XML. If you override this method, you should also override the method. Typically, in derived classes, if the method cannot deserialize the token from the referenced XML, it throws an . @@ -692,9 +692,9 @@ > [!IMPORTANT] > Calling this method with untrusted data is a security risk. Call this method only with trusted data. For more information, see [Untrusted Data Security Risks](http://go.microsoft.com/fwlink/?LinkId=330378). - The default implementation ignores the `tokenResolver` parameter and delegates the call to the method. + The default implementation ignores the `tokenResolver` parameter and delegates the call to the method. - Override this method to provide the logic to deserialize a security token from XML. If you override this method, you should also override the method. Typically, in derived classes, if the method cannot deserialize the token from the referenced XML, it throws an . + Override this method to provide the logic to deserialize a security token from XML. If you override this method, you should also override the method. Typically, in derived classes, if the method cannot deserialize the token from the referenced XML, it throws an . ]]> @@ -817,9 +817,9 @@ The method is called by the infrastructure to validate and extract the claims from the deserialized security token. These claims are returned in the collection of objects returned by the method. In the typical case, this collection will contain a single identity. - In derived classes, validation typically includes validating the intended audience specified in the token against the audience URIs specified in the property of the token handler configuration object specified on the property. These URIs are typically set in the configuration file under the [<audienceUris>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/audienceuris.md) element. If the audience cannot be validated, an exception should be thrown. + In derived classes, validation typically includes validating the intended audience specified in the token against the audience URIs specified in the property of the token handler configuration object specified on the property. These URIs are typically set in the configuration file under the [<audienceUris>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/audienceuris.md) element. If the audience cannot be validated, an exception should be thrown. - When processing the token, the issuer is typically validated by passing the issuer token to one of the methods on the object that is configured for the handler through the property. The issuer name registry is typically configured through the [<issuerNameRegistry>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/issuernameregistry.md) element in the configuration file. The returns the name of the issuer. This name should be used to set the property in claims contained in the token. If the issuer name registry does not contain an entry for the issuer token, returns `null`. In this case a is typically thrown in derived classes, but this behavior is up to the designer of the class. + When processing the token, the issuer is typically validated by passing the issuer token to one of the methods on the object that is configured for the handler through the property. The issuer name registry is typically configured through the [<issuerNameRegistry>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/issuernameregistry.md) element in the configuration file. The returns the name of the issuer. This name should be used to set the property in claims contained in the token. If the issuer name registry does not contain an entry for the issuer token, returns `null`. In this case a is typically thrown in derived classes, but this behavior is up to the designer of the class. diff --git a/xml/System.IdentityModel.Tokens/SecurityTokenHandlerCollection.xml b/xml/System.IdentityModel.Tokens/SecurityTokenHandlerCollection.xml index 0439b857883af..f20919e0d619a 100644 --- a/xml/System.IdentityModel.Tokens/SecurityTokenHandlerCollection.xml +++ b/xml/System.IdentityModel.Tokens/SecurityTokenHandlerCollection.xml @@ -208,7 +208,7 @@ method on the token handlers () in the collection to determine whether the token can be read. + The method invokes the method on the token handlers () in the collection to determine whether the token can be read. ]]> diff --git a/xml/System.IdentityModel.Tokens/SessionSecurityToken.xml b/xml/System.IdentityModel.Tokens/SessionSecurityToken.xml index 39bae6ba89d54..5935cdf4f7a78 100644 --- a/xml/System.IdentityModel.Tokens/SessionSecurityToken.xml +++ b/xml/System.IdentityModel.Tokens/SessionSecurityToken.xml @@ -26,7 +26,7 @@ The property determines whether the session token is in reference mode or not. > [!IMPORTANT] -> To operate in reference mode, Microsoft recommends providing a handler for the event in the global.asax.cs file and setting the property on the token passed in the property. This will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. +> To operate in reference mode, Microsoft recommends providing a handler for the event in the global.asax.cs file and setting the property on the token passed in the property. This will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. The class provided with WIF serializes the session token as a WS-Secure Conversation `` element. @@ -60,16 +60,16 @@ ||`claimsPrincipal`| ||`null`| ||Set to a generated unique ID.| -||| +||| ||Set to a generated unique ID.| ||`false`| ||`false`| ||| -|| plus the property.| +|| plus the property.| ||`null`| ||Contains a generated 128 bit symmetric key. **Note:** The default implementation does not use this property. Signing and encryption keys are dictated by the cookie transforms applied by the that processes the token.| ||| -|| plus the property.| +|| plus the property.| ]]> @@ -129,16 +129,16 @@ ||`claimsPrincipal`| ||`context`| ||Set to a generated unique ID.| -||| +||| ||Set to a generated unique ID.| ||`false`| ||`false`| ||| -|| plus the property.| +|| plus the property.| ||`null`| ||Contains a generated 128 bit symmetric key. **Note:** The default implementation does not use this property. Signing and encryption keys are dictated by the cookie transforms applied by the that processes the token.| ||| -|| plus the property.| +|| plus the property.| ]]> @@ -178,7 +178,7 @@ ||`claimsPrincipal`| ||`null`| ||Set to a generated unique ID.| -||| +||| ||Set to a generated unique ID.| ||`false`| ||`false`| @@ -233,7 +233,7 @@ ||`claimsPrincipal`| ||`context`| ||Set to a generated unique ID.| -||| +||| ||Set to a generated unique ID.| ||`false`| ||`false`| @@ -242,7 +242,7 @@ ||`null`| ||Contains a generated 128 bit symmetric key. **Note:** The default implementation does not use this property. Signing and encryption keys are dictated by the cookie transforms applied by the that processes the token.| ||The value of the `validFrom` parameter, or, if `validFrom` is `null`, .| -||The value of the `validFrom` parameter. If `validFrom` is `null`, the value of the property (as determined by the `validFrom` parameter) plus the property.| +||The value of the `validFrom` parameter. If `validFrom` is `null`, the value of the property (as determined by the `validFrom` parameter) plus the property.| ]]> @@ -298,7 +298,7 @@ ||`null`| ||Contains a generated 128 bit symmetric key. **Note:** The default implementation does not use this property. Signing and encryption keys are dictated by the cookie transforms applied by the that processes the token.| ||The value of the `validFrom` parameter, or, if `validFrom` is `null`, .| -||The value of the `validFrom` parameter. If `validFrom` is `null`, the value of the property (as determined by the `validFrom` parameter) plus the property.| +||The value of the `validFrom` parameter. If `validFrom` is `null`, the value of the property (as determined by the `validFrom` parameter) plus the property.| ]]> @@ -498,7 +498,7 @@ ||`null`| ||Contains single element that is either `key` or, if `key` is `null`, a generated 128 bit symmetric key. **Note:** The default implementation does not use this property. Signing and encryption keys are dictated by the cookie transforms applied by the that processes the token.| ||The value of the `validFrom` parameter, or, if `validFrom` is `null`, .| -||The value of the `validFrom` parameter. If `validFrom` is `null`, the value of the property (as determined by the `validFrom` parameter) plus the property.| +||The value of the `validFrom` parameter. If `validFrom` is `null`, the value of the property (as determined by the `validFrom` parameter) plus the property.| ]]> @@ -586,7 +586,7 @@ The class uses both the context ID and the key generation to generate a key for the token in the . - The class serializes this property as the `` child element of the `` element. For more information, see the documentation for the method. + The class serializes this property as the `` child element of the `` element. For more information, see the documentation for the method. ]]> @@ -661,7 +661,7 @@ class serializes this property as the `Id` attribute of the `` element. For more information, see the documentation for the method. + The class serializes this property as the `Id` attribute of the `` element. For more information, see the documentation for the method. ]]> @@ -716,7 +716,7 @@ In reference mode, a simple artifact is produced during serialization and the token material is stored in the token cache that is associated with the token handler. The token cache is an instance of a class that derives from . For Web Farm scenarios, the token cache must operate across all nodes in the farm. > [!IMPORTANT] -> To operate in reference mode, Microsoft recommends providing a handler for the event in the global.asax.cs file and setting the property on the token passed in the property. This will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. +> To operate in reference mode, Microsoft recommends providing a handler for the event in the global.asax.cs file and setting the property on the token passed in the property. This will ensure that the session token operates in reference mode for every request and is favored over merely setting the property on the Session Authentication Module. ]]> @@ -781,7 +781,7 @@ The class uses both the context ID and the key generation to generate a key for the token in the . - The class serializes this property as the `` child element of the `` element. For more information, see the documentation for the method. + The class serializes this property as the `` child element of the `` element. For more information, see the documentation for the method. ]]> diff --git a/xml/System.IdentityModel.Tokens/SessionSecurityTokenCacheKey.xml b/xml/System.IdentityModel.Tokens/SessionSecurityTokenCacheKey.xml index 1d911bd7a0c16..fbefa7aecdf2d 100644 --- a/xml/System.IdentityModel.Tokens/SessionSecurityTokenCacheKey.xml +++ b/xml/System.IdentityModel.Tokens/SessionSecurityTokenCacheKey.xml @@ -16,7 +16,7 @@ there are two indexes required. One is the context ID, represented by the property, that is unique across all session tokens. The other is the key generation, represented by the property, which is unique within a session token. When a session token is issued it has only a context ID. When the session token is renewed, the key generation is added. After renewal, the renewed session token is uniquely identifiable via the context ID and key generation. + When caching a there are two indexes required. One is the context ID, represented by the property, that is unique across all session tokens. The other is the key generation, represented by the property, which is unique within a session token. When a session token is issued it has only a context ID. When the session token is renewed, the key generation is added. After renewal, the renewed session token is uniquely identifiable via the context ID and key generation. Objects of type are used as the indexes to the session token cache. An index will always have a valid property specified, but the property may be `null`, depending on whether the token has been renewed. There is also an optional which gives the endpoint to which the token is scoped. diff --git a/xml/System.IdentityModel.Tokens/SessionSecurityTokenHandler.xml b/xml/System.IdentityModel.Tokens/SessionSecurityTokenHandler.xml index c79036db2811f..7e614bcd06876 100644 --- a/xml/System.IdentityModel.Tokens/SessionSecurityTokenHandler.xml +++ b/xml/System.IdentityModel.Tokens/SessionSecurityTokenHandler.xml @@ -23,13 +23,13 @@ > [!NOTE] > The \ configuration element can be used to specify a that has the responsibility for securing the application’s sessions. Developers should use caution when changing this configuration setting, as a misconfigured system could result in application compromise. For example, specifying a derived HYPERLINK "http://msdn.microsoft.com/en-us/library/hh193426%28v=vs.110%29.aspx" \t "_blank" and passing an empty Transforms (CookieTransform) collection to the base, would result in the users identity being serialized into a cookie that was not protected. This could allow an attacker to modify the identity and therefore change access privileges. - If the session token is in reference mode, that is, its property is `true`, the session token handler only serializes properties of the session token that are needed to regenerate its key in the . In the default case, the class is used to represent cache keys, and the token handler writes the and properties of the token. If the session token is not in reference mode, that is, the property is `false`, then, in addition to the properties mentioned previously, the handler invokes the method on a byte array serialized from the token and stores the resulting value in the cookie as well. For more details about how the token is serialized, see the method. + If the session token is in reference mode, that is, its property is `true`, the session token handler only serializes properties of the session token that are needed to regenerate its key in the . In the default case, the class is used to represent cache keys, and the token handler writes the and properties of the token. If the session token is not in reference mode, that is, the property is `false`, then, in addition to the properties mentioned previously, the handler invokes the method on a byte array serialized from the token and stores the resulting value in the cookie as well. For more details about how the token is serialized, see the method. The property gets the list of transforms that are applied to the session token in the method. All transforms derive from the class. In the default case the and the are applied. The uses the Data Protection API (DPAPI) to protect the cookie material. DPAPI uses a key that is specific to the computer on which it is running in its protection algorithms. For this reason, the default session token handler is not usable in Web farm scenarios because, in such scenarios, tokens written on one computer may need to be read on another computer. You can use many strategies to circumvent this issue. For example, you can: - Replace the default with the . The enables you to specify signing and encryption keys under the ASP.NET `` element in the configuration file. -- Provide a handler for the event in the global.asax.cs file and replace the default session token handler with an instance of that has a list of transforms that includes the and the . You can create the new instance by invoking one of the constructors that takes a list of transforms. +- Provide a handler for the event in the global.asax.cs file and replace the default session token handler with an instance of that has a list of transforms that includes the and the . You can create the new instance by invoking one of the constructors that takes a list of transforms. - Derive a custom transform from the base class and use the method above to include it in the list of transforms to be applied. @@ -332,7 +332,7 @@ , and . If the property is set `true` on the token handler configuration specified by the property, the bootstrap context is created from the property and is saved in the session token. + Creates and returns a session security token by using the following properties in the token descriptor: , and . If the property is set `true` on the token handler configuration specified by the property, the bootstrap context is created from the property and is saved in the session token. ]]> @@ -492,7 +492,7 @@ ## Remarks The reader must be positioned at either a WS-Secure Conversation Feb2005 or a WS-Secure Conversation 1.3 `` element. - The default implementation invokes the method using a default token resolver. + The default implementation invokes the method using a default token resolver. ]]> @@ -526,7 +526,7 @@ over the token and invokes the method. + The default implementation creates an over the token and invokes the method. ]]> @@ -561,7 +561,7 @@ If the token material is cached, it is read from the token cache, which is an instance of the class. Otherwise, the token material is read from the child element of the `` element that is specified by the and properties and the method is invoked to decode the cookie. - For more information about how session tokens are serialized into a ` method. + For more information about how session tokens are serialized into a ` method. ]]> @@ -768,7 +768,7 @@ method; otherwise, throws a . + Performs a check to make sure that the specified token is scoped for the specified endpoint ID and, if so, invokes the method; otherwise, throws a . > [!IMPORTANT] > Session tokens that have an property that is `null` or empty are considered to be globally scoped. This presents a potential security risk. For this reason you should make sure that the property is set in your session tokens. @@ -826,7 +826,7 @@ and invoking the method. See that overload for more details. + Serializes the specified token by creating and XML writer over a and invoking the method. See that overload for more details. ]]> @@ -858,7 +858,7 @@ ` element, depending on the value of the property. The property is serialized as the `Id` attribute. The property is serialized as the `` child element. If not `null` the property is serialized as an `` element. Finally, if the property is `false`, the entire token is serialized into binary array which is passed to the method to be encoded. The encoded token is then written as a base64 encoded value to the element and namespace specified by the and properties. If the property is `true`, the token is not serialized. + The default implementation serializes the specified token as either a WS-Secure Conversation Feb2005 or WS-Secure Conversation 1.3 `` element, depending on the value of the property. The property is serialized as the `Id` attribute. The property is serialized as the `` child element. If not `null` the property is serialized as an `` element. Finally, if the property is `false`, the entire token is serialized into binary array which is passed to the method to be encoded. The encoded token is then written as a base64 encoded value to the element and namespace specified by the and properties. If the property is `true`, the token is not serialized. ]]> diff --git a/xml/System.IdentityModel/AsyncResult.xml b/xml/System.IdentityModel/AsyncResult.xml index 21cecd44d68ef..8e47fed720c51 100644 --- a/xml/System.IdentityModel/AsyncResult.xml +++ b/xml/System.IdentityModel/AsyncResult.xml @@ -23,7 +23,7 @@ interface. + For more information see the interface. The class derives from . @@ -103,7 +103,7 @@ property. + For more information see the property. ]]> @@ -128,7 +128,7 @@ property. + For more information see the property. ]]> @@ -200,7 +200,7 @@ property. + For more information see the property. ]]> diff --git a/xml/System.IdentityModel/EnvelopedSignatureReader.xml b/xml/System.IdentityModel/EnvelopedSignatureReader.xml index fac08ef04c3c8..2d4de68b50dc4 100644 --- a/xml/System.IdentityModel/EnvelopedSignatureReader.xml +++ b/xml/System.IdentityModel/EnvelopedSignatureReader.xml @@ -36,7 +36,7 @@ constructor is invoked with the following additional parameters: + The constructor is invoked with the following additional parameters: |Parameter Name|Value| |--------------------|-----------| @@ -78,7 +78,7 @@ constructor is invoked with the following additional parameters: + The constructor is invoked with the following additional parameters: |Parameter Name|Value| |--------------------|-----------| diff --git a/xml/System.IdentityModel/SecurityTokenService.xml b/xml/System.IdentityModel/SecurityTokenService.xml index 25e308996af57..59be2995aa39b 100644 --- a/xml/System.IdentityModel/SecurityTokenService.xml +++ b/xml/System.IdentityModel/SecurityTokenService.xml @@ -38,7 +38,7 @@ [!code-csharp[WIFCustomTokenSTS#3](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/customsecuritytokenservice.cs#3)] - The following code shows how to invoke a custom passive STS to process a WS-Federation request by calling the method from the code behind in the `default.aspx.cs` file. + The following code shows how to invoke a custom passive STS to process a WS-Federation request by calling the method from the code behind in the `default.aspx.cs` file. [!code-csharp[WIFCustomTokenSTS#1](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/default.aspx.cs#1)] @@ -669,7 +669,7 @@ ## Remarks This method is called from the method. - The default implementation does the following. Returns `null` if there is no encryption token specified in the request (the property is `null`). Otherwise, if it can get the token as an , it returns credentials based on that token. If it cannot resolve the token as an , a is thrown. + The default implementation does the following. Returns `null` if there is no encryption token specified in the request (the property is `null`). Otherwise, if it can get the token as an , it returns credentials based on that token. If it cannot resolve the token as an , a is thrown. ]]> @@ -704,12 +704,12 @@ ## Remarks The method is called as the last step from the token issuance pipeline, which is implemented by the method. It creates and returns the response (RSTR) by using the original incoming request (RST) and the token descriptor that was built up during previous steps in the token issuance pipeline. - The default implementation creates the RSTR by passing the RST specified in the request parameter to the constructor, invoking the method on the token descriptor passed into to apply its properties to the newly created RSTR, setting the property on the RSTR by using the property on the token descriptor, and finally setting the property on the RSTR according to the following table: + The default implementation creates the RSTR by passing the RST specified in the request parameter to the constructor, invoking the method on the token descriptor passed into to apply its properties to the newly created RSTR, setting the property on the RSTR by using the property on the token descriptor, and finally setting the property on the RSTR according to the following table: -|`RST.ReplyTo` property| property.|`RSTR.ReplyTo` property| +|`RST.ReplyTo` property| property.|`RSTR.ReplyTo` property| |----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------| |Set|Not Set|Not Set| -|Set|Set|| +|Set|Set|| |Not Set|Set|Not Set| |Not Set|Not Set|Not Set| @@ -760,7 +760,7 @@ ## Examples The code example that is used in this topic is taken from the `Custom Token` sample. This sample provides custom classes that enable processing of Simple Web Tokens (SWT) and it includes an implementation of a passive STS that is capable of serving an SWT token. For an example of how to implement an active STS, you can see the `Federation Metadata` sample. For information about these samples and other samples available for WIF and about where to download them, see [WIF Code Sample Index](~/docs/framework/security/wif-code-sample-index.md). - The following code example shows an implementation of the method. This implementation verifies that the RP is recognized by the STS, validates the address in the request and sets the property accordingly, and sets the signing and encrypting credentials to use with the RP based on certificates that are hard-coded in the file. + The following code example shows an implementation of the method. This implementation verifies that the RP is recognized by the STS, validates the address in the request and sets the property accordingly, and sets the signing and encrypting credentials to use with the RP based on certificates that are hard-coded in the file. [!code-csharp[WIFCustomTokenSTS#4](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/customsecuritytokenservice.cs#4)] [!code-csharp[WIFCustomTokenSTS#5](~/samples/snippets/csharp/VS_Snippets_Misc/wifcustomtokensts/cs/passivests/customsecuritytokenservice.cs#5)] @@ -831,9 +831,9 @@ |Created (in)|Expires (in)|Created (in)|Expires (out)| |--------------------|--------------------|--------------------|---------------------| -|`null`|`null`|| + | -|C|`null`|C|C + | -|`null`|E||E| +|`null`|`null`|| + | +|C|`null`|C|C + | +|`null`|E||E| |C|E|C|E| This method is called from the default token issuance pipeline implemented in the method. @@ -873,7 +873,7 @@ 2. The method to get a object that contains information about the relying party (RP) associated with the request. You must override this method. If returns `null`, a is thrown. -3. The method to return a security token descriptor based on the RST and the object returned in the previous step. The security token descriptor () contains information about the request in a form that can be used by a token handler. The property is set to the descriptor returned by the call. If `null` is returned or if the property of the descriptor is `null`, an is thrown. The exception is also thrown if the property is `true` but the property on the returned descriptor is `null`. +3. The method to return a security token descriptor based on the RST and the object returned in the previous step. The security token descriptor () contains information about the request in a form that can be used by a token handler. The property is set to the descriptor returned by the call. If `null` is returned or if the property of the descriptor is `null`, an is thrown. The exception is also thrown if the property is `true` but the property on the returned descriptor is `null`. 4. The method to get the appropriate token handler based on the kind of token requested. If `null` is returned, a is thrown. @@ -1070,7 +1070,7 @@ ## Remarks The method is called from the token issuance pipeline (the method) to validate the incoming RST. The RST is validated against the requirements (policy) of the STS and an appropriate exception is thrown if it is not valid. - The default implementation of the class supports only the RST-RSTR pattern and only the Issue binding of the WS-Trust specification (the property of the request must be set to ). The default implementation of this method enforces these requirements (and others noted in the exceptions section). You can override this method if you must enforce different validation requirements for your custom STS. + The default implementation of the class supports only the RST-RSTR pattern and only the Issue binding of the WS-Trust specification (the property of the request must be set to ). The default implementation of this method enforces these requirements (and others noted in the exceptions section). You can override this method if you must enforce different validation requirements for your custom STS. ]]> diff --git a/xml/System.Management.Instrumentation/ManagementBindAttribute.xml b/xml/System.Management.Instrumentation/ManagementBindAttribute.xml index eda2deb4b56b8..aaecbbb774f00 100644 --- a/xml/System.Management.Instrumentation/ManagementBindAttribute.xml +++ b/xml/System.Management.Instrumentation/ManagementBindAttribute.xml @@ -90,7 +90,7 @@ public ClassConstructor(int Id) , then the output should be treated as a value of type . + If the returned type is , then the output should be treated as a value of type . ]]> diff --git a/xml/System.Management.Instrumentation/ManagementConfigurationAttribute.xml b/xml/System.Management.Instrumentation/ManagementConfigurationAttribute.xml index 19108a7544863..7ead4a530503c 100644 --- a/xml/System.Management.Instrumentation/ManagementConfigurationAttribute.xml +++ b/xml/System.Management.Instrumentation/ManagementConfigurationAttribute.xml @@ -107,7 +107,7 @@ public double ReadableWritableProperty , then the output should be treated as a value of type . + If the returned type is , then the output should be treated as a value of type . ]]> diff --git a/xml/System.Management.Instrumentation/ManagementEnumeratorAttribute.xml b/xml/System.Management.Instrumentation/ManagementEnumeratorAttribute.xml index b73bc612b8084..a1ca219b032ac 100644 --- a/xml/System.Management.Instrumentation/ManagementEnumeratorAttribute.xml +++ b/xml/System.Management.Instrumentation/ManagementEnumeratorAttribute.xml @@ -80,7 +80,7 @@ public static IEnumerable Enumerate() , then the output should be treated as a value of type . + If the returned type is , then the output should be treated as a value of type . ]]> diff --git a/xml/System.Management.Instrumentation/ManagementProbeAttribute.xml b/xml/System.Management.Instrumentation/ManagementProbeAttribute.xml index 43fd5d29e1d60..12baaa4eaaf93 100644 --- a/xml/System.Management.Instrumentation/ManagementProbeAttribute.xml +++ b/xml/System.Management.Instrumentation/ManagementProbeAttribute.xml @@ -86,7 +86,7 @@ public int ReadOnlyProperty , then the output should be treated as a value of type . + If the returned type is , then the output should be treated as a value of type . ]]> diff --git a/xml/System.Management.Instrumentation/ManagementRemoveAttribute.xml b/xml/System.Management.Instrumentation/ManagementRemoveAttribute.xml index 6c8f750ef99b1..9af3c89c6b7c9 100644 --- a/xml/System.Management.Instrumentation/ManagementRemoveAttribute.xml +++ b/xml/System.Management.Instrumentation/ManagementRemoveAttribute.xml @@ -65,7 +65,7 @@ , then the output should be treated as a value of type . + If the returned type is , then the output should be treated as a value of type . ]]> diff --git a/xml/System.Management.Instrumentation/ManagementTaskAttribute.xml b/xml/System.Management.Instrumentation/ManagementTaskAttribute.xml index 3a71bce289c04..7b84cd5749513 100644 --- a/xml/System.Management.Instrumentation/ManagementTaskAttribute.xml +++ b/xml/System.Management.Instrumentation/ManagementTaskAttribute.xml @@ -83,7 +83,7 @@ public void ResetCounters() , then the output should be treated as a value of type . + If the returned type is , then the output should be treated as a value of type . ]]> diff --git a/xml/System.Management/ConnectionOptions.xml b/xml/System.Management/ConnectionOptions.xml index c0460da9dc4a5..3ebf5898ebcf5 100644 --- a/xml/System.Management/ConnectionOptions.xml +++ b/xml/System.Management/ConnectionOptions.xml @@ -162,10 +162,10 @@ if the client requires all communication to be encrypted. + On Windows 2000 and below, the WMI service will request Connect level authentication, while on Windows XP and higher it will request Packet level authentication. If the client requires a specific authentication setting, this property can be used to control the authentication level on this particular connection. For example, the property can be set to if the client requires all communication to be encrypted. ## Property Value - The COM authentication level to be used for operations in this connection. The default value is , which indicates that the client will use the authentication level requested by the server, according to the standard DCOM negotiation process. + The COM authentication level to be used for operations in this connection. The default value is , which indicates that the client will use the authentication level requested by the server, according to the standard DCOM negotiation process. ## .NET Framework Security Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](~/docs/framework/misc/using-libraries-from-partially-trusted-code.md). @@ -310,10 +310,10 @@ NTLMDOMAIN: setting is advantageous when the provider is a trusted application or service. It eliminates the need for the provider to perform client identity and access checks for the requested operations. However, if for some reason the provider cannot be trusted, allowing it to impersonate the client may constitute a security threat. In such cases, we recommend that this property be set by the client to a lower value, such as . Note that this may cause failure of the provider to perform the requested operations, for lack of sufficient permissions or inability to perform access checks. + The setting is advantageous when the provider is a trusted application or service. It eliminates the need for the provider to perform client identity and access checks for the requested operations. However, if for some reason the provider cannot be trusted, allowing it to impersonate the client may constitute a security threat. In such cases, we recommend that this property be set by the client to a lower value, such as . Note that this may cause failure of the provider to perform the requested operations, for lack of sufficient permissions or inability to perform access checks. ## Property Value - The COM impersonation level to be used for operations in this connection. The default value is , which indicates that the WMI provider can impersonate the client when performing the requested operations in this connection. + The COM impersonation level to be used for operations in this connection. The default value is , which indicates that the WMI provider can impersonate the client when performing the requested operations in this connection. ## .NET Framework Security Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](~/docs/framework/misc/using-libraries-from-partially-trusted-code.md). diff --git a/xml/System.Media/SoundPlayer.xml b/xml/System.Media/SoundPlayer.xml index ba58080b1e8ac..24b64503be533 100644 --- a/xml/System.Media/SoundPlayer.xml +++ b/xml/System.Media/SoundPlayer.xml @@ -557,7 +557,7 @@ when the property is set to a . + This property is set to when the property is set to a . diff --git a/xml/System.Messaging/AcknowledgeTypes.xml b/xml/System.Messaging/AcknowledgeTypes.xml index c76ee97e9129e..41b8ed446b06e 100644 --- a/xml/System.Messaging/AcknowledgeTypes.xml +++ b/xml/System.Messaging/AcknowledgeTypes.xml @@ -91,7 +91,7 @@ method does not remove a message from the queue, so this acknowledgment type could be returned even if you did peek the message. Only the method (or the related asynchronous method) removes a message from the queue. + Using the method does not remove a message from the queue, so this acknowledgment type could be returned even if you did peek the message. Only the method (or the related asynchronous method) removes a message from the queue. ]]> diff --git a/xml/System.Messaging/Acknowledgment.xml b/xml/System.Messaging/Acknowledgment.xml index de536f7b9a7f9..9d552403d13a8 100644 --- a/xml/System.Messaging/Acknowledgment.xml +++ b/xml/System.Messaging/Acknowledgment.xml @@ -17,11 +17,11 @@ ## Remarks The class defines the types of acknowledgment messages that Message Queuing posts in the administration queue and the conditions that cause an acknowledgment message to be sent. Acknowledgment types can be divided broadly into four groups: positive arrival acknowledgments, positive read acknowledgments, negative arrival acknowledgments, and negative read acknowledgments. - The administration queue associated with message is specified in the property. + The administration queue associated with message is specified in the property. - Message Queuing sets the property to one of the enumeration values when it creates an acknowledgment message. The property value is typically meaningful only when the instance refers to a system-sent acknowledgment message. Reading the property for a message other than an acknowledgment message throws an exception. + Message Queuing sets the property to one of the enumeration values when it creates an acknowledgment message. The property value is typically meaningful only when the instance refers to a system-sent acknowledgment message. Reading the property for a message other than an acknowledgment message throws an exception. - Message Queuing does not send an acknowledgment message unless the sending application requests that it do so. Your application makes this request by setting the appropriate value for the property. Message Queuing sends all acknowledgment messages to the administration queue specified in the property of the original . + Message Queuing does not send an acknowledgment message unless the sending application requests that it do so. Your application makes this request by setting the appropriate value for the property. Message Queuing sends all acknowledgment messages to the administration queue specified in the property of the original . diff --git a/xml/System.Messaging/DefaultPropertiesToSend.xml b/xml/System.Messaging/DefaultPropertiesToSend.xml index 89864fbf39e4f..d75959f1ae471 100644 --- a/xml/System.Messaging/DefaultPropertiesToSend.xml +++ b/xml/System.Messaging/DefaultPropertiesToSend.xml @@ -21,7 +21,7 @@ . is used to specify default property values of the message being sent when objects other than instances are sent to a queue, for example, the string argument passed into the method in the code fragment, `myMessageQueue.Send("hello")`. The class has corresponding, identically named properties to those in that provide the values when sending a instance specifically. Even if you have specified for a queue, sending a object to that queue will cause the values for the identically named properties to override the queue's values. + You can set default values on selected properties for messages sent to a . is used to specify default property values of the message being sent when objects other than instances are sent to a queue, for example, the string argument passed into the method in the code fragment, `myMessageQueue.Send("hello")`. The class has corresponding, identically named properties to those in that provide the values when sending a instance specifically. Even if you have specified for a queue, sending a object to that queue will cause the values for the identically named properties to override the queue's values. Properties that you do not set explicitly default to the values specified by the constructor, . @@ -56,9 +56,9 @@ to define default property values to associate with objects sent to a queue that are not of type . When working with objects, a instance is created for you and associated with the member of the . + You can create a new instance of to define default property values to associate with objects sent to a queue that are not of type . When working with objects, a instance is created for you and associated with the member of the . - There are two ways to define a queue's default properties to send, as shown in the following C# code. You can set values for this instance of and associate it with the queue's property: + There are two ways to define a queue's default properties to send, as shown in the following C# code. You can set values for this instance of and associate it with the queue's property: ``` DefaultPropertiesToSend myDefaultProperties = new DefaultPropertiesToSend(); @@ -79,7 +79,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; myMessageQueue.Send("hello"); ``` - If you choose the second of these options, you do not need to call the constructor explicitly. You might want to create instances of , for example, if the properties' default values depend on some criterion of the message being sent. You can create multiple instances and assign one to the queue's property before sending the message to the queue. + If you choose the second of these options, you do not need to call the constructor explicitly. You might want to create instances of , for example, if the properties' default values depend on some criterion of the message being sent. You can create multiple instances and assign one to the queue's property before sending the message to the queue. The following table shows initial property values for an instance of . @@ -773,7 +773,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; You do not create a journal or dead-letter queue. These are both system queues that are generated by Message Queuing. - Journaling can be specified by both the message and the queue. When is `true`, the message is journaled when it is sent. When is `true`, the message is journaled when it is received. + Journaling can be specified by both the message and the queue. When is `true`, the message is journaled when it is sent. When is `true`, the message is journaled when it is received. ]]> diff --git a/xml/System.Messaging/Message.xml b/xml/System.Messaging/Message.xml index 20002ec629779..20bb885b37aeb 100644 --- a/xml/System.Messaging/Message.xml +++ b/xml/System.Messaging/Message.xml @@ -23,7 +23,7 @@ ## Remarks Use the class to peek or receive messages from a queue, or to have fine control over message properties when sending a message to a queue. - uses the class when it peeks or receives messages from queues, because both the and methods create a new instance of the class and set the instance's properties. The class's read-only properties apply to retrieving messages from a queue, while the read/write properties apply to sending and retrieving messages. When peeks or receives a message from a queue, its property determines which of the message's properties are retrieved. + uses the class when it peeks or receives messages from queues, because both the and methods create a new instance of the class and set the instance's properties. The class's read-only properties apply to retrieving messages from a queue, while the read/write properties apply to sending and retrieving messages. When peeks or receives a message from a queue, its property determines which of the message's properties are retrieved. The class's method allows you to specify any object type for a message being sent to that queue. You can use the instance's property to specify settings for generic messages sent to the queue. The types of settings include formatter, label, encryption, and authentication. You can also specify values for the appropriate members when you coordinate your messaging application to respond to acknowledgment and report messages. Using a instance to send a message to the queue gives you the flexibility to access and modify many of these properties—either for a single message or on a message-by-message basis. properties take precedence over . @@ -31,7 +31,7 @@ The contents of the property are serialized when the message is sent, using the property you specify. The serialized contents are found in the property. You can also set the property directly, for example, to send a file as the data content of a message. You can change the or properties at any time before sending the message, and the data will be serialized appropriately when you call . - The properties defined by the property apply only to messages that are not of type . If you specify the property for a , the identically named properties in a instance sent to that queue cause these default properties to be ignored. + The properties defined by the property apply only to messages that are not of type . If you specify the property for a , the identically named properties in a instance sent to that queue cause these default properties to be ignored. For a list of initial property values for an instance of , see the constructor. @@ -715,7 +715,7 @@ ## Remarks The message's property usually contains the data associated with the message. Although you can also send application-specific data in the and properties, you should include message data in the of the message whenever possible. Only the property contents are serialized or encrypted. - The property can contain any object whose size does not exceed 4 MB. If you use to send any object that is not of type to the , that object will be located in the property of the instance returned by or . + The property can contain any object whose size does not exceed 4 MB. If you use to send any object that is not of type to the , that object will be located in the property of the instance returned by or . The string argument in `MessageQueue.Send("hello.")` is an example of such a generic object. diff --git a/xml/System.Messaging/MessageEnumerator.xml b/xml/System.Messaging/MessageEnumerator.xml index 47f26d3eee5ab..e13bb986ea055 100644 --- a/xml/System.Messaging/MessageEnumerator.xml +++ b/xml/System.Messaging/MessageEnumerator.xml @@ -36,12 +36,12 @@ Instances of for a given queue work independently. You can create two instances that apply to the same queue. The changes that one makes to the messages in the queue will be reflected immediately in a second enumerator if the second enumerator is positioned before the first. However, if two enumerators have the same position and one of them removes the message at that position, an exception is thrown if the other enumerator attempts to get the value of the property on the now-deleted message. > [!NOTE] -> If you create an instance of with set to `true`, no other application can modify the messages in your enumerator while you have the connection to the queue. +> If you create an instance of with set to `true`, no other application can modify the messages in your enumerator while you have the connection to the queue. ## Examples - The following example gets a dynamic list of messages in a queue and counts all messages with the property set to . + The following example gets a dynamic list of messages in a queue and counts all messages with the property set to . [!code-cpp[MessageQueue.GetMessageEnumerator#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/CPP/mqgetmessageenumerator.cpp#1)] [!code-csharp[MessageQueue.GetMessageEnumerator#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/CS/mqgetmessageenumerator.cs#1)] diff --git a/xml/System.Messaging/MessagePropertyFilter.xml b/xml/System.Messaging/MessagePropertyFilter.xml index 13ac7297efbe2..5a6fec19fe871 100644 --- a/xml/System.Messaging/MessagePropertyFilter.xml +++ b/xml/System.Messaging/MessagePropertyFilter.xml @@ -24,7 +24,7 @@ ## Remarks Setting the on a instance controls the set of properties that are retrieved when peeking or receiving a message. The filter is set on the instance of that retrieves the message information. When you set a Boolean-valued member to `false`, you prevent the information of the associated property from being retrieved by the . - There are several filter properties that are not Boolean values. They are integer values that get or set the default sizes of the , , or . + There are several filter properties that are not Boolean values. They are integer values that get or set the default sizes of the , , or . Retrieving a limited set of properties helps improve performance because smaller amounts of data are transferred from the queue. @@ -109,7 +109,7 @@ property of the class specifies the type of acknowledgment messages requested by the sending application. The type of acknowledgment defines when acknowledgments are returned. Set the property before sending the message to request a specific type of acknowledgment. + The property of the class specifies the type of acknowledgment messages requested by the sending application. The type of acknowledgment defines when acknowledgments are returned. Set the property before sending the message to request a specific type of acknowledgment. @@ -151,11 +151,11 @@ property of the class specifies the type of acknowledgment messages the system posts in the administration queue, which determines when acknowledgments are generated. + The property of the class specifies the type of acknowledgment messages the system posts in the administration queue, which determines when acknowledgments are generated. Acknowledgments are returned from the destination queue and posted as messages to the specified by the original message. The type of acknowledgment generated depends on what was requested. - Read the property when receiving a message from an administration queue to verify the status of the message originally sent to the message queue. + Read the property when receiving a message from an administration queue to verify the status of the message originally sent to the message queue. @@ -324,7 +324,7 @@ property of the class specifies whether the should be or has been attached to the message. The is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. + The property of the class specifies whether the should be or has been attached to the message. The is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. @@ -410,7 +410,7 @@ property of the class specifies the name of the cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. + The property of the class specifies the name of the cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. @@ -596,9 +596,9 @@ ## Remarks The property of the class is required when an application sets a message property that is typically set by Message Queuing. It is used in the following two instances: -- When a message is passed by a connector application, the is required for the sending and receiving applications to interpret the security and acknowledgment properties of the message. +- When a message is passed by a connector application, the is required for the sending and receiving applications to interpret the security and acknowledgment properties of the message. -- When sending application-encrypted messages, the property informs Message Queuing to use the symmetric key. +- When sending application-encrypted messages, the property informs Message Queuing to use the symmetric key. @@ -1354,7 +1354,7 @@ ## Remarks The property of the class indicates whether delivery of a message is guaranteed, even if a computer crashes while the message is en route to the destination queue. - If delivery of a message is guaranteed, the message is stored locally at every step until the message is successfully forwarded to the next computer. Setting to `true` on the message could affect the throughput. + If delivery of a message is guaranteed, the message is stored locally at every step until the message is successfully forwarded to the next computer. Setting to `true` on the message could affect the throughput. @@ -1526,7 +1526,7 @@ ## Remarks The property of the class specifies the version of Message Queuing used to send the message. The property is important to be aware of when using features like transaction processing, which is only supported by Message Queuing version 2.0 and later, or digital signatures, which are used to authenticate messages sent by version 1.0. - is set by the sending queue manager when the message is sent. + is set by the sending queue manager when the message is sent. @@ -1668,7 +1668,7 @@ ||255| ||255| - The property represents a on which has been called. + The property represents a on which has been called. diff --git a/xml/System.Messaging/MessageQueue.xml b/xml/System.Messaging/MessageQueue.xml index e57b9c6d5156c..168562f7af883 100644 --- a/xml/System.Messaging/MessageQueue.xml +++ b/xml/System.Messaging/MessageQueue.xml @@ -2281,9 +2281,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. and provide faster throughput than the . The allows interoperability with Visual Basic 6.0 Message Queuing applications. - When your application sends messages to the queue, the applies only to those messages that use the default message properties, . If you send a to the queue, Message Queuing uses the formatter defined in the property to serialize the body instead. + When your application sends messages to the queue, the applies only to those messages that use the default message properties, . If you send a to the queue, Message Queuing uses the formatter defined in the property to serialize the body instead. - The class will always use a to receive or peek a message from the queue. The message is deserialized using the property. + The class will always use a to receive or peek a message from the queue. The message is deserialized using the property. The following table shows whether this property is available in various Workgroup modes. @@ -2506,7 +2506,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Examples - The following code example gets a dynamic list of messages in a queue and counts all messages with the property set to . + The following code example gets a dynamic list of messages in a queue and counts all messages with the property set to . [!code-cpp[MessageQueue.GetMessageEnumerator#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/CPP/mqgetmessageenumerator.cpp#1)] [!code-csharp[MessageQueue.GetMessageEnumerator#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/CS/mqgetmessageenumerator.cs#1)] @@ -5958,7 +5958,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -6019,7 +6019,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. @@ -6090,7 +6090,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -6151,7 +6151,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. The property for this instance must be specified before you send the message. If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -6214,7 +6214,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. @@ -6292,7 +6292,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over , and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over , and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. diff --git a/xml/System.Messaging/MessageQueueAccessControlEntry.xml b/xml/System.Messaging/MessageQueueAccessControlEntry.xml index a9eb17256dafb..7a930c1e1cdfe 100644 --- a/xml/System.Messaging/MessageQueueAccessControlEntry.xml +++ b/xml/System.Messaging/MessageQueueAccessControlEntry.xml @@ -26,7 +26,7 @@ To set message queue permissions for a trustee, create a new instance of the class and pass it into an overload of the constructor. Specify the message queue access rights either by passing an instance of into the constructor or by setting the property on an existing instance. - You can then pass the instance directly to the method, or alternately add the entry to an instance of before calling . + You can then pass the instance directly to the method, or alternately add the entry to an instance of before calling . ]]> @@ -113,7 +113,7 @@ property enables you to specify Message Queuing object-specific rights such as receiving, peeking, or writing messages, or setting queue properties. The value of this property is set by the constructor, but you can change it at any time before using this instance of in a call to . + The property enables you to specify Message Queuing object-specific rights such as receiving, peeking, or writing messages, or setting queue properties. The value of this property is set by the constructor, but you can change it at any time before using this instance of in a call to . ]]> diff --git a/xml/System.Messaging/MessageQueueErrorCode.xml b/xml/System.Messaging/MessageQueueErrorCode.xml index 9128b317af749..db4a3b06fa18a 100644 --- a/xml/System.Messaging/MessageQueueErrorCode.xml +++ b/xml/System.Messaging/MessageQueueErrorCode.xml @@ -51,7 +51,7 @@ and topics. + Message Queuing returns this error if access to the specified queue or computer is denied. If this error is returned, verify that you have access rights for the operation, such as creating, deleting, or setting properties for a queue. For information about changing access rights for a queue, see the and topics. ]]> @@ -337,7 +337,7 @@ and topics. + For information about cryptographic providers, see the and topics. ]]> @@ -412,7 +412,7 @@ and topics. + Message Queuing returns this error when the application requests encryption and the computer (source or destination) does not support encryption operations. When this error is returned, the encryption operation fails. For more information about using encryption, see the and topics. ]]> @@ -1329,7 +1329,7 @@ or expires before a new message arrives in the queue. This can only happen if there was no message already in the queue; both methods would return immediately if a message exists. + Message Queuing returns this error if the time-out specified in a call to or expires before a new message arrives in the queue. This can only happen if there was no message already in the queue; both methods would return immediately if a message exists. ]]> @@ -1413,7 +1413,7 @@ class, such as the instance returned through a call to or . + Message Queuing returns this error when some other cursor, application, or the system administrator has already removed the message from the queue. This error is most likely to occur when using the class, such as the instance returned through a call to or . ]]> diff --git a/xml/System.Messaging/MessageQueueInstaller.xml b/xml/System.Messaging/MessageQueueInstaller.xml index 58e381a639b3b..4233a6c41c268 100644 --- a/xml/System.Messaging/MessageQueueInstaller.xml +++ b/xml/System.Messaging/MessageQueueInstaller.xml @@ -28,7 +28,7 @@ Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process and calls if the installation did not throw an exception. It backs out failures, if necessary, by calling for the object that generated the exception. - An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information is continuously updated as each instance is installed by the utility. It is not usually necessary for your code to explicitly modify the state information. + An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information is continuously updated as each instance is installed by the utility. It is not usually necessary for your code to explicitly modify the state information. ]]> @@ -188,7 +188,7 @@ After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. - An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility commits each instance. Usually, it is not necessary for your code to explicitly modify this state information. When the queue has been cleared, posts a log entry to the `savedState` that is associated with the installation. + An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility commits each instance. Usually, it is not necessary for your code to explicitly modify this state information. When the queue has been cleared, posts a log entry to the `savedState` that is associated with the installation. ]]> @@ -286,7 +286,7 @@ After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. - An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the utility installs each instance. Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the utility installs each instance. Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -603,7 +603,7 @@ Typically, you do not call the methods of the from within your code; they are generally called only by the InstallUtil.exe installation utility. The utility automatically calls the method after an installation failure to undo any changes that the installation process has already made. - An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility rolls back each instance. Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility rolls back each instance. Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -666,7 +666,7 @@ Typically, you do not call the methods of the from within your code; they are generally called only by the InstallUtil.exe installation utility (in uninstall mode). The utility automatically calls the method to restore the parts of the system that were affected by the installation to their pre-installation states. This includes deleting registry information that is associated with the MessageQueue being uninstalled. - An application's uninstall routine uses the project installer's to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility uninstalls each instance. Usually, it is not necessary for your code to explicitly modify this state information. + An application's uninstall routine uses the project installer's to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility uninstalls each instance. Usually, it is not necessary for your code to explicitly modify this state information. ]]> diff --git a/xml/System.Messaging/MessageQueueTransaction.xml b/xml/System.Messaging/MessageQueueTransaction.xml index 4483ec16bd732..f8a81297a5671 100644 --- a/xml/System.Messaging/MessageQueueTransaction.xml +++ b/xml/System.Messaging/MessageQueueTransaction.xml @@ -20,7 +20,7 @@ class to create a transaction and pass it to an overload of the method or the method that takes a `transaction` parameter. Messages sent as part of a transaction must be sent to transactional queues. Messages received from transactional queues must be received using a specified transaction. + To send or receive a message as part of a transaction, you can use the class to create a transaction and pass it to an overload of the method or the method that takes a `transaction` parameter. Messages sent as part of a transaction must be sent to transactional queues. Messages received from transactional queues must be received using a specified transaction. In addition to the method, you can receive messages with a specified identifier or specified correlation identifier. See the and methods for more information about selectively receiving messages from transactional queues. @@ -234,7 +234,7 @@ . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). diff --git a/xml/System.Messaging/MessageType.xml b/xml/System.Messaging/MessageType.xml index 845b3fe5aeff2..e3c0a786a28a1 100644 --- a/xml/System.Messaging/MessageType.xml +++ b/xml/System.Messaging/MessageType.xml @@ -15,11 +15,11 @@ class or any overload of the method. + Typical (`Normal` type) messages are those that you send to a queue using either the class or any overload of the method. Message Queuing generates acknowledgment messages whenever the sending application requests one. If you send a message using the class, you can use its property to specify the types of acknowledgments to receive. For example, Message Queuing can generate positive or negative messages to indicate that the original message arrived or was read. Message Queuing returns the appropriate acknowledgment message to the administration queue specified by the sending application. When you receive or peek an acknowledgment message using a , its property indicates the reason Message Queuing sent the acknowledgment. - Message Queuing generates report messages whenever a report queue is defined at the source queue manager. When tracing is enabled (by setting the property on the original message), Message Queuing sends a report message to the Message Queuing report queue each time the original message enters or leaves a Message Queuing server. + Message Queuing generates report messages whenever a report queue is defined at the source queue manager. When tracing is enabled (by setting the property on the original message), Message Queuing sends a report message to the Message Queuing report queue each time the original message enters or leaves a Message Queuing server. ]]> diff --git a/xml/System.Messaging/PeekCompletedEventArgs.xml b/xml/System.Messaging/PeekCompletedEventArgs.xml index 8c0a90a9bf9cc..539aebd4f9a77 100644 --- a/xml/System.Messaging/PeekCompletedEventArgs.xml +++ b/xml/System.Messaging/PeekCompletedEventArgs.xml @@ -20,7 +20,7 @@ There are two ways to provide notification of event completion: event notification and callbacks. is used only with event notification. For information comparing callbacks and event notification, see "Events vs. Callbacks" on MSDN. - provides access to the message that initiated the end of the asynchronous peek operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . + provides access to the message that initiated the end of the asynchronous peek operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . @@ -83,7 +83,7 @@ ## Remarks The property provides a means for retrieving the message that initiated the end of the asynchronous peek operation. - is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. + is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. ]]> diff --git a/xml/System.Messaging/PeekCompletedEventHandler.xml b/xml/System.Messaging/PeekCompletedEventHandler.xml index 5e48c9a98cd53..e35ef03f09347 100644 --- a/xml/System.Messaging/PeekCompletedEventHandler.xml +++ b/xml/System.Messaging/PeekCompletedEventHandler.xml @@ -29,7 +29,7 @@ ## Examples - The following example illustrates how to create an event delegate () for the event handler (`MyPeekCompleted`) and associate it with the event. The event handler peeks a message and writes its label to the screen. + The following example illustrates how to create an event delegate () for the event handler (`MyPeekCompleted`) and associate it with the event. The event handler peeks a message and writes its label to the screen. [!code-cpp[MessageQueue.BeginPeek_noparms#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp#1)] [!code-csharp[MessageQueue.BeginPeek_noparms#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CS/mqbeginpeek_noparms.cs#1)] diff --git a/xml/System.Messaging/ReceiveCompletedEventArgs.xml b/xml/System.Messaging/ReceiveCompletedEventArgs.xml index 801a5e5a5316f..f9a63b0324f6d 100644 --- a/xml/System.Messaging/ReceiveCompletedEventArgs.xml +++ b/xml/System.Messaging/ReceiveCompletedEventArgs.xml @@ -20,7 +20,7 @@ There are two ways to provide notification of event completion: event notification and callbacks. is used only with event notification. For information comparing callbacks and event notification, see "Events vs. Callbacks" on MSDN. - provides access to the message that initiated the end of the asynchronous receive operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . + provides access to the message that initiated the end of the asynchronous receive operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . @@ -83,7 +83,7 @@ ## Remarks The property provides a means for retrieving the message that initiated the end of the asynchronous receive operation. - is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. + is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. ]]> diff --git a/xml/System.Messaging/ReceiveCompletedEventHandler.xml b/xml/System.Messaging/ReceiveCompletedEventHandler.xml index 9f6c7312e44d4..a8c5c95108a47 100644 --- a/xml/System.Messaging/ReceiveCompletedEventHandler.xml +++ b/xml/System.Messaging/ReceiveCompletedEventHandler.xml @@ -29,7 +29,7 @@ ## Examples - The following code example illustrates how to create an event delegate () for the event handler (`MyReceiveCompleted`) and associate it with the event. The event handler receives a message from a queue, and writes its label to the screen. + The following code example illustrates how to create an event delegate () for the event handler (`MyReceiveCompleted`) and associate it with the event. The event handler receives a message from a queue, and writes its label to the screen. [!code-cpp[MessageQueue.ReceiveCompleted#1](~/samples/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ReceiveCompleted/CPP/mqreceivecompletedeventhandler.cpp#1)] [!code-csharp[MessageQueue.ReceiveCompleted#1](~/samples/snippets/csharp/VS_Snippets_Remoting/MessageQueue.ReceiveCompleted/CS/mqreceivecompletedeventhandler.cs#1)] diff --git a/xml/System.Net.Cache/HttpRequestCacheLevel.xml b/xml/System.Net.Cache/HttpRequestCacheLevel.xml index 548087ab4d863..b6fda5413d7ba 100644 --- a/xml/System.Net.Cache/HttpRequestCacheLevel.xml +++ b/xml/System.Net.Cache/HttpRequestCacheLevel.xml @@ -28,7 +28,7 @@ This BypassCache value is the default cache behavior specified in the machine configuration file that ships with the .NET Framework. No entries are taken from caches, added to caches, or removed from caches between the client and server. - The property is used to get or set the default cache policy for instances. The property is used to get or set the default cache policy for a instances. The property is used to get or set the cache policy for a specific request. + The property is used to get or set the default cache policy for instances. The property is used to get or set the default cache policy for a instances. The property is used to get or set the cache policy for a specific request. A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the default cache policy level for this request. diff --git a/xml/System.Net.Cache/RequestCacheLevel.xml b/xml/System.Net.Cache/RequestCacheLevel.xml index f23fe61939409..a3360c19a6760 100644 --- a/xml/System.Net.Cache/RequestCacheLevel.xml +++ b/xml/System.Net.Cache/RequestCacheLevel.xml @@ -24,11 +24,11 @@ objects. The current setting for a object is available in the property. + Members of this enumeration are used to initialize objects. The current setting for a object is available in the property. This value is the default cache behavior specified in the machine configuration file that ships with the .NET Framework. No entries are taken from caches, added to caches, or removed from caches between the client and server. - The property is used to get or set the default cache policy for instances. The property is used to get or set the default cache policy for a instances. The property is used to get or set the cache policy for a specific request. + The property is used to get or set the default cache policy for instances. The property is used to get or set the default cache policy for a instances. The property is used to get or set the cache policy for a specific request. A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the default cache policy level for this request. diff --git a/xml/System.Net.Cache/RequestCachePolicy.xml b/xml/System.Net.Cache/RequestCachePolicy.xml index 45535638e6999..ac6dba3691c66 100644 --- a/xml/System.Net.Cache/RequestCachePolicy.xml +++ b/xml/System.Net.Cache/RequestCachePolicy.xml @@ -155,7 +155,7 @@ as their cache policy level. Using the level, the effective cache policy is determined by the current cache policy and the age of the content in the cache. The property, if not `null`, determines the cache policy in effect for a request. + Applications typically use as their cache policy level. Using the level, the effective cache policy is determined by the current cache policy and the age of the content in the cache. The property, if not `null`, determines the cache policy in effect for a request. The default policy for the application domain can be set using the or the application or machine configuration file. For more information, see [<requestCaching> Element (Network Settings)](~/docs/framework/configure-apps/file-schema/network/requestcaching-element-network-settings.md). diff --git a/xml/System.Net.Configuration/ConnectionManagementElement.xml b/xml/System.Net.Configuration/ConnectionManagementElement.xml index 97d4b4bb7e961..0a84c88510131 100644 --- a/xml/System.Net.Configuration/ConnectionManagementElement.xml +++ b/xml/System.Net.Configuration/ConnectionManagementElement.xml @@ -126,7 +126,7 @@ ## Remarks This property specifies how many simultaneous connections are allowed between the local computer and the remote computer. The remote computer is specified using the property. - The property is per . If an application is not changing from the default, then the property applies to the entire application domain. If only a single application domain is running in your application, then the property setting is application-wide. + The property is per . If an application is not changing from the default, then the property applies to the entire application domain. If only a single application domain is running in your application, then the property setting is application-wide. ]]> diff --git a/xml/System.Net.Configuration/HttpListenerElement.xml b/xml/System.Net.Configuration/HttpListenerElement.xml index eb06db8754857..f28141f463458 100644 --- a/xml/System.Net.Configuration/HttpListenerElement.xml +++ b/xml/System.Net.Configuration/HttpListenerElement.xml @@ -20,7 +20,7 @@ The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. - When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. + When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. The `http.sys` service exposes two request URI strings: @@ -28,7 +28,7 @@ - Converted URI - The raw URI is the provided in the request line of a HTTP request: + The raw URI is the provided in the request line of a HTTP request: `GET /path/` @@ -42,7 +42,7 @@ `http://www.contoso.com/path/` - The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: + The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: - Un-escapes all percent encoded values. @@ -169,7 +169,7 @@ ## Remarks The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. - When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. + When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. The `http.sys` service exposes two request URI strings: @@ -177,7 +177,7 @@ - Converted URI - The raw URI is the provided in the request line of a HTTP request: + The raw URI is the provided in the request line of a HTTP request: `GET /path/` @@ -191,7 +191,7 @@ `http://www.contoso.com/path/` - The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: + The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: - Un-escapes all percent encoded values. diff --git a/xml/System.Net.Configuration/ServicePointManagerElement.xml b/xml/System.Net.Configuration/ServicePointManagerElement.xml index 5d57792d4019b..5c67d9314133d 100644 --- a/xml/System.Net.Configuration/ServicePointManagerElement.xml +++ b/xml/System.Net.Configuration/ServicePointManagerElement.xml @@ -174,7 +174,7 @@ property can require, allow, or prevent encryption. The will be applied to an SSL/TLS session. The use of the Null cipher is required when the encryption policy is set to . + The property can require, allow, or prevent encryption. The will be applied to an SSL/TLS session. The use of the Null cipher is required when the encryption policy is set to . ]]> @@ -207,7 +207,7 @@ ## Remarks When this property is set to `true`, client requests that use the `POST` method expect to receive a 100-Continue response from the server to indicate that the client should send the data to be posted. This mechanism allows clients to avoid sending large amounts of data over the network when the server, based on the request headers, intends to reject the request. - For additional information, see . + For additional information, see . ]]> diff --git a/xml/System.Net.Configuration/SocketElement.xml b/xml/System.Net.Configuration/SocketElement.xml index c91f02d34ba00..59caac920694f 100644 --- a/xml/System.Net.Configuration/SocketElement.xml +++ b/xml/System.Net.Configuration/SocketElement.xml @@ -120,7 +120,7 @@ property enables configuration of a restriction for an IPv6 socket to a specified scope, such as addresses with the same link local or site local prefix. This option enables applications to place access restrictions on IPv6 sockets. Such restrictions enable an application running on a private LAN to simply and robustly harden itself against external attacks. This option widens or narrows the scope of a listening socket, enabling unrestricted access from public and private users when appropriate, or restricting access only to the same site, as required. This option has three defined protection levels specified in the enumeration. + The property enables configuration of a restriction for an IPv6 socket to a specified scope, such as addresses with the same link local or site local prefix. This option enables applications to place access restrictions on IPv6 sockets. Such restrictions enable an application running on a private LAN to simply and robustly harden itself against external attacks. This option widens or narrows the scope of a listening socket, enabling unrestricted access from public and private users when appropriate, or restricting access only to the same site, as required. This option has three defined protection levels specified in the enumeration. ]]> diff --git a/xml/System.Net.Http/HttpMessageHandler.xml b/xml/System.Net.Http/HttpMessageHandler.xml index 1816c5f5cf5e2..7cb790acb814d 100644 --- a/xml/System.Net.Http/HttpMessageHandler.xml +++ b/xml/System.Net.Http/HttpMessageHandler.xml @@ -35,7 +35,7 @@ 3. - A class that operates at the bottom of the handler chain that actually handles the HTTP transport operations. -4. - A specialty class that operates at the bottom of the handler chain class that handles HTTP transport operations with options that are specific to the object. +4. - A specialty class that operates at the bottom of the handler chain class that handles HTTP transport operations with options that are specific to the object. If developers derive classes from and override the method, they must make sure that can get called concurrently by different threads. @@ -162,7 +162,7 @@ ## Remarks This operation will not block. The returned object will complete once the entire response including content is read. - The method is used primarily by the system. This method is called by the system one of the methods is called. Most apps will never call this method. + The method is used primarily by the system. This method is called by the system one of the methods is called. Most apps will never call this method. ]]> diff --git a/xml/System.Net.Http/HttpResponseMessage.xml b/xml/System.Net.Http/HttpResponseMessage.xml index b7e353bdc23b5..1c0b117a46162 100644 --- a/xml/System.Net.Http/HttpResponseMessage.xml +++ b/xml/System.Net.Http/HttpResponseMessage.xml @@ -27,7 +27,7 @@ is from one of the methods. + A common way to get an is from one of the methods. ]]> @@ -46,7 +46,7 @@ is from one of the methods. + A common way to get an is from one of the methods. ]]> diff --git a/xml/System.Net.Http/WinHttpHandler.xml b/xml/System.Net.Http/WinHttpHandler.xml index 115971c2b9a64..892463a540e58 100644 --- a/xml/System.Net.Http/WinHttpHandler.xml +++ b/xml/System.Net.Http/WinHttpHandler.xml @@ -156,7 +156,7 @@ . + The default value for this property is . ]]> @@ -240,7 +240,7 @@ . If this value is set to , then a container object must be initialized and assigned to the property. Otherwise, an exception will be thrown when trying to send a request. + The default for this property is . If this value is set to , then a container object must be initialized and assigned to the property. Otherwise, an exception will be thrown when trying to send a request. ]]> @@ -268,7 +268,7 @@ . + The default value for this property is . ]]> diff --git a/xml/System.Net.Mail/Attachment.xml b/xml/System.Net.Mail/Attachment.xml index 40204dd5874a1..12de9100b2b0c 100644 --- a/xml/System.Net.Mail/Attachment.xml +++ b/xml/System.Net.Mail/Attachment.xml @@ -25,7 +25,7 @@ class is used with the class. All messages include a , which contains the content of the message. In addition to the body, you might want to send additional files. These are sent as attachments and are represented as instances. To add an attachment to a mail message, add it to the collection. + The class is used with the class. All messages include a , which contains the content of the message. In addition to the body, you might want to send additional files. These are sent as attachments and are represented as instances. To add an attachment to a mail message, add it to the collection. Attachment content can be a , , or file name. You can specify the content in an attachment by using any of the constructors. @@ -180,7 +180,7 @@ (""), the for this attachment is constructed with the property set to `name`. The property is set to . + If `name` is not `null` or equal to (""), the for this attachment is constructed with the property set to `name`. The property is set to . If the stream's property is `false`, the attachment and the that contains it are not reusable. You must supply a stream that can be searched in order to reuse an attachment. @@ -261,7 +261,7 @@ (""), the property for this attachment is set to . If `mediaType` is not `null` and is not a zero-length string, it is used to construct the associated with this attachment. + If `mediaType` is `null` or equal to (""), the property for this attachment is set to . If `mediaType` is not `null` and is not a zero-length string, it is used to construct the associated with this attachment. @@ -311,7 +311,7 @@ (""), it is used to construct the class associated with this attachment. + If `mediaType` is not `null` or equal to (""), it is used to construct the class associated with this attachment. If `mediaType` and `name` both contain information, the value specified in `name` is used. The property is set to . diff --git a/xml/System.Net.Mail/AttachmentCollection.xml b/xml/System.Net.Mail/AttachmentCollection.xml index a86eb3a5ccfe7..0bded33eeb7f0 100644 --- a/xml/System.Net.Mail/AttachmentCollection.xml +++ b/xml/System.Net.Mail/AttachmentCollection.xml @@ -32,7 +32,7 @@ class are returned by the and properties. + Instances of the class are returned by the and properties. Use the property to specify copies of an e-mail message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use e-mail readers that cannot display HTML content. diff --git a/xml/System.Net.Mail/LinkedResourceCollection.xml b/xml/System.Net.Mail/LinkedResourceCollection.xml index a70f379956671..7c767eac6d99b 100644 --- a/xml/System.Net.Mail/LinkedResourceCollection.xml +++ b/xml/System.Net.Mail/LinkedResourceCollection.xml @@ -32,7 +32,7 @@ class is returned by the property. + An instance of the class is returned by the property. ]]> diff --git a/xml/System.Net.Mail/MailAddress.xml b/xml/System.Net.Mail/MailAddress.xml index 567a716b55c70..796b60df54c48 100644 --- a/xml/System.Net.Mail/MailAddress.xml +++ b/xml/System.Net.Mail/MailAddress.xml @@ -188,7 +188,7 @@ The following code example demonstrates sending an e-mail message by using the < If `displayName` contains non-ASCII characters, the iso-8859-1 character set is used for the `displayName` encoding. Encoding non-ASCII characters is discussed in RFC 1522, which is available at [http://www.ietf.org](http://www.ietf.org). - If `address` contains a display name, and `displayName` is not `null` and is not equal to , `displayName` overrides the value specified in `address`. + If `address` contains a display name, and `displayName` is not `null` and is not equal to , `displayName` overrides the value specified in `address`. @@ -251,7 +251,7 @@ The following code example demonstrates sending an e-mail message by using the < ## Remarks Leading and trailing white space in the display name is preserved. - If `address` contains a display name, and `displayName` is not `null` and is not equal to , `displayName` overrides the value specified in `address`. + If `address` contains a display name, and `displayName` is not `null` and is not equal to , `displayName` overrides the value specified in `address`. The method does not check if the `displayName` parameter is valid. This method removes surrounding quotes not displayed by the property. Quotes will be added before transmission, except where or is specified in the `displayNameEncoding` parameter. The encoding specified in the `displayNameEncoding` parameter will be applied to the property before transmission or is specified in the `displayNameEncoding` parameter. is the default encoding if none is specified. @@ -512,11 +512,11 @@ The following code example demonstrates sending an e-mail message by using the < property is not `null` and not equal to (""), returns a string composed using the following syntax: + The string returned by this method is not necessarily identical to the string specified when the instance was created. If the property is not `null` and not equal to (""), returns a string composed using the following syntax: \<@> - If is `null` or is equal to , returns the value of the property. + If is `null` or is equal to , returns the value of the property. diff --git a/xml/System.Net.Mail/MailAddressCollection.xml b/xml/System.Net.Mail/MailAddressCollection.xml index 2504eb1388615..cc0423da1e3ac 100644 --- a/xml/System.Net.Mail/MailAddressCollection.xml +++ b/xml/System.Net.Mail/MailAddressCollection.xml @@ -28,7 +28,7 @@ , , and properties return instances of this class that are used to hold the respective e-mail addresses. + The , , and properties return instances of this class that are used to hold the respective e-mail addresses. For details on the mail address formats supported by the class, see the class. diff --git a/xml/System.Net.Mail/MailMessage.xml b/xml/System.Net.Mail/MailMessage.xml index 3423acef61bbf..958b3c64a478d 100644 --- a/xml/System.Net.Mail/MailMessage.xml +++ b/xml/System.Net.Mail/MailMessage.xml @@ -890,7 +890,7 @@ property defaults to . + The value of the property defaults to . SMTP messages consist of headers and body parts. The IETF RFCs for SMTP restrict the header and body part names to be ASCII. However, the IETF RFCs allow header and body part values to contain Unicode characters. In any particular value, if non-ASCII characters exist, then the value is encoded using a combination of character encoding (UTF8 or Shift-JIS, for example) followed by byte encoding ( or for example). The result is usually that only ASCII characters are in the network transmission stream. diff --git a/xml/System.Net.Mail/SmtpClient.xml b/xml/System.Net.Mail/SmtpClient.xml index 61a6519d3c17b..7c062f45f85e1 100644 --- a/xml/System.Net.Mail/SmtpClient.xml +++ b/xml/System.Net.Mail/SmtpClient.xml @@ -50,13 +50,13 @@ - Credentials for authentication, if required by the SMTP server. See the property. -- The e-mail address of the sender. See the and methods that take a `from` parameter. Also see the property. +- The e-mail address of the sender. See the and methods that take a `from` parameter. Also see the property. -- The e-mail address or addresses of the recipients. See the and methods that take a `recipient` parameter. Also see the property. +- The e-mail address or addresses of the recipients. See the and methods that take a `recipient` parameter. Also see the property. -- The message content. See the and methods that take a `body` parameter. Also see the property. +- The message content. See the and methods that take a `body` parameter. Also see the property. - To include an attachment with an e-mail message, first create the attachment by using the class, and then add it to the message by using the property. Depending on the e-mail reader used by the recipients and the file type of the attachment, some recipients might not be able to read the attachment. For clients that cannot display the attachment in its original form, you can specify alternate views by using the property. + To include an attachment with an e-mail message, first create the attachment by using the class, and then add it to the message by using the property. Depending on the e-mail reader used by the recipients and the file type of the attachment, some recipients might not be able to read the attachment. For clients that cannot display the attachment in its original form, you can specify alternate views by using the property. You can use the application or machine configuration files to specify default host, port, and credentials values for all objects. For more information, see [<mailSettings> Element (Network Settings)](~/docs/framework/configure-apps/file-schema/network/mailsettings-element-network-settings.md). @@ -158,7 +158,7 @@ property. The and properties are initialized by using the settings in the application or machine configuration files. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. + The `host` parameter is used to initialize the value of the property. The and properties are initialized by using the settings in the application or machine configuration files. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. For more information about using the application and machine configuration files, see [<mailSettings> Element (Network Settings)](~/docs/framework/configure-apps/file-schema/network/mailsettings-element-network-settings.md). If information is specified using constructors or properties, this information overrides the configuration file settings. @@ -205,7 +205,7 @@ and properties, respectively. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. If `port` is zero, is initialized using the settings in the application or machine configuration files. The property is initialized using the settings in the application or machine configuration files. + The `host` and `port` parameters set the value of the and properties, respectively. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. If `port` is zero, is initialized using the settings in the application or machine configuration files. The property is initialized using the settings in the application or machine configuration files. For more information about using the application and machine configuration files, see [<mailSettings> Element (Network Settings)](~/docs/framework/configure-apps/file-schema/network/mailsettings-element-network-settings.md). If information is specified using constructors or properties, this information overrides the configuration file settings. diff --git a/xml/System.Net.Mail/SmtpDeliveryMethod.xml b/xml/System.Net.Mail/SmtpDeliveryMethod.xml index d4c3d054b53de..bb8644e1b723c 100644 --- a/xml/System.Net.Mail/SmtpDeliveryMethod.xml +++ b/xml/System.Net.Mail/SmtpDeliveryMethod.xml @@ -24,7 +24,7 @@ enumeration as a parameter to the property to specify the delivery method. + Use the enumeration as a parameter to the property to specify the delivery method. ]]> diff --git a/xml/System.Net.Mime/ContentDisposition.xml b/xml/System.Net.Mime/ContentDisposition.xml index 8518bb7765f7f..de4429db7882b 100644 --- a/xml/System.Net.Mime/ContentDisposition.xml +++ b/xml/System.Net.Mime/ContentDisposition.xml @@ -27,7 +27,7 @@ ## Remarks The information in the class accompanies an e-mail message that contains attachments when the e-mail message is sent to its destination. The information in can be used by software that displays e-mail to present the e-mail attachments in the manner intended by the sender. - E-mail messages are created using instances of the class. Instances of the class are used to add attachments to e-mail messages. To modify the for an attachment, get the instance from the property. + E-mail messages are created using instances of the class. Instances of the class are used to add attachments to e-mail messages. To modify the for an attachment, get the instance from the property. Content to be displayed as part of the message body has the disposition type of . Content that is not displayed but is attached in a separate file has the disposition type of . Use the property to control the disposition type for the attachment associated with an instance of . @@ -155,7 +155,7 @@ ## Remarks The property is used to send time stamp information with a file being sent in an e-mail message. This value sets the Creation-Date parameter in the Content-Disposition header sent with the email. - The class is used to compose an e-mail message. The class is used to attach a file to an e-mail message. To set , get the for the attachment from the property. + The class is used to compose an e-mail message. The class is used to attach a file to an e-mail message. To set , get the for the attachment from the property. The Content-Disposition header is described in RFC 2183 available at [http://www.ietf.org](http://www.ietf.org/). @@ -352,7 +352,7 @@ property sets the disposition type in the Content-Disposition header sent with the e-mail message. The disposition type can be used by software that displays e-mail to determine the correct way to present the e-mail attachments. Attachments with a disposition type of are usually displayed when the user opens the e-mail. Attachments with a disposition type of are usually not opened until the user performs some additional action, such as clicking an icon that represents the attachment. + The property sets the disposition type in the Content-Disposition header sent with the e-mail message. The disposition type can be used by software that displays e-mail to determine the correct way to present the e-mail attachments. Attachments with a disposition type of are usually displayed when the user opens the e-mail. Attachments with a disposition type of are usually not opened until the user performs some additional action, such as clicking an icon that represents the attachment. The Content-Disposition header is described in RFC 2183 available at [http://www.ietf.org](http://www.ietf.org/). @@ -398,7 +398,7 @@ ## Remarks The property is used to send time stamp information with a file being sent in an e-mail message. This value sets the Modification-Date parameter in the Content-Disposition header sent with the e-mail message. - The class is used to compose an e-mail message. The class is used to attach a file to an e-mail message. To set the property, get the for the attachment using the property. + The class is used to compose an e-mail message. The class is used to attach a file to an e-mail message. To set the property, get the for the attachment using the property. The Content-Disposition header is described in RFC 2183 available at [http://www.ietf.org](http://www.ietf.org/). @@ -488,7 +488,7 @@ ## Remarks The property is used to send time stamp information with a file being sent in an e-mail message. This value sets the Read-Date parameter in the Content-Disposition header sent with the e-mail message. - The class is used to compose an e-mail message. The class is used to attach a file to an e-mail message. To set , get the for the attachment by using the property. + The class is used to compose an e-mail message. The class is used to attach a file to an e-mail message. To set , get the for the attachment by using the property. The Content-Disposition header is described in RFC 2183 available at [http://www.ietf.org](http://www.ietf.org/). diff --git a/xml/System.Net.Mime/ContentType.xml b/xml/System.Net.Mime/ContentType.xml index 64fbdda12059f..8e48923e69b94 100644 --- a/xml/System.Net.Mime/ContentType.xml +++ b/xml/System.Net.Mime/ContentType.xml @@ -160,7 +160,7 @@ `content-type: multipart/mixed; boundary=-----boundary---0` - Set this property to `null` or to remove the boundary information from the header. + Set this property to `null` or to remove the boundary information from the header. The syntax of the Content-Type header is described in RFC 2045 Section 5.1. An in-depth discussion of the boundary parameter is contained in RFC 2046 Section 5.1.1. These RFCs are available at [http://www.ietf.org](http://www.ietf.org/). @@ -208,7 +208,7 @@ `content-type: application/x-myType; charset=us-ascii` - Set this property to `null` or to remove the charset information from the header. + Set this property to `null` or to remove the charset information from the header. A grammar that details the syntax of the Content-Type header is described in RFC 2045 Section 5.1. An in-depth discussion of the charset parameter is contained in RFC 2046 Section 4.1.2. These RFCs are available at [http://www.ietf.org](http://www.ietf.org/). @@ -316,7 +316,7 @@ `content-type: application/x-myType; name=data.xyz` - Set this property to `null` or to remove the name information from the header. + Set this property to `null` or to remove the name information from the header. The syntax of the Content-Type header is described in RFC 2045 Section 5.1. RFC 2046 provides detailed information on MIME media types. These RFCs are available at [http://www.ietf.org](http://www.ietf.org/). diff --git a/xml/System.Net.Mime/TransferEncoding.xml b/xml/System.Net.Mime/TransferEncoding.xml index 068cbab32fe0e..091e08b9aa417 100644 --- a/xml/System.Net.Mime/TransferEncoding.xml +++ b/xml/System.Net.Mime/TransferEncoding.xml @@ -24,7 +24,7 @@ enumeration are used with the property. + The values in the enumeration are used with the property. The Content-Transfer-Encoding header specifies the encoding of the associated message body so that it meets SMTP requirements. SMTP requires data for transport to be in 7-bit US-ASCII characters with lines no longer than 1000 characters. diff --git a/xml/System.Net.NetworkInformation/IPGlobalProperties.xml b/xml/System.Net.NetworkInformation/IPGlobalProperties.xml index b7e7ab6ca3287..39ac5c2bab183 100644 --- a/xml/System.Net.NetworkInformation/IPGlobalProperties.xml +++ b/xml/System.Net.NetworkInformation/IPGlobalProperties.xml @@ -111,9 +111,9 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. - The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. + The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. ]]> @@ -240,11 +240,11 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. The method ends a pending asynchronous request to retrieve the stable unicast IP address table. - The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. + The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. ]]> @@ -863,9 +863,9 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method will allow an application to retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method will allow an application to retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. - The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. + The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. ]]> @@ -909,9 +909,9 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method will allow an application to retrieve the list of stable unicast IP addresses as asynchronous operation. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method will allow an application to retrieve the list of stable unicast IP addresses as asynchronous operation. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. - The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. + The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. ]]> diff --git a/xml/System.Net.NetworkInformation/IPStatus.xml b/xml/System.Net.NetworkInformation/IPStatus.xml index aa864dd193808..3f6514f78ab4b 100644 --- a/xml/System.Net.NetworkInformation/IPStatus.xml +++ b/xml/System.Net.NetworkInformation/IPStatus.xml @@ -25,7 +25,7 @@ class uses the values in this enumeration to set the property. The class returns objects when you call the or methods to check whether you can reach a computer across the network. + The class uses the values in this enumeration to set the property. The class returns objects when you call the or methods to check whether you can reach a computer across the network. > [!WARNING] > The DestinationProhibited and DestinationProtocolUnreachable enumeration values have the same numeric value. This is possible because DestinationProhibited applies only to IPv6 and DestinationProtocolUnreachable applies only to IPv4. diff --git a/xml/System.Net.NetworkInformation/NetworkInformationPermission.xml b/xml/System.Net.NetworkInformation/NetworkInformationPermission.xml index da4b8ea805ab8..a4fc9622ae482 100644 --- a/xml/System.Net.NetworkInformation/NetworkInformationPermission.xml +++ b/xml/System.Net.NetworkInformation/NetworkInformationPermission.xml @@ -144,7 +144,7 @@ created with is given | access. A created with is given access. + A created with is given | access. A created with is given access. diff --git a/xml/System.Net.NetworkInformation/NetworkInterfaceType.xml b/xml/System.Net.NetworkInformation/NetworkInterfaceType.xml index 2a5cf17485b3d..2ca9ca776b846 100644 --- a/xml/System.Net.NetworkInformation/NetworkInterfaceType.xml +++ b/xml/System.Net.NetworkInformation/NetworkInterfaceType.xml @@ -27,7 +27,7 @@ ## Remarks Network interfaces, also known as network adapters, connect a computer to a network. The interface type defines the transmission media that provides network connectivity. - This enumeration defines the values returned by the property. + This enumeration defines the values returned by the property. ]]> diff --git a/xml/System.Net.NetworkInformation/PhysicalAddress.xml b/xml/System.Net.NetworkInformation/PhysicalAddress.xml index 814e956c1a6b9..9095aca5c8821 100644 --- a/xml/System.Net.NetworkInformation/PhysicalAddress.xml +++ b/xml/System.Net.NetworkInformation/PhysicalAddress.xml @@ -28,7 +28,7 @@ ## Remarks The MAC address, or physical address, is a hardware address that uniquely identifies each node, such as a computer or printer, on a network. - Instances of this class are returned by the method. + Instances of this class are returned by the method. diff --git a/xml/System.Net.NetworkInformation/Ping.xml b/xml/System.Net.NetworkInformation/Ping.xml index 36150a8be939e..f0e2369f15e8d 100644 --- a/xml/System.Net.NetworkInformation/Ping.xml +++ b/xml/System.Net.NetworkInformation/Ping.xml @@ -53,7 +53,7 @@ ||Contains the data associated with events, which are raised when a call completes or is canceled.| ||The delegate that provides the callback method invoked when a call completes or is canceled.| - The and methods return the reply in a object. The property returns an value to indicate the outcome of the request. + The and methods return the reply in a object. The property returns an value to indicate the outcome of the request. When sending the request, you must specify the remote computer. You can do this by providing a host name string, an IP address in string format, or an object. diff --git a/xml/System.Net.Security/SslStream.xml b/xml/System.Net.Security/SslStream.xml index 27d2b925eb94d..3690f7dfe5744 100644 --- a/xml/System.Net.Security/SslStream.xml +++ b/xml/System.Net.Security/SslStream.xml @@ -126,9 +126,9 @@ defaults to for the instance that is constructed. + If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. - The use of the Null cipher is required when the encryption policy is set to . + The use of the Null cipher is required when the encryption policy is set to . ]]> @@ -179,9 +179,9 @@ ## Remarks When you specify `true` for the `leaveStreamOpen` parameter, closing the has no effect on the `innerStream` stream; you must explicitly close `innerStream` when you no longer need it. - If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. + If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. - The use of the Null cipher is required when the encryption policy is set to . + The use of the Null cipher is required when the encryption policy is set to . @@ -246,9 +246,9 @@ The security protocol and cryptographic algorithms are already selected when the `userCertificateValidationCallback` delegate's method is invoked. You can use the method to determine whether the selected cryptographic algorithms and strengths are sufficient for your application. If not, the method should return `false` to prevent the from being created. - If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. + If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. - The use of the Null cipher is required when the encryption policy is set to . + The use of the Null cipher is required when the encryption policy is set to . > [!NOTE] > The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. @@ -323,9 +323,9 @@ The `userCertificateSelectionCallback` delegate is useful when your application has multiple certificates and must dynamically choose a certificate. Certificates in the "MY" store are passed to the method invoked by the delegate. - If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. + If a value is not specified in the configuration file for encryptionpolicy, the defaults to for the instance that is constructed. - The use of the Null cipher is required when the encryption policy is set to . + The use of the Null cipher is required when the encryption policy is set to . > [!NOTE] > The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of P:System.Net.HttpWebRequest.ClientCertificates (if there is one), or tries to reuse an anonymous sessions if P:System.Net.HttpWebRequest.ClientCertificates is empty. @@ -396,7 +396,7 @@ . + The use of the Null cipher is required when the `encryptionPolicy` parameter is set to . ]]> @@ -3009,7 +3009,7 @@ on the underlying stream specified when this was created. + This method invokes on the underlying stream specified when this was created. ]]> diff --git a/xml/System.Net.Sockets/LingerOption.xml b/xml/System.Net.Sockets/LingerOption.xml index b73afddc17d1a..71b60f96087af 100644 --- a/xml/System.Net.Sockets/LingerOption.xml +++ b/xml/System.Net.Sockets/LingerOption.xml @@ -26,7 +26,7 @@ or method. If you want to specify the amount of time that the will attempt to transmit unsent data after closing, create a with the `enable` parameter set to `true`, and the `seconds` parameter set to the desired amount of time. The `seconds` parameter is used to indicate how long you would like the to remain connected before timing out. If you do not want the to stay connected for any length of time after closing, create a instance with the `enable` parameter set to `true` and the `seconds` parameter set to zero. In this case, the will close immediately and any unsent data will be lost. Once created, pass the to the method. If you are sending and receiving data with a , then set the instance in the property. + There may still be data available in the outgoing network buffer after an application calls the or method. If you want to specify the amount of time that the will attempt to transmit unsent data after closing, create a with the `enable` parameter set to `true`, and the `seconds` parameter set to the desired amount of time. The `seconds` parameter is used to indicate how long you would like the to remain connected before timing out. If you do not want the to stay connected for any length of time after closing, create a instance with the `enable` parameter set to `true` and the `seconds` parameter set to zero. In this case, the will close immediately and any unsent data will be lost. Once created, pass the to the method. If you are sending and receiving data with a , then set the instance in the property. The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a when the property is not set and for a when the property is not set. @@ -77,7 +77,7 @@ ## Remarks There may still be data available in the outgoing network buffer after you close the . Use the `enable` parameter to specify whether you would like the to continue transmitting unsent data after the close method is called. Use the `seconds` parameter to indicate how long you would like the to attempt transferring unsent data before timing out. If you specify `true` for the `enable` parameter and 0 for the `seconds` parameter, the will attempt to send data until there is no data left in the outgoing network buffer. If you specify `false` for the `enable` parameter, the will close immediately and any unsent data will be lost. - The following table describes the behavior on the and methods based on the possible values of the `enable` and `seconds` parameters when an T:System.Net.Sockets.LingerOption instance is created and set in the or property. + The following table describes the behavior on the and methods based on the possible values of the `enable` and `seconds` parameters when an T:System.Net.Sockets.LingerOption instance is created and set in the or property. |`enable`|`seconds`|Behavior| |--------------|---------------|--------------| diff --git a/xml/System.Net.Sockets/MulticastOption.xml b/xml/System.Net.Sockets/MulticastOption.xml index 26ac0c981cac9..744b99a96a256 100644 --- a/xml/System.Net.Sockets/MulticastOption.xml +++ b/xml/System.Net.Sockets/MulticastOption.xml @@ -26,11 +26,11 @@ to store the of a multicast group you want to join or drop. Use the method with the following parameters to join a multicast group. + Use a to store the of a multicast group you want to join or drop. Use the method with the following parameters to join a multicast group. |Parameter|Value| |---------------|-----------| -|socketOptionLevel|| +|socketOptionLevel|| |socketOptionName|| |object|| diff --git a/xml/System.Net.Sockets/NetworkStream.xml b/xml/System.Net.Sockets/NetworkStream.xml index ef175545fe571..359513d955ebc 100644 --- a/xml/System.Net.Sockets/NetworkStream.xml +++ b/xml/System.Net.Sockets/NetworkStream.xml @@ -903,7 +903,7 @@ . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information about using the Finalize method, see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). @@ -940,7 +940,7 @@ method implements the method; however, because is not buffered, it has no affect on network streams. Calling the method does not throw an exception. + The method implements the method; however, because is not buffered, it has no affect on network streams. Calling the method does not throw an exception. ]]> @@ -1397,7 +1397,7 @@ method starts at the specified `offset` and sends `size` bytes from the contents of `buffer` to the network. The method blocks until the requested number of bytes is sent or a is thrown. If you receive a , use the property to obtain the specific error code, and refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. + The method starts at the specified `offset` and sends `size` bytes from the contents of `buffer` to the network. The method blocks until the requested number of bytes is sent or a is thrown. If you receive a , use the property to obtain the specific error code, and refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > Check to see if the is writable by accessing the property. If you attempt to write to a that is not writable, you will get an . If you receive an , check the property to determine if it was caused by a . diff --git a/xml/System.Net.Sockets/SelectMode.xml b/xml/System.Net.Sockets/SelectMode.xml index 4b9f8f25f1bae..be65a2b700a2c 100644 --- a/xml/System.Net.Sockets/SelectMode.xml +++ b/xml/System.Net.Sockets/SelectMode.xml @@ -25,12 +25,12 @@ enumeration defines the polling modes that can be passed to the method. Use the SelectRead value to determine if a listening has incoming connection requests. Use the SelectWrite value to determine if a is writeable. Use the SelectError value to determine if there is an error condition present on the . For explanations of writeability, readability, and the presence of error conditions, see the method. + The enumeration defines the polling modes that can be passed to the method. Use the SelectRead value to determine if a listening has incoming connection requests. Use the SelectWrite value to determine if a is writeable. Use the SelectError value to determine if there is an error condition present on the . For explanations of writeability, readability, and the presence of error conditions, see the method. ## Examples - The following example checks the status of a using all three enumeration values. A call to using the SelectWrite enumerated value should return `true`. + The following example checks the status of a using all three enumeration values. A call to using the SelectWrite enumerated value should return `true`. [!code-cpp[SelectModeExample#1](~/samples/snippets/cpp/VS_Snippets_Remoting/SelectModeExample/CPP/source.cpp#1)] [!code-csharp[SelectModeExample#1](~/samples/snippets/csharp/VS_Snippets_Remoting/SelectModeExample/CS/source.cs#1)] diff --git a/xml/System.Net.Sockets/SendPacketsElement.xml b/xml/System.Net.Sockets/SendPacketsElement.xml index 39a926ed20c8f..f83b6d02e5194 100644 --- a/xml/System.Net.Sockets/SendPacketsElement.xml +++ b/xml/System.Net.Sockets/SendPacketsElement.xml @@ -26,7 +26,7 @@ class is used to enhance the class for use by server applications that use asynchronous network I/O to achieve the highest performance. The class is used with the property to get or set a data buffer or file to be sent using the method. + The class is used to enhance the class for use by server applications that use asynchronous network I/O to achieve the highest performance. The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -62,7 +62,7 @@ constructor initializes a new instance of the class with a byte array of data. The class is used with the property to get or set a data buffer or file to be sent using the method. + The constructor initializes a new instance of the class with a byte array of data. The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -98,7 +98,7 @@ constructor initializes a new instance of the class with a filename of a file. The class is used with the property to get or set a data buffer or file to be sent using the method. + The constructor initializes a new instance of the class with a filename of a file. The class is used with the property to get or set a data buffer or file to be sent using the method. Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. @@ -140,7 +140,7 @@ constructor initializes a new instance of the class with a byte array of data. The class is used with the property to get or set a data buffer or file to be sent using the method. + The constructor initializes a new instance of the class with a byte array of data. The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -183,7 +183,7 @@ constructor initializes a new instance of the class with a filename of a file. The class is used with the property to get or set a data buffer or file to be sent using the method. + The constructor initializes a new instance of the class with a filename of a file. The class is used with the property to get or set a data buffer or file to be sent using the method. Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. @@ -230,7 +230,7 @@ constructor initializes a new instance of the class with a byte array of data. The class is used with the property to get or set a data buffer or file to be sent using the method. + The constructor initializes a new instance of the class with a byte array of data. The class is used with the property to get or set a data buffer or file to be sent using the method. ]]> @@ -275,7 +275,7 @@ constructor initializes a new instance of the class with a filename of a file. The class is used with the property to get or set a data buffer or file to be sent using the method. + The constructor initializes a new instance of the class with a filename of a file. The class is used with the property to get or set a data buffer or file to be sent using the method. Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index 1bbcac9bd0788..1861598e6c580 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -138,7 +138,7 @@ The `socketType` parameter specifies the type of the class and the `protocolType` parameter specifies the protocol used by . The two parameters are not independent. Often the type is implicit in the protocol. If the combination of type and protocol type results in an invalid , this constructor throws a . > [!NOTE] -> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -184,7 +184,7 @@ The `addressFamily` parameter specifies the addressing scheme that the class uses, the `socketType` parameter specifies the type of the class, and the `protocolType` parameter specifies the protocol used by . The three parameters are not independent. Some address families restrict which protocols can be used with them, and often the type is implicit in the protocol. If the combination of address family, type, and protocol type results in an invalid , this constructor throws a . > [!NOTE] -> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -237,7 +237,7 @@ In blocking mode, blocks until an incoming connection attempt is queued. Once a connection is accepted, the original continues queuing incoming connection requests until you close it. - If you call this method using a non-blocking , and no connection requests are queued, throws a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. + If you call this method using a non-blocking , and no connection requests are queued, throws a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > Before calling the method, you must first call the method to listen for and queue incoming connection requests. @@ -298,23 +298,23 @@ ## Remarks Connection-oriented protocols can use the method to asynchronously process incoming connection attempts. Accepting connections asynchronously gives you the ability to send and receive data within a separate execution thread. Before calling the method, you must call the method to listen for and queue incoming connection requests. - To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and hook it to the event. + To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and hook it to the event. - The following properties and events on the object are required: + The following properties and events on the object are required: -- +- - The caller can optionally specify an existing to use for the incoming connection by specifying the to use with the property. + The caller can optionally specify an existing to use for the incoming connection by specifying the to use with the property. - If the property is null, a new is constructed with the same , , and as the current and set as the property. + If the property is null, a new is constructed with the same , , and as the current and set as the property. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - Optionally, a buffer may be provided in which to receive the initial block of data on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to receive and the property needs to be set to the maximum number of bytes of data to receive in the buffer. These properties can be set using the method. Part of the buffer passed in will be consumed internally for use by the the underlying Winsock AcceptEx call. This means that the amount of data returned will always be less than the value of the property on the instance provided. The amount of the buffer used internally varies based on the address family of the socket. The minimum buffer size required is 288 bytes. If a larger buffer size is specified, then the will expect some extra data other than the address data received by the Winsock AcceptEx call and will wait until this extra data is received. If a timeout occurs, the connection is reset. So if extra data is expected of a specific amount, then the buffer size should be set to the minimum buffer size plus this amount. + Optionally, a buffer may be provided in which to receive the initial block of data on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to receive and the property needs to be set to the maximum number of bytes of data to receive in the buffer. These properties can be set using the method. Part of the buffer passed in will be consumed internally for use by the the underlying Winsock AcceptEx call. This means that the amount of data returned will always be less than the value of the property on the instance provided. The amount of the buffer used internally varies based on the address family of the socket. The minimum buffer size required is 288 bytes. If a larger buffer size is specified, then the will expect some extra data other than the address data received by the Winsock AcceptEx call and will wait until this extra data is received. If a timeout occurs, the connection is reset. So if extra data is expected of a specific amount, then the buffer size should be set to the minimum buffer size plus this amount. - The completion callback method should examine the property to determine if the operation was successful. + The completion callback method should examine the property to determine if the operation was successful. - The event can occur in some cases when no connection has been accepted and cause the property to be set to . This can occur as a result of port scanning using a half-open SYN type scan (a SYN -> SYN-ACK -> RST sequence). Applications using the method should be prepared to handle this condition. + The event can occur in some cases when no connection has been accepted and cause the property to be set to . This can occur as a result of port scanning using a half-open SYN type scan (a SYN -> SYN-ACK -> RST sequence). Applications using the method should be prepared to handle this condition. ]]> @@ -407,7 +407,7 @@ ## Remarks If you are using a non-blocking , is a good way to determine whether data is queued for reading, before calling . The available data is the total amount of data queued in the network buffer for reading. If no data is queued in the network buffer, returns 0. - If the remote host shuts down or closes the connection, can throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. + If the remote host shuts down or closes the connection, can throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -464,7 +464,7 @@ You must create a callback method that implements the delegate and pass its name to the method. To do this, at the very minimum, you must pass the listening object to through the `state` parameter. If your callback needs more information, you can create a small class to hold the and the other required information. Pass an instance of this class to the method through the `state` parameter. - Your callback method should invoke the method. When your application calls , the system usually uses a separate thread to execute the specified callback method and blocks on until a pending connection is retrieved. will return a new object that you can use to send and receive data with the remote host. You cannot use this returned to accept any additional connections from the connection queue. If you want the original thread to block after you call the method, use . Call the Set method on a in the callback method when you want the original thread to continue executing. + Your callback method should invoke the method. When your application calls , the system usually uses a separate thread to execute the specified callback method and blocks on until a pending connection is retrieved. will return a new object that you can use to send and receive data with the remote host. You cannot use this returned to accept any additional connections from the connection queue. If you want the original thread to block after you call the method, use . Call the Set method on a in the callback method when you want the original thread to continue executing. The system may also use the calling thread to invoke the callback method. In this case, the property on the returned will be set to indicate that the method completed synchronously. @@ -476,7 +476,7 @@ > You can use the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -551,7 +551,7 @@ Your callback method should invoke the method. When your application calls , the system usually uses a separate thread to execute the specified callback method and blocks on until a pending connection is retrieved. - returns a new that you can use to send and receive data with the remote host. You cannot use this returned to accept any additional connections from the connection queue. If you want the original thread to block after you call the method, use . Call the Set method on a in the callback method when you want the original thread to continue executing. + returns a new that you can use to send and receive data with the remote host. You cannot use this returned to accept any additional connections from the connection queue. If you want the original thread to block after you call the method, use . Call the Set method on a in the callback method when you want the original thread to continue executing. The system may also use the calling thread to invoke the callback method. In this case, the property on the returned will be set to indicate that the method completed synchronously. @@ -563,7 +563,7 @@ > You can call use the property of the returned object to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -639,7 +639,7 @@ Your callback method should invoke the method. When your application calls , the system usually uses a separate thread to execute the specified callback method and blocks on until a pending connection is retrieved. - returns a new object that you can use to send and receive data with the remote host. You cannot use this returned to accept any additional connections from the connection queue. If you want the original thread to block after you call the method, use . Call the Set method on a in the callback method when you want the original thread to continue executing. + returns a new object that you can use to send and receive data with the remote host. You cannot use this returned to accept any additional connections from the connection queue. If you want the original thread to block after you call the method, use . Call the Set method on a in the callback method when you want the original thread to continue executing. The system may also use the calling thread to invoke the callback method. In this case, the property on the returned will be set to indicate that the method completed synchronously. @@ -651,7 +651,7 @@ > You can use the property of the returned object to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -730,7 +730,7 @@ To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an to indicate that the operation has been cancelled. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. @@ -807,7 +807,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](~/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md) > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. Also the that is used must be different. @@ -888,7 +888,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](~/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md). > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. Also the that is used must be different. @@ -969,7 +969,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](~/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md) > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. Also the that is used must be different. @@ -1043,7 +1043,7 @@ The method uses a separate thread to invoke the specified callback method. The method blocks until the pending disconnect is complete. For additional information on writing callback methods, see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -1115,7 +1115,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](~/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md). > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -1192,7 +1192,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](~/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md). > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -1266,7 +1266,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](~/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md). > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -1373,7 +1373,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](~/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md). > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -1458,7 +1458,7 @@ You can create a callback method that implements the delegate and pass its name to the method. To do this, at the very minimum, your `state` parameter must contain the connected or default being used for communication. If your callback needs more information, you can create a small class to hold the and the other required information. Pass an instance of this class to the method through the `state` parameter. - Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and it will block on until the reads data or throws an exception. If you want the original thread to block after you call the method, use . Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information on writing callback methods, see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). + Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and it will block on until the reads data or throws an exception. If you want the original thread to block after you call the method, use . Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information on writing callback methods, see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). > [!NOTE] > Before calling , you must explicitly bind the to a local endpoint using the method, or will throw a . @@ -1474,7 +1474,7 @@ To cancel a pending , call the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -1578,7 +1578,7 @@ This method reads data into the `buffer` parameter, and captures the remote host endpoint from which the data is sent, as well as information about the received packet. For information on how to retrieve this endpoint, refer to . This method is most useful if you intend to asynchronously receive connectionless datagrams from an unknown host or multiple hosts. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -1655,14 +1655,14 @@ You can create a callback method that implements the delegate and pass its name to the method. To do this, at the very minimum, your `state` parameter must contain the connected or default being used for communication. If your callback needs more information, you can create a small class or structure to hold the and the other required information. Pass an instance of this class to the method through the `state` parameter. - Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). + Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -1738,14 +1738,14 @@ You can create a callback method that implements the delegate and pass its name to the method. To do this, at the very minimum, your `state` parameter must contain the connected or default being used for communication. If your callback needs more information, you can create a small class or structure to hold the and the other required information. Pass an instance of this class to the method through the `state` parameter. - Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). + Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -1818,14 +1818,14 @@ You can create a callback method that implements the delegate and pass its name to the method. To do this, at the very minimum, your `state` parameter must contain the connected or default being used for communication. If your callback needs more information, you can create a small class or structure to hold the and the other required information. Pass an instance of this class to the method through the `state` parameter. - Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). + Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -1921,14 +1921,14 @@ You can create a callback method that implements the delegate and pass its name to the method. To do this, at the very minimum, your `state` parameter must contain the connected or default being used for communication. If your callback needs more information, you can create a small class or structure to hold the and the other required information. Pass an instance of this class to the method through the `state` parameter. - Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). + Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use . It is okay to use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to or . With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -2016,7 +2016,7 @@ Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -2097,7 +2097,7 @@ Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must also be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -2173,18 +2173,18 @@ You can create a callback method that implements the delegate and pass its name to the method. To do this, at the very minimum, your `state` parameter must contain the connected or default being used for communication. If your callback needs more information, you can create a small class to hold the , and the other required information. Pass an instance of this class to the method through the `state` parameter. - Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information about writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). + Your callback method should invoke the method. When your application calls , the system will use a separate thread to execute the specified callback method, and will block on until the sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the method, use the method. Call the Set method on a T:System.Threading.ManualResetEvent in the callback method when you want the original thread to continue executing. For additional information about writing callback methods see [Marshaling a Delegate as a Callback Method](~/docs/framework/interop/marshaling-a-delegate-as-a-callback-method.md). If you are using a connection-oriented protocol, you must first call the , , , or method, or will throw a . will ignore the `remoteEP` parameter and send data to the established in the , , , or method. If you are using a connectionless protocol, you do not need to establish a default remote host with the or method prior to calling . You only need to do this if you intend to call the method. If you do call the or method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. - If you want to send data to a broadcast address, you must first call the method and set the socket option to . -You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you want to send data to a broadcast address, you must first call the method and set the socket option to . -You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -2262,7 +2262,7 @@ ## Remarks Use the method if you need to use a specific local endpoint. You must call before you can call the method. You do not need to call before using the method unless you need to use a specific local endpoint. You can use the method on both connectionless and connection-oriented protocols. - Before calling , you must first create the local from which you intend to communicate data. If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. + Before calling , you must first create the local from which you intend to communicate data. If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. If you use the above approach, you can discover what local network address and port number has been assigned by calling the . If you are using a connection-oriented protocol, will not return the locally assigned network address until after you have made a call to the or method. If you are using a connectionless protocol, you will not have access to this information until you have completed a send or receive. @@ -2275,7 +2275,7 @@ > You must call the method if you intend to receive connectionless datagrams using the method. > [!NOTE] -> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -2334,7 +2334,7 @@ If you are in blocking mode, and you make a method call which does not complete immediately, your application will block execution until the requested operation completes. If you want execution to continue even though the requested operation is not complete, change the property to `false`. The property has no effect on asynchronous methods. If you are sending and receiving data asynchronously and want to block execution, use the class. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -2530,9 +2530,9 @@ ## Remarks If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call , you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. - The method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + The method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] > If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. @@ -2599,9 +2599,9 @@ ## Remarks If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. - method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] > If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. @@ -2668,9 +2668,9 @@ ## Remarks This method is typically used immediately after a call to , which can return multiple IP addresses for a single host. If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. - method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] > If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. @@ -2737,9 +2737,9 @@ ## Remarks If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote host. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. - method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. @@ -2808,32 +2808,32 @@ ## Remarks If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the remote host. If you are using a connectionless protocol, establishes a default remote host. - To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. + To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. - The caller must set the property to the of the remote host to connect to. + The caller must set the property to the of the remote host to connect to. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to change the default remote host, call the method again with the desired endpoint. If you wish to set the default remote host to a broadcast address, you must first call and set Broadcast to `true`. If this is not done, the method will throw a . - The following properties and events on the object are required: + The following properties and events on the object are required: -- +- -- +- - Optionally, a buffer may be provided which will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. + Optionally, a buffer may be provided which will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network IP address and port number until you call the or methods. - The method throws if the address family of the and the are not the same address family. + The method throws if the address family of the and the are not the same address family. > [!NOTE] -> If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. ]]> @@ -2887,32 +2887,32 @@ ## Remarks If you are using a connection-oriented protocol, the M:System.Net.Sockets.Socket.ConnectAsync(System.Net.Sockets.SocketType,System.Net.Sockets.ProtocolType,System.Net.Sockets.SocketAsyncEventArgs) method starts an asynchronous request for a connection to the remote host. If you are using a connectionless protocol, establishes a default remote host specified by the `socketType` and `protocolType` parameters. - To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. + To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. - The caller must set the property to the of the remote host to connect to. + The caller must set the property to the of the remote host to connect to. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to change the default remote host, call the method again with the desired endpoint. If you wish to set the default remote host to a broadcast address, you must first call and set Broadcast to `true`. If this is not done, the method will throw a . - The following properties and events on the object are required: + The following properties and events on the object are required: -- +- -- +- - Optionally, a buffer may be provided which will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. + Optionally, a buffer may be provided which will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network IP address and port number until you call the or methods. - The method throws if the address family of the and the are not the same address family. + The method throws if the address family of the and the are not the same address family. > [!NOTE] -> If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. ]]> @@ -3013,7 +3013,7 @@ If you need to call without first calling , you can set the option to `false` and specify a nonzero time-out interval to ensure that data queued for outgoing transmission is sent. then blocks until the data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -3067,7 +3067,7 @@ method requests a disconnect from a remote endpoint. If you set to `true` in the `e` parameter, the socket can be reused. + When using a connection-oriented protocol, calling the method requests a disconnect from a remote endpoint. If you set to `true` in the `e` parameter, the socket can be reused. ]]> @@ -3386,7 +3386,7 @@ The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -3454,7 +3454,7 @@ The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -3523,7 +3523,7 @@ The method blocks until a connection is pending in the incoming connection queue. The method accepts the incoming connection and returns a new that can be used to send data to and receive data from the remote host. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -3587,7 +3587,7 @@ Within the callback method, call the method of the parameter to obtain the on which the connection attempt is being made. After obtaining the , you can call the method to successfully complete the connection attempt. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -3647,7 +3647,7 @@ completes a call to . The method blocks until the disconnect completes. For information about asynchronous operations, see the Asynchronous Programming Overview topic in the MSDN library. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -3719,7 +3719,7 @@ To cancel a pending , call the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -3793,7 +3793,7 @@ To obtain the received data, call the method of the , and extract the buffer contained in the resulting state object. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -3853,10 +3853,10 @@ Within the callback method, call the method of the to obtain the state object passed to the method. Extract the receiving from this state object. After obtaining the , you can call the method to successfully complete the read operation and return the number of bytes read. - The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. To obtain the received data, call the method of the object, and extract the buffer contained in the resulting state object. To identify the originating host, extract the and cast it to an . Use the method to obtain the IP address and the method to obtain the port number. + The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. To obtain the received data, call the method of the object, and extract the buffer contained in the resulting state object. To identify the originating host, extract the and cast it to an . Use the method to obtain the IP address and the method to obtain the port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -3990,7 +3990,7 @@ There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -4067,7 +4067,7 @@ There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -4130,7 +4130,7 @@ If you are using a connectionless protocol, blocks until the datagram is sent. If you are using a connection-oriented protocol, blocks until the entire file is sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -4197,7 +4197,7 @@ If you are using a connectionless protocol, will block until the datagram is sent. If you are using a connection-oriented protocol, will block until the requested number of bytes are sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -4348,7 +4348,7 @@ options determine the behavior of the current . Use this overload to get the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to set the value of any of the options listed above, use the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -4410,7 +4410,7 @@ ## Remarks options determine the behavior of the current . Upon successful completion of this method, the array specified by the `optionValue` parameter contains the value of the specified option. - When the length of the `optionValue` array is smaller than the number of bytes required to store the value of the specified option, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. Use this overload for any sockets that are represented by Boolean values or integers. + When the length of the `optionValue` array is smaller than the number of bytes required to store the value of the specified option, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. Use this overload for any sockets that are represented by Boolean values or integers. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -4474,7 +4474,7 @@ The `optionLength` parameter sets the maximum size of the returned byte array. If the option value requires fewer bytes, the array will contain only that many bytes. If the option value requires more bytes, will throw a . Use this overload for any sockets that are represented by Boolean values or integers. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -4565,7 +4565,7 @@ The method provides low-level access to the operating system underlying the current instance of the class. For more information, see the WSAIoctl documentation in the MSDN library. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -4627,7 +4627,7 @@ This method provides low-level access to the operating system underlying the current instance of the class. For more, see the WSAIoctl documentation in the MSDN library. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -4844,12 +4844,12 @@ property gets an that contains the local IP address and port number to which your is bound. You must cast this to an before retrieving any information. You can then call the method to retrieve the local , and the method to retrieve the local port number. + The property gets an that contains the local IP address and port number to which your is bound. You must cast this to an before retrieving any information. You can then call the method to retrieve the local , and the method to retrieve the local port number. The property is usually set after you make a call to the method. If you allow the system to assign your socket's local IP address and port number, the property will be set after the first I/O operation. For connection-oriented protocols, the first I/O operation would be a call to the or method. For connectionless protocols, the first I/O operation would be any of the send or receive calls. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5108,10 +5108,10 @@ method will check the state of the . Specify for the `selectMode` parameter to determine if the is readable. Specify to determine if the is writable. Use to detect an error condition. will block execution until the specified time period, measured in `microseconds`, elapses. Set the `microSeconds` parameter to a negative integer if you would like to wait indefinitely for a response. If you want to check the status of multiple sockets, you might prefer to use the method. + The method will check the state of the . Specify for the `selectMode` parameter to determine if the is readable. Specify to determine if the is writable. Use to detect an error condition. will block execution until the specified time period, measured in `microseconds`, elapses. Set the `microSeconds` parameter to a negative integer if you would like to wait indefinitely for a response. If you want to check the status of multiple sockets, you might prefer to use the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This method cannot detect certain kinds of connection problems, such as a broken network cable, or that the remote host was shut down ungracefully. You must attempt to send or receive data to detect these kinds of errors. @@ -5218,14 +5218,14 @@ If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5288,14 +5288,14 @@ If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. **Note** This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5355,7 +5355,7 @@ If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5425,14 +5425,14 @@ If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5502,14 +5502,14 @@ If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, The method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, The method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5583,14 +5583,14 @@ If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5652,14 +5652,14 @@ If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the size parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5751,14 +5751,14 @@ If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the size parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -5835,25 +5835,25 @@ For bound connectionless sockets, this function restricts the addresses from which received messages are accepted. The function only returns messages from the remote address specified in the connection. Messages from other addresses are silently discarded. - The property on the `e` parameter provides the Window Sockets service provider with additional information about the read request. For more information about how to use this parameter, see . + The property on the `e` parameter provides the Window Sockets service provider with additional information about the read request. For more information about how to use this parameter, see . - The following properties and events on the object are required to successfully call this method: + The following properties and events on the object are required to successfully call this method: -- or +- or -- if is set +- if is set -- if is set +- if is set -- +- - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. For byte stream-style sockets, incoming data is placed into the buffer until the buffer is filled, the connection is closed, or the internally buffered data is exhausted. For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer associated with the `e` parameter. If the message is larger than the buffer, the buffer is filled with the first part of the message. - For connection-oriented sockets, the method can indicate the graceful termination of the virtual circuit in one of two ways that depend on whether the socket is byte stream or message oriented. For byte streams, zero bytes having been read indicates graceful closure and that no more bytes will ever be read. For message-oriented sockets, where a zero byte message is often allowable, a with the set to the native Winsock WSAEDISCON error code (10101) is used to indicate graceful closure. In any case, a with the set to the native Winsock WSAECONNRESET error code (10054) indicates an abortive close has occurred. + For connection-oriented sockets, the method can indicate the graceful termination of the virtual circuit in one of two ways that depend on whether the socket is byte stream or message oriented. For byte streams, zero bytes having been read indicates graceful closure and that no more bytes will ever be read. For message-oriented sockets, where a zero byte message is often allowable, a with the set to the native Winsock WSAEDISCON error code (10101) is used to indicate graceful closure. In any case, a with the set to the native Winsock WSAECONNRESET error code (10054) indicates an abortive close has occurred. ]]> @@ -5961,7 +5961,7 @@ With connection-oriented sockets, will read as much data as is available up to the size of `buffer`. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The of the used in needs to match the of the used in . @@ -6045,7 +6045,7 @@ With connection-oriented sockets, will read as much data as is available up to the size of `buffer`. If the remote host shuts down the connection with the method, and all available data has been Received, the method will complete immediately and return zero bytes. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The of the used in needs to match the of the used in . @@ -6128,7 +6128,7 @@ With connection-oriented sockets, will read as much data as is available up to the number of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] -> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The of the used in needs to match the of the used in . @@ -6226,7 +6226,7 @@ With connection-oriented sockets, will read as much data as is available up to the amount of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been Received, the method will complete immediately and return zero bytes. > [!NOTE] -> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The of the used in needs to match the of the used in . @@ -6316,27 +6316,27 @@ ## Remarks The method is used primarily to receive data on a connectionless socket. The socket's local address must be known. - The caller must set the property to the of the remote host from which the data is to be received. + The caller must set the property to the of the remote host from which the data is to be received. - The property on the `e` parameter provides the Window Sockets service provider with additional information about the read request. For more information about how to use this parameter, see . + The property on the `e` parameter provides the Window Sockets service provider with additional information about the read request. For more information about how to use this parameter, see . - The following properties and events on the object are required to successfully call this method: + The following properties and events on the object are required to successfully call this method: -- +- -- +- -- +- -- +- -- +- - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. + For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. - For byte stream–style sockets, incoming data is placed into the buffer until the buffer is filled, the connection is closed, or the internally buffered data is exhausted. The and properties determine where in the buffer the data is placed and the amount of data. + For byte stream–style sockets, incoming data is placed into the buffer until the buffer is filled, the connection is closed, or the internally buffered data is exhausted. The and properties determine where in the buffer the data is placed and the amount of data. ]]> @@ -6496,23 +6496,23 @@ ## Remarks The method is used primarily to receive message data on a connectionless socket. The socket's local address must be known. This method can only be used with datagram and raw sockets. The socket must be initialized with the socket type set to or before calling this method. This can be done when the socket is constructed using . - The caller must set the property to the of the remote host from which the data is to be received. + The caller must set the property to the of the remote host from which the data is to be received. - The following properties and events on the object are required to successfully call this method: + The following properties and events on the object are required to successfully call this method: -- +- -- +- -- +- -- +- -- +- - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. + For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. The method automatically sets the socket option to `true` the first time it is called for a given . However, the object will only be valid for packets which arrive at the local computer after the socket option has been set. If a socket is sent packets between when the socket is bound to a local endpoint (explicitly by the method or implicitly by one of the , , , or methods) and the first call to the method, calls to method will result in invalid objects for these packets. @@ -6603,9 +6603,9 @@ property gets the that contains the remote IP address and port number to which the is connected. If you are using a connectionless protocol, contains the default remote IP address and port number with which the will communicate. You must cast this to an before retrieving any information. You can then call the method to retrieve the remote , and the method to retrieve the remote port number. + If you are using a connection-oriented protocol, the property gets the that contains the remote IP address and port number to which the is connected. If you are using a connectionless protocol, contains the default remote IP address and port number with which the will communicate. You must cast this to an before retrieving any information. You can then call the method to retrieve the remote , and the method to retrieve the remote port number. - The is set after a call to either or . If you try to access this property earlier, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. + The is set after a call to either or . If you try to access this property earlier, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -6680,7 +6680,7 @@ > This method cannot detect certain kinds of connection problems, such as a broken network cable, or that the remote host was shut down ungracefully. You must attempt to send or receive data to detect these kinds of errors. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. @@ -6746,10 +6746,10 @@ If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -6815,10 +6815,10 @@ If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -6880,10 +6880,10 @@ If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call the method before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> You must ensure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> You must ensure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -6949,10 +6949,10 @@ If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -7016,10 +7016,10 @@ If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call the method before each call to the method. You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - With a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + With a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> You must ensure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> You must ensure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -7099,10 +7099,10 @@ If you are using a connectionless protocol and plan to send data to several different hosts, you should use the method. If you do not use the method, you will have to call before each call to . You can use even after you have established a default remote host with . You can also change the default remote host prior to calling by making another call to . - If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -7170,10 +7170,10 @@ You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . - If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -7268,10 +7268,10 @@ You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . - If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. + If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -7354,23 +7354,23 @@ The method starts an asynchronous send operation to the remote host established in the , , , , , or method. - The following properties and events on the object are required to successfully call this method: + The following properties and events on the object are required to successfully call this method: -- or +- or -- if is set +- if is set -- if is set +- if is set -- +- - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. The method will throw an exception if you do not first call , , , , or . Calling the method gives you the ability to send data within a separate execution thread. - For message-oriented sockets, do not exceed the maximum message size of the underlying Windows sockets service provider. If the data is too long to pass atomically through the underlying service provider, no data is transmitted and the method throws a with the set to the native Winsock WSAEMSGSIZE error code (10040). + For message-oriented sockets, do not exceed the maximum message size of the underlying Windows sockets service provider. If the data is too long to pass atomically through the underlying service provider, no data is transmitted and the method throws a with the set to the native Winsock WSAEMSGSIZE error code (10040). Note that the successful completion of the method does not indicate that the data was successfully delivered. @@ -7471,7 +7471,7 @@ If you are using a connection-oriented protocol, blocks until the file is sent. In nonblocking mode, may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -7543,7 +7543,7 @@ If you are using a connection-oriented protocol, blocks until the entire file is sent. In nonblocking mode, may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -7611,19 +7611,19 @@ ## Remarks The method is used to send a collection of files or in memory data buffers to remote host. The must already be connected to the remote host. - If a references a file in the working directory, it may be identified with just the name of the file; otherwise, the full path and name of the file must be specified. Wildcards and UNC share names are supported. If the file is not found, is thrown. + If a references a file in the working directory, it may be identified with just the name of the file; otherwise, the full path and name of the file must be specified. Wildcards and UNC share names are supported. If the file is not found, is thrown. - To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. + To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. - The property on the `e` parameter provides the Window Sockets service provider with additional information about the file transfer. For more information about how to use this parameter, see . + The property on the `e` parameter provides the Window Sockets service provider with additional information about the file transfer. For more information about how to use this parameter, see . - The following properties and events on the object are required to successfully call this method: + The following properties and events on the object are required to successfully call this method: -- +- -- +- - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. This method uses the TransmitPackets function found in the Windows Sockets 2 API. For more information about the TransmitPackets function and its flags, see the Windows Sockets documentation in the MSDN Library. @@ -7633,7 +7633,7 @@ On Windows client editions, the method is optimized for minimum memory and resource utilization. - Use of the flag in the property on the `e` parameter can deliver significant performance benefits. If the thread initiating the method call is being used for heavy computations, it is possible, though unlikely, that APCs could be prevented from launching. Note that there is a difference between kernel and user-mode APCs. Kernel APCs launch when a thread is in a wait state. User-mode APCs launch when a thread is in an alertable wait state + Use of the flag in the property on the `e` parameter can deliver significant performance benefits. If the thread initiating the method call is being used for heavy computations, it is possible, though unlikely, that APCs could be prevented from launching. Note that there is a difference between kernel and user-mode APCs. Kernel APCs launch when a thread is in a wait state. User-mode APCs launch when a thread is in an alertable wait state ]]> @@ -7733,10 +7733,10 @@ Blocking sockets will block until the all of the bytes in the buffer are sent. Since a nonblocking completes immediately, it might not send all of the bytes in the `buffer`. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends all of the bytes in the `buffer`. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. - If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -7807,10 +7807,10 @@ Blocking sockets will block until the requested all of the bytes in the `buffer` are sent. Since a nonblocking completes immediately, it might not send all of the bytes in the `buffer`. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends all of the bytes in the `buffer`. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. - If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -7883,10 +7883,10 @@ Blocking sockets will block until the requested number of bytes are sent. Since a nonblocking completes immediately, it might not send all of the bytes requested in a single operation. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. - If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -7962,10 +7962,10 @@ Blocking sockets will block until the requested number of bytes are sent. Since a non-blocking completes immediately, it might not send all of the bytes requested in a single operation. It is your applications responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of out-going data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. - If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -8046,31 +8046,31 @@ method starts an asynchronous send operation to the remote host specified in the property of the `e` parameter. Calling the method gives you the ability to send data within a separate execution thread. Although this method is intended for connectionless protocols, works with both connectionless and connection-oriented protocols. + The method starts an asynchronous send operation to the remote host specified in the property of the `e` parameter. Calling the method gives you the ability to send data within a separate execution thread. Although this method is intended for connectionless protocols, works with both connectionless and connection-oriented protocols. - To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. + To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. - The following properties and events on the object are required to successfully call this method: + The following properties and events on the object are required to successfully call this method: -- +- -- +- -- +- -- +- -- +- - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - If you are using a connection-oriented protocol, you must first call the , , , , , or method. Otherwise will throw a . When using a connection-oriented protocol, the method will ignore the property and send data to the established in the , , , , , or method. + If you are using a connection-oriented protocol, you must first call the , , , , , or method. Otherwise will throw a . When using a connection-oriented protocol, the method will ignore the property and send data to the established in the , , , , , or method. - If you are using a connectionless protocol, you do not need to establish a default remote host with the , , or method prior to calling . You only need to do this if you intend to call the or methods. If you do call the , , or method prior to calling , the property will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network IP address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network IP address and port number, you can use the property after the event is signaled and the associated delegates are called. + If you are using a connectionless protocol, you do not need to establish a default remote host with the , , or method prior to calling . You only need to do this if you intend to call the or methods. If you do call the , , or method prior to calling , the property will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network IP address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network IP address and port number, you can use the property after the event is signaled and the associated delegates are called. - If you want to send data to a broadcast address, you must first call the method and set the socket option for to true. You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . + If you want to send data to a broadcast address, you must first call the method and set the socket option for to true. You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . - If you specify the DontRoute flag in the property, the data you are sending will not be routed. + If you specify the DontRoute flag in the property, the data you are sending will not be routed. For message-oriented sockets, care must be taken not to exceed the maximum message size of the underlying transport. If the size of the buffer exceeds the maximum packet size of the underlying service provider, the datagram is not sent and will throw a . The successful completion of a method does not indicate that the data was successfully delivered. @@ -8172,7 +8172,7 @@ Listed below are the various options that can be set using this overload. These options are grouped by the appropriate value. If you intend to set any of these options, be sure to use the appropriate value for the `optionLevel` parameter. The option you choose to set must be specified in the `optionName` parameter. If you want to get the current value of any of the options listed, use the method. - options that can be set using this overload. + options that can be set using this overload. - @@ -8188,7 +8188,7 @@ - - options that can be set using this overload. + options that can be set using this overload. - @@ -8196,7 +8196,7 @@ - - options that can be set using this overload. + options that can be set using this overload. - @@ -8204,14 +8204,14 @@ - - options that can be set using this overload. + options that can be set using this overload. - For more information on these options, refer to the enumeration. > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. @@ -8266,7 +8266,7 @@ options determine the behavior of the current . Use this overload to set those options that require a byte array as an option value. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -8326,7 +8326,7 @@ Listed below are the various options that can be set using this overload. These options are grouped by the appropriate . If you intend to set any of these options, be sure to use the appropriate for the `optionLevel` parameter. The option you choose to set must be specified in the `optionName` parameter. If you want to get the current value of any of the options listed, use the method. - options that can be set using this overload. + options that can be set using this overload. - @@ -8352,7 +8352,7 @@ - - options that can be set using this overload. + options that can be set using this overload. - @@ -8370,7 +8370,7 @@ - - options that can be set using this overload. + options that can be set using this overload. - @@ -8378,20 +8378,20 @@ - - options that can be set using this overload. + options that can be set using this overload. - - - options that can be set using this overload. + options that can be set using this overload. - For more information about these options, refer to the enumeration. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -8450,7 +8450,7 @@ options determine the behavior of the current . Use this overload to set the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to get the current value of any of the options listed above, use the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. @@ -8526,7 +8526,7 @@ Setting `how` to disables both sends and receives as described above. > [!NOTE] -> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. +> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -8705,7 +8705,7 @@ Setting this property on a Transmission Control Protocol (TCP) socket is ignored by the TCP/IP stack if a successful connection has been established using the socket. - If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. + If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error. diff --git a/xml/System.Net.Sockets/SocketAsyncEventArgs.xml b/xml/System.Net.Sockets/SocketAsyncEventArgs.xml index c7650b1cf837c..fbe1b702739be 100644 --- a/xml/System.Net.Sockets/SocketAsyncEventArgs.xml +++ b/xml/System.Net.Sockets/SocketAsyncEventArgs.xml @@ -30,11 +30,11 @@ class is part of a set of enhancements to the class that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. This class was specifically designed for network server applications that require high performance. An application can use the enhanced asynchronous pattern exclusively or only in targeted hot areas (for example, when receiving large amounts of data). + The class is part of a set of enhancements to the class that provide an alternative asynchronous pattern that can be used by specialized high-performance socket applications. This class was specifically designed for network server applications that require high performance. An application can use the enhanced asynchronous pattern exclusively or only in targeted hot areas (for example, when receiving large amounts of data). - The main feature of these enhancements is the avoidance of the repeated allocation and synchronization of objects during high-volume asynchronous socket I/O. The Begin/End design pattern currently implemented by the class requires a object be allocated for each asynchronous socket operation. + The main feature of these enhancements is the avoidance of the repeated allocation and synchronization of objects during high-volume asynchronous socket I/O. The Begin/End design pattern currently implemented by the class requires a object be allocated for each asynchronous socket operation. - In the new class enhancements, asynchronous socket operations are described by reusable objects allocated and maintained by the application. High-performance socket applications know best the amount of overlapped socket operations that must be sustained. The application can create as many of the objects that it needs. For example, if a server application needs to have 15 socket accept operations outstanding at all times to support incoming client connection rates, it can allocate 15 reusable objects for that purpose. + In the new class enhancements, asynchronous socket operations are described by reusable objects allocated and maintained by the application. High-performance socket applications know best the amount of overlapped socket operations that must be sustained. The application can create as many of the objects that it needs. For example, if a server application needs to have 15 socket accept operations outstanding at all times to support incoming client connection rates, it can allocate 15 reusable objects for that purpose. The pattern for performing an asynchronous socket operation with this class consists of the following steps: @@ -97,7 +97,7 @@ - The property will be equal to . -- The property will be equal to , which specifies no flags will be used. +- The property will be equal to , which specifies no flags will be used. - The property will be equal to . @@ -144,7 +144,7 @@ that will be used for an asynchronous socket accept operation. Upon completion of the accept operation, it is the socket representing the accepted connection. If not supplied (set to null) before calling the method, a new socket will be created automatically and be accessible in the completion callback with this property. + This property can be used to provide an already created that will be used for an asynchronous socket accept operation. Upon completion of the accept operation, it is the socket representing the accepted connection. If not supplied (set to null) before calling the method, a new socket will be created automatically and be accessible in the completion callback with this property. ]]> @@ -182,7 +182,7 @@ ## Remarks This property gets the data buffer currently associated with the instance. To set the buffer, the method must be used. - This property is used with the , , , , , , and methods. + This property is used with the , , , , , , and methods. ]]> @@ -217,17 +217,17 @@ and methods. + This property is used with the and methods. - This property is used to provide multiple buffers of data to be sent or to provide multiple buffers in which to store received data for an asynchronous socket operation that can send or receive data. Multiple buffers using the property are supported by the and methods. + This property is used to provide multiple buffers of data to be sent or to provide multiple buffers in which to store received data for an asynchronous socket operation that can send or receive data. Multiple buffers using the property are supported by the and methods. - If the property is set to a non-null value, the property must be null and is ignored by the and methods. + If the property is set to a non-null value, the property must be null and is ignored by the and methods. If the was set to a non-null value and an attempt is made to set the property to a non-null value, an exception is thrown. - If the property is set to a non-null value, the and methods will throw an . + If the property is set to a non-null value, the and methods will throw an . - The parameter is ignored by the and methods. + The parameter is ignored by the and methods. ]]> @@ -265,7 +265,7 @@ ## Remarks This property provides the number of bytes transferred in an asynchronous socket operation that can receive or send data. If zero is returned from a read operation, the remote end has closed the connection. - This property is set by all asynchronous socket operations except the method. + This property is set by all asynchronous socket operations except the method. ]]> @@ -414,7 +414,7 @@ ## Remarks This property is set by calling the method. - This property is used with the , , , , , , and methods. + This property is used with the , , , , , , and methods. ]]> @@ -448,7 +448,7 @@ method. If true, a socket disconnected by the method can be reused after disconnect completion in subsequent socket accept or connect operations. + This property is used to alter the behavior of method. If true, a socket disconnected by the method can be reused after disconnect completion in subsequent socket accept or connect operations. ]]> @@ -564,13 +564,13 @@ object. The value of this property will be until the instance is used to begin an asynchronous socket operation. The property will then be set to the type of operation being performed in the methods that take the as a parameter. This property more easily facilitates using a single completion callback delegate for multiple kinds of asynchronous socket operations. + This property describes the asynchronous socket operation that was most recently completed using this object. The value of this property will be until the instance is used to begin an asynchronous socket operation. The property will then be set to the type of operation being performed in the methods that take the as a parameter. This property more easily facilitates using a single completion callback delegate for multiple kinds of asynchronous socket operations. This property remains valid in a instance until the instance is used for another asynchronous socket (xxxAsync) operation. This property is set by all asynchronous socket (xxxAsync) methods. - Calling an asynchronous socket method (xxxAsync) on the class sets this property value. This property is intended for use with the SocketAsyncCallback completion routine implemented by the application. + Calling an asynchronous socket method (xxxAsync) on the class sets this property value. This property is intended for use with the SocketAsyncCallback completion routine implemented by the application. ]]> @@ -609,7 +609,7 @@ This property does not apply to the property. - This property is used with the , , , , , , and methods. + This property is used with the , , , , , , and methods. ]]> @@ -651,7 +651,7 @@ An application that creates a class inheriting from can override this method to hook into this completion notification and clean up any resources that it allocated for the operation. The default implementation just raises the event. - This method is used to hook up an event handler to be used as the completion callback for a subsequent asynchronous socket operation. The caller must implement at least one callback delegate inherited from this method prior to starting an asynchronous socket operation using one of the asynchronous (xxxAsync) methods on the class. + This method is used to hook up an event handler to be used as the completion callback for a subsequent asynchronous socket operation. The caller must implement at least one callback delegate inherited from this method prior to starting an asynchronous socket operation using one of the asynchronous (xxxAsync) methods on the class. The caller's method provides a way for client applications to complete an asynchronous socket operation. A callback delegate must be implemented when an asynchronous socket operation is initiated. The completion callback delegate(s) inherited from the method must contain program logic to finish processing the asynchronous socket operation for the client. @@ -699,9 +699,9 @@ method. + This property provides information about a packet received using the method. - This property is used with the method. + This property is used with the method. ]]> @@ -736,11 +736,11 @@ method. This property can specify the remote endpoint to which to send data using method. This property can specify the remote endpoint from which data was received using the or methods. + This property specifies the remote endpoint. This property can specify the remote endpoint to which to connect using the method. This property can specify the remote endpoint to which to send data using method. This property can specify the remote endpoint from which data was received using the or methods. This remote endpoint specified by this property can include an IPv4 or IPv6 address. - This property is used with the , , , or methods. + This property is used with the , , , or methods. ]]> @@ -775,7 +775,7 @@ method. + The array of buffers can represent a file or files in memory or a set of memory data buffers. This property is used with the method. ]]> @@ -809,7 +809,7 @@ that are used by the method. + This property specifies the that are used by the method. ]]> @@ -849,7 +849,7 @@ property. This capability is useful for message protocols that place limitations on the size of individual send requests. + Set this property to zero to let the sockets layer select a default send size. Setting this property to 0xFFFFFFFF enables the caller to control the size and content of each send request, achieved by using the property. This capability is useful for message protocols that place limitations on the size of individual send requests. ]]> @@ -1034,7 +1034,7 @@ indicates successful completion of an operation. This property is primarily used in an application’s event handler routine. + This property provides the completion status of an asynchronous socket operation. A value of indicates successful completion of an operation. This property is primarily used in an application’s event handler routine. This property is used with all of the asynchronous socket (xxxAsync) methods. @@ -1081,9 +1081,9 @@ to be used for an asynchronous socket operation. + The property specifies the bitwise combination of the to be used for an asynchronous socket operation. - This property is used with the , , , and methods. + This property is used with the , , , and methods. ]]> diff --git a/xml/System.Net.Sockets/SocketAsyncOperation.xml b/xml/System.Net.Sockets/SocketAsyncOperation.xml index 23e1159cb29ad..2bba23116968d 100644 --- a/xml/System.Net.Sockets/SocketAsyncOperation.xml +++ b/xml/System.Net.Sockets/SocketAsyncOperation.xml @@ -25,9 +25,9 @@ object. The value of the property is set to None until the instance is used to begin an asynchronous socket operation. The property will then be set to the type of asynchronous operation being performed. This type more easily facilitates using a single completion callback delegate for multiple kinds of asynchronous socket operations. This type is intended for use in the SocketAsyncCallback completion routine. + This type describes the asynchronous socket operation that was most recently completed using a object. The value of the property is set to None until the instance is used to begin an asynchronous socket operation. The property will then be set to the type of asynchronous operation being performed. This type more easily facilitates using a single completion callback delegate for multiple kinds of asynchronous socket operations. This type is intended for use in the SocketAsyncCallback completion routine. - The type is used by the property. + The type is used by the property. ]]> diff --git a/xml/System.Net.Sockets/SocketInformation.xml b/xml/System.Net.Sockets/SocketInformation.xml index 002330ba783b6..3f69dbf8cb298 100644 --- a/xml/System.Net.Sockets/SocketInformation.xml +++ b/xml/System.Net.Sockets/SocketInformation.xml @@ -25,7 +25,7 @@ creates a instance for use with the constructor. + creates a instance for use with the constructor. ]]> diff --git a/xml/System.Net.Sockets/SocketOptionLevel.xml b/xml/System.Net.Sockets/SocketOptionLevel.xml index 14c99f318da45..e4f4078bfe82d 100644 --- a/xml/System.Net.Sockets/SocketOptionLevel.xml +++ b/xml/System.Net.Sockets/SocketOptionLevel.xml @@ -25,7 +25,7 @@ enumeration defines the socket option levels that can be passed to the and methods. enumerated values are grouped by . + The enumeration defines the socket option levels that can be passed to the and methods. enumerated values are grouped by . **Note** To use IPv6 on Windows XP, install Advance Networking Pack for Windows XP. diff --git a/xml/System.Net.Sockets/SocketOptionName.xml b/xml/System.Net.Sockets/SocketOptionName.xml index 1ac2b08f2c8af..7e2227497190c 100644 --- a/xml/System.Net.Sockets/SocketOptionName.xml +++ b/xml/System.Net.Sockets/SocketOptionName.xml @@ -25,7 +25,7 @@ enumeration defines the name of each configuration option. Sockets can be configured with the method. + The enumeration defines the name of each configuration option. Sockets can be configured with the method. diff --git a/xml/System.Net.Sockets/SocketShutdown.xml b/xml/System.Net.Sockets/SocketShutdown.xml index aa75116bfd30f..e02a3f72d49f2 100644 --- a/xml/System.Net.Sockets/SocketShutdown.xml +++ b/xml/System.Net.Sockets/SocketShutdown.xml @@ -25,7 +25,7 @@ enumeration defines the values that can be passed to the method. + The enumeration defines the values that can be passed to the method. ]]> diff --git a/xml/System.Net.Sockets/SocketType.xml b/xml/System.Net.Sockets/SocketType.xml index a52ffc3244c19..9ef9483f97793 100644 --- a/xml/System.Net.Sockets/SocketType.xml +++ b/xml/System.Net.Sockets/SocketType.xml @@ -28,12 +28,12 @@ Before a can send and receive data, it must first be created using an , a , and a . The enumeration provides several options for defining the type of that you intend to open. > [!NOTE] -> sometimes implicitly indicates which is used within an . For example, when the is , the is always . When the is , the is always . If you try to create a with an incompatible combination, throws a . +> sometimes implicitly indicates which is used within an . For example, when the is , the is always . When the is , the is always . If you try to create a with an incompatible combination, throws a . ## Examples - The following example uses as a parameter to the constructor. + The following example uses as a parameter to the constructor. [!code-cpp[SelectModeExample#1](~/samples/snippets/cpp/VS_Snippets_Remoting/SelectModeExample/CPP/source.cpp#1)] [!code-csharp[SelectModeExample#1](~/samples/snippets/csharp/VS_Snippets_Remoting/SelectModeExample/CS/source.cs#1)] diff --git a/xml/System.Net.Sockets/TcpClient.xml b/xml/System.Net.Sockets/TcpClient.xml index eb1f810de18e1..d08c01ce35af3 100644 --- a/xml/System.Net.Sockets/TcpClient.xml +++ b/xml/System.Net.Sockets/TcpClient.xml @@ -240,7 +240,7 @@ If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -328,7 +328,7 @@ ## Remarks is a way to determine whether data is queued for reading. If data is available, call to get the data. The available data is the total amount of data queued in the network buffer for reading. If no data is queued in the network buffer, returns 0. - If the remote host shuts down or closes the connection, may throw a . If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library) for a detailed description of the error. + If the remote host shuts down or closes the connection, may throw a . If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library) for a detailed description of the error. @@ -653,7 +653,7 @@ Call this method to establish a synchronous remote host connection to the specified . Before you call you must create an instance of the class using an IP address and a port number. Use this as the `remoteEP` parameter. The method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md) @@ -710,7 +710,7 @@ Call this method to establish a synchronous remote host connection to the specified and port number. The method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -769,7 +769,7 @@ This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. Call the method to establish a synchronous remote host connection to the host specified by the array of elements and the port number. The method will block until it either connects or fails. After connecting with the remote host, use the method to obtain the underlying . Use this to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library) for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library) for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -830,7 +830,7 @@ If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -895,7 +895,7 @@ Call this method to establish a synchronous remote host connection to the specified and port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -951,7 +951,7 @@ This method is typically used immediately after a call to the method, which can return multiple IP addresses for a single host. Call this method to establish a synchronous remote host connection to the host specified by the array of elements and the port number as an asynchronous operation. After connecting with the remote host, use the method to obtain the underlying . Use this to send and receive data. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library) for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library) for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -1010,7 +1010,7 @@ If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -1181,7 +1181,7 @@ This method blocks until the operation is complete. To perform this operation synchronously, use a method. > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library) for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library) for a detailed description of the error. @@ -1277,7 +1277,7 @@ . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. The class finalizer closes the TCP connection and releases all managed resources associated with the . These resources include the underlying used for connecting with the remote host, and the used to send and receive data. The finalizer does not release any unmanaged resources. @@ -1325,7 +1325,7 @@ > You must close the when you are through sending and receiving data. Closing does not release the . > [!NOTE] -> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -1481,7 +1481,7 @@ ## Remarks The property gets or sets the number of bytes that you are expecting to store in the receive buffer for each read operation. This property actually manipulates the network buffer space allocated for receiving incoming data. - Your network buffer should be at least as large as your application buffer to ensure that the desired data will be available when you call the method. Use the property to set this size. If your application will be receiving bulk data, you should pass the method a very large application buffer. + Your network buffer should be at least as large as your application buffer to ensure that the desired data will be available when you call the method. Use the property to set this size. If your application will be receiving bulk data, you should pass the method a very large application buffer. If the network buffer is smaller than the amount of data you request in the method, you will not be able to retrieve the desired amount of data in one read operation. This incurs the overhead of additional calls to the method. @@ -1576,7 +1576,7 @@ property gets or sets the number of bytes that you are expecting to send in each call to the method. This property actually manipulates the network buffer space allocated for send operation. + The property gets or sets the number of bytes that you are expecting to send in each call to the method. This property actually manipulates the network buffer space allocated for send operation. Your network buffer should be at least as large as your application buffer to ensure that the desired data will be stored and sent in one operation. Use the property to set this size. If your application will be sending bulk data, you should pass the method a very large application buffer. diff --git a/xml/System.Net.Sockets/TcpListener.xml b/xml/System.Net.Sockets/TcpListener.xml index a511d10c75961..f858a5257ee21 100644 --- a/xml/System.Net.Sockets/TcpListener.xml +++ b/xml/System.Net.Sockets/TcpListener.xml @@ -84,7 +84,7 @@ or constructors. + This constructor is obsolete. Use the or constructors. This constructor allows you to specify the port number on which to listen for incoming connection attempts. With this constructor, the underlying service provider assigns the most appropriate network address. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. If you use this approach, you can discover what local network address and port number has been assigned by using the property. @@ -136,7 +136,7 @@ ## Remarks This constructor allows you to specify the local IP address and port number on which to listen for incoming connection attempts. Before using this constructor, you must create an using the desired local IP address and port number. Pass this to the constructor as the `localEP` parameter. - If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. If you use this approach, you can discover what local network address and port number has been assigned by using the property. + If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. If you use this approach, you can discover what local network address and port number has been assigned by using the property. Call the method to begin listening for incoming connection attempts. @@ -189,7 +189,7 @@ using the desired local address. Pass this to the constructor as the `localaddr` parameter. If you do not care which local address is assigned, specify for the `localaddr` parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. If you use this approach, you can discover what local network address and port number has been assigned by using the property. + This constructor allows you to specify the local IP address and port number on which to listen for incoming connection attempts. Before calling this constructor you must first create an using the desired local address. Pass this to the constructor as the `localaddr` parameter. If you do not care which local address is assigned, specify for the `localaddr` parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 5000. If you use this approach, you can discover what local network address and port number has been assigned by using the property. Call the method to begin listening for incoming connection attempts. @@ -338,7 +338,7 @@ ## Remarks is a blocking method that returns a that you can use to send and receive data. Use the method to determine if connection requests are available in the incoming connection queue if you want to avoid blocking. - Use the method to obtain the underlying of the returned . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using . + Use the method to obtain the underlying of the returned . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -392,7 +392,7 @@ ## Remarks This operation will not block. The returned object will complete after the TCP connection has been accepted. - Use the method to obtain the underlying of the returned in the . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using or . + Use the method to obtain the underlying of the returned in the . The will provide you with methods for sending and receiving with the remote host. When you are through with the , be sure to call its method. If you want greater flexibility than a offers, consider using or . > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -529,7 +529,7 @@ > You can call the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -590,7 +590,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](~/docs/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously.md). > [!NOTE] -> If you receive a , use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -683,7 +683,7 @@ > You can call the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -746,7 +746,7 @@ > You can call the property of the underlying socket () to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -862,7 +862,7 @@ property to identify the local network interface and port number being used to listen for incoming client connection requests, after a socket connection has been made. You must first cast this to an . You can then call the property to retrieve the local IP address, and the property to retrieve the local port number. + You can use the property to identify the local network interface and port number being used to listen for incoming client connection requests, after a socket connection has been made. You must first cast this to an . You can then call the property to retrieve the local IP address, and the property to retrieve the local port number. @@ -1061,7 +1061,7 @@ Use the method to close the and stop listening. You are responsible for closing your accepted connections separately. > [!NOTE] -> Use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. +> Use the property to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library/](http://msdn.microsoft.com/library/) for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). diff --git a/xml/System.Net.Sockets/UdpClient.xml b/xml/System.Net.Sockets/UdpClient.xml index 47e6f7281074d..b7aef9dfa25a2 100644 --- a/xml/System.Net.Sockets/UdpClient.xml +++ b/xml/System.Net.Sockets/UdpClient.xml @@ -86,7 +86,7 @@ This constructor creates a new and allows the underlying service provider to assign the most appropriate local IPv4 address and port number. If this constructor is used, the instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. This constructor is not suitable for joining a multicast group because it does not perform socket binding. Also, it works only with IPv4 address types. @@ -136,7 +136,7 @@ This constructor creates an underlying and binds it to the port number from which you intend to communicate. Use this constructor if you are only interested in setting the local port number. The underlying service provider will assign the local IP address. If you pass 0 to the constructor, the underlying service provider will assign a port number. If this constructor is used, the instance is set with an address family of IPv4 that cannot be changed or overwritten by a connect method call with an IPv6 target. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. This constructor works only with IPv4 address types. @@ -189,7 +189,7 @@ If this constructor is used, the instance is set with the address family specified by the `localEP` parameter that cannot be changed or overwritten by a connect method call with a different address family. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. @@ -241,9 +241,9 @@ If this constructor is used, the instance is set with the address family specified by the `family` parameter that cannot be changed or overwritten by a connect method call with a different address family. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. - The is not suitable for joining a multicast group because it does not perform socket binding. + The is not suitable for joining a multicast group because it does not perform socket binding. ]]> @@ -290,7 +290,7 @@ If this constructor is used, the instance is set with the address family specified by the `family` parameter that cannot be changed or overwritten by a connect method call with a different address family. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. @@ -343,7 +343,7 @@ This constructor initializes a new and establishes a remote host using the `hostname` and `port` parameters. Establishing a default remote host is optional. If you use this constructor, you do not have to specify a remote host in each call to the method. Specifying a default remote host limits you to that host only. You can change the default remote host at any time by calling the method. If you want to specify a remote host in your call to the method, do not use this constructor. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. @@ -476,7 +476,7 @@ If the remote host shuts down or closes the connection, the property throws a . > [!NOTE] -> If you receive a , use to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library)/ for a detailed description of the error. +> If you receive a , use to obtain the specific error code and refer to the Windows Sockets version 2 API error code documentation in the MSDN library at [http://msdn.microsoft.com/library](http://msdn.microsoft.com/library)/ for a detailed description of the error. @@ -802,7 +802,7 @@ The disables the underlying and releases all managed and unmanaged resources associated with the . > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. @@ -851,11 +851,11 @@ ## Remarks The method establishes a default remote host using the value specified in the `endPoint` parameter. Once established, you do not have to specify a remote host in each call to the method. - Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. + Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the Client method to obtain the underlying , and set the socket option to . + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the Client method to obtain the underlying , and set the socket option to . - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. > [!NOTE] > Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. @@ -912,11 +912,11 @@ ## Remarks The method establishes a default remote host using the values specified in the `addr` and `port` parameters. Once established, you do not have to specify a remote host in each call to the method. - Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. + Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. > [!NOTE] > Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. @@ -978,11 +978,11 @@ Establishing a default remote host is optional. Specifying a default remote host limits you to that host only. If you want to send datagrams to a different remote host, you must make another call to the method or create another without a default remote host. - If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. + If you have established a default remote host and you also provide a remote host in your call to the method, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. - If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . + If you call the method, any datagrams that arrive from an address other than the specified default will be discarded. You cannot set the default remote host to a broadcast address using this method unless you inherit from , use the client method to obtain the underlying , and set the socket option to . - You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. + You can however, broadcast data to the default broadcast address, 255.255.255.255, if you specify in your call to the method. If your application requires greater control over broadcast addresses, you can also revert to using the class. > [!NOTE] > Since the UDP protocol is connectionless, the method does not block. Do not call the method if you intend to receive multicasted datagrams. @@ -1159,7 +1159,7 @@ The method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. > [!NOTE] -> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. @@ -1216,7 +1216,7 @@ The method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. @@ -1426,7 +1426,7 @@ ## Remarks By default, multiple clients can use a specific port; however, only one of the clients can perform operations on the network traffic sent to the port. You can use the property to prevent multiple clients from using a specific port. - This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the constructor, and you cannot subsequently set the property + This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the constructor, and you cannot subsequently set the property @@ -1493,7 +1493,7 @@ method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . + The method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . > [!NOTE] > You must create the using the multicast port number; otherwise, you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method, or the method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. @@ -1566,7 +1566,7 @@ > There are several multicast address ranges to choose from. Refer to the IETF RFC 2375. > [!NOTE] -> You cannot call on a constructed without a specific local port (that is, using the or constructor). +> You cannot call on a constructed without a specific local port (that is, using the or constructor). @@ -1615,7 +1615,7 @@ method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. The `timeToLive` parameter specifies how many router hops will be allowed for a multicasted datagram before being discarded. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . + The method subscribes the to a multicast group using the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router requesting membership to the multicast group. The multicast address range is 224.0.0.0 to 239.255.255.255. If you specify an address outside this range or if the router to which the request is made is not multicast enabled, will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. The `timeToLive` parameter specifies how many router hops will be allowed for a multicasted datagram before being discarded. Once the is listed with the router as a member of the multicast group, it will be able to receive multicasted datagrams sent to the specified . > [!NOTE] > You must create the using the multicast port number otherwise you will not be able to receive multicasted datagrams. Do not call the method prior to calling the method or the receive method will not work. You do not need to belong to a multicast group to send datagrams to a multicast IP address. @@ -1782,7 +1782,7 @@ If you specify a default remote host in the method, the method will accept datagrams from that host only. All other datagrams will be discarded. - If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. + If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!NOTE] > If you intend to receive multicasted datagrams, do not call the method prior to calling the method. The you use to receive datagrams must be created using the multicast port number. @@ -1838,7 +1838,7 @@ If you specify a default remote host in the method, this method will accept datagrams from that host only. All other datagrams will be discarded. - If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. + If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. > [!WARNING] > If you intend to receive multicasted datagrams, do not call the method prior to calling this method. The you use to receive datagrams must be created using the multicast port number. @@ -1883,7 +1883,7 @@ method and returns the number of bytes sent. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. + This overload sends datagrams to the remote host established in the method and returns the number of bytes sent. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. @@ -1941,12 +1941,12 @@ method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to the method as the `endPoint` parameter. + The method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to the method as the `endPoint` parameter. - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. > [!NOTE] -> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. @@ -2008,10 +2008,10 @@ ## Remarks The method sends datagrams to the values specified by the `hostname` and `port` parameters and returns the number of bytes successfully sent. You can send datagrams to the default broadcast address by specifying "255.255.255.255" for the `hostname` parameter value. - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. > [!NOTE] -> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. @@ -2065,7 +2065,7 @@ method. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. + This overload sends datagrams to the remote host established in the method. If you do not call before calling this overload, the method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. If you want to send datagrams to a different remote host, you must call the method and specify the desired remote host. Use either of the other method overloads to send datagrams to a broadcast address. @@ -2115,12 +2115,12 @@ using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to this method as the `endPoint` parameter. + This method sends datagrams to the specified endpoint. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to this method as the `endPoint` parameter. - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. > [!WARNING] -> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> Do not provide an `endPoint` parameter to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. ]]> @@ -2174,10 +2174,10 @@ ## Remarks This method sends datagrams to the values specified by the `hostname` and `port` parameters. You can send datagrams to the default broadcast address by specifying "255.255.255.255" for the `hostname` parameter value. - If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. + If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. > [!WARNING] -> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. +> Do not provide a host name or port number to this method if you have already established a remote host with the method. If you do, this method will throw a . If you receive a , use to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Sockets version 2 API error code documentation in MSDN for a detailed description of the error. ]]> diff --git a/xml/System.Net/AuthenticationManager.xml b/xml/System.Net/AuthenticationManager.xml index c298eb381f1ee..7b1f27573908e 100644 --- a/xml/System.Net/AuthenticationManager.xml +++ b/xml/System.Net/AuthenticationManager.xml @@ -27,7 +27,7 @@ ## Remarks is a static class that manages the authentication modules that an application uses. When a request is made to protected resources, the calls the method to get an instance to use in subsequent requests. - The queries each registered authentication module by calling the method for each module. The first authentication module to return an instance is used to authenticate the request. + The queries each registered authentication module by calling the method for each module. The first authentication module to return an instance is used to authenticate the request. Modules that provide the basic, digest, negotiate, NTLM, and Kerberos authentication types are registered with the by default. Additional authentication modules that implement the interface can be added using the method. Authentication modules are called in the order in which they were added to the list. @@ -81,7 +81,7 @@ method calls the method on each registered authentication module until one of the module responds with an instance. + The method calls the method on each registered authentication module until one of the module responds with an instance. The first instance returned is used to authenticate the request. If no authentication module can authenticate the request, the method returns `null`. @@ -178,7 +178,7 @@ to in your request. + An SPN is a name by which a client uniquely identifies an instance of a service or application on a server for purposes of mutual authentication. Mutual authentication is requested by default, and you can require it by setting to in your request. When a requires mutual authentication, the SPN for the destination must be supplied by the client. If you know the SPN, you can add it to the before sending the request. If you have not added SPN information to this dictionary, the uses the method to compose the most likely SPN; however, this is a computed value and might be incorrect. If mutual authentication is attempted and fails, you can check the dictionary to determine the computed SPN. No SPN is entered into the dictionary if the authentication protocol does not support mutual authentication. @@ -190,7 +190,7 @@ > [!NOTE] > When Kerberos authentication is performed through a proxy, both the proxy and the ultimate host name need to be resolved to an SPN. The proxy name resolution is protected by a timeout. Resolution of the ultimate host name to a SPN requires a DNS lookup, and there is no timeout associated directly with this operation. Therefore synchronous operations may take longer to timeout. To overcome this, add the ultimate host's URI prefix to the SPN cache prior to making requests to it. - Version 3.5 SP1 now defaults to specifying the host name used in the request URL in the SPN in the NTLM (NT LAN Manager) authentication exchange when the property is not set. The host name used in the request URL may be different from the Host header specified in the in the client request. The host name used in the request URL may be different from the actual host name of the server, the machine name of the server, the computer's IP address, or the loopback address. In these cases, Windows will fail the authentication request. To address the issue, you may need to notify Windows that the host name used in the request URL in the client request ("contoso", for example) is actually an alternate name for the local computer. + Version 3.5 SP1 now defaults to specifying the host name used in the request URL in the SPN in the NTLM (NT LAN Manager) authentication exchange when the property is not set. The host name used in the request URL may be different from the Host header specified in the in the client request. The host name used in the request URL may be different from the actual host name of the server, the machine name of the server, the computer's IP address, or the loopback address. In these cases, Windows will fail the authentication request. To address the issue, you may need to notify Windows that the host name used in the request URL in the client request ("contoso", for example) is actually an alternate name for the local computer. @@ -240,7 +240,7 @@ ## Remarks If the authentication module can preauthenticate the request, the method returns an Authentication instance and sends the authorization information to the server preemptively instead of waiting for the resource to issue a challenge. This behavior is outlined in section 3.3 of RFC 2617 (HTTP Authentication: Basic and Digest Access Authentication). Authentication modules that support preauthentication allow clients to improve server efficiency by avoiding extra round trips caused by authentication challenges. - Authorization modules that can preauthenticate requests set the property to `true`. + Authorization modules that can preauthenticate requests set the property to `true`. ]]> diff --git a/xml/System.Net/BindIPEndPoint.xml b/xml/System.Net/BindIPEndPoint.xml index 93a3377cfbb1c..45c377a617d47 100644 --- a/xml/System.Net/BindIPEndPoint.xml +++ b/xml/System.Net/BindIPEndPoint.xml @@ -36,9 +36,9 @@ delegate is used by a by setting the property with the delegate as an argument. This delegate should specify a local IP address and port number in the returned . + Specify that the delegate is used by a by setting the property with the delegate as an argument. This delegate should specify a local IP address and port number in the returned . - If the .NET Framework cannot bind the returned to the after attempts, an is thrown. + If the .NET Framework cannot bind the returned to the after attempts, an is thrown. If you want the delegate to give the service point control of the connection binding, the delegate should return `null`. If you want to abort the connection, the delegate must throw an exception. diff --git a/xml/System.Net/Dns.xml b/xml/System.Net/Dns.xml index 65b93fac42262..dfe4c4d07978c 100644 --- a/xml/System.Net/Dns.xml +++ b/xml/System.Net/Dns.xml @@ -443,7 +443,7 @@ To perform this operation synchronously, use the method. - If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -540,7 +540,7 @@ ## Remarks This method blocks until the operation is complete. - If the is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the is set to `true`, the property of the instance returned is not populated by this method and will always be empty. To perform this operation synchronously, use the method. @@ -824,7 +824,7 @@ For asynchronous access to DNS information, use the and methods. - If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -1196,7 +1196,7 @@ When `hostName` is a DNS-style host name associated with multiple IP addresses, only the first IP address that resolves to that host name is returned. - If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). diff --git a/xml/System.Net/DownloadProgressChangedEventHandler.xml b/xml/System.Net/DownloadProgressChangedEventHandler.xml index 71e8a3916d5e4..928c3ff02b801 100644 --- a/xml/System.Net/DownloadProgressChangedEventHandler.xml +++ b/xml/System.Net/DownloadProgressChangedEventHandler.xml @@ -41,7 +41,7 @@ ## Examples - The following code example demonstrates setting an event handler for the event. + The following code example demonstrates setting an event handler for the event. [!code-cpp[NCLWebClientAsync#19](~/samples/snippets/cpp/VS_Snippets_Remoting/NCLWebClientAsync/CPP/asyncmethods.cpp#19)] [!code-csharp[NCLWebClientAsync#19](~/samples/snippets/csharp/VS_Snippets_Remoting/NCLWebClientAsync/CS/asyncmethods.cs#19)] diff --git a/xml/System.Net/FileWebRequest.xml b/xml/System.Net/FileWebRequest.xml index 965713ab5ed83..4a522c9d5aac3 100644 --- a/xml/System.Net/FileWebRequest.xml +++ b/xml/System.Net/FileWebRequest.xml @@ -31,7 +31,7 @@ ## Remarks The class implements the `abstract` base class for Uniform Resource Identifiers (URIs) that use the `file://` scheme to request local files. - Do not use the constructor. Use the method to initialize new instances of the class. If the URI scheme is `file://`, the method returns a object. + Do not use the constructor. Use the method to initialize new instances of the class. If the URI scheme is `file://`, the method returns a object. The method makes a synchronous request for the file specified in the property and returns a object that contains the response. You can make an asynchronous request for the file using the and methods. diff --git a/xml/System.Net/FileWebResponse.xml b/xml/System.Net/FileWebResponse.xml index 1d24a85851c17..2339b3d975dd6 100644 --- a/xml/System.Net/FileWebResponse.xml +++ b/xml/System.Net/FileWebResponse.xml @@ -110,10 +110,10 @@ method cleans up the resources used by a and closes the response stream by calling the method. + The method cleans up the resources used by a and closes the response stream by calling the method. > [!NOTE] -> The response stream must be closed to avoid running out of system resources. You can closes the response stream by calling either or +> The response stream must be closed to avoid running out of system resources. You can closes the response stream by calling either or @@ -285,7 +285,7 @@ The method returns the data stream from the file system resource. > [!NOTE] -> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or +> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or diff --git a/xml/System.Net/FtpWebRequest.xml b/xml/System.Net/FtpWebRequest.xml index 93a099c25b360..38254fdad3cc5 100644 --- a/xml/System.Net/FtpWebRequest.xml +++ b/xml/System.Net/FtpWebRequest.xml @@ -1068,7 +1068,7 @@ property identifies the instance that communicates with the FTP server. The proxy is set by the system by using configuration files and the Internet Explorer Local Area Network settings. To specify that no proxy should be used, set to the proxy instance returned by the method. For more information about automatic proxy detection, see [Automatic Proxy Detection](~/docs/framework/network-programming/automatic-proxy-detection.md). + The property identifies the instance that communicates with the FTP server. The proxy is set by the system by using configuration files and the Internet Explorer Local Area Network settings. To specify that no proxy should be used, set to the proxy instance returned by the method. For more information about automatic proxy detection, see [Automatic Proxy Detection](~/docs/framework/network-programming/automatic-proxy-detection.md). You must set before writing data to the request's stream or getting the response. Changing after calling the , , , or method causes an exception. diff --git a/xml/System.Net/GlobalProxySelection.xml b/xml/System.Net/GlobalProxySelection.xml index a48eb10fe091b..cdcf419a1d617 100644 --- a/xml/System.Net/GlobalProxySelection.xml +++ b/xml/System.Net/GlobalProxySelection.xml @@ -30,7 +30,7 @@ stores the proxy settings for the default proxy that instances use to contact Internet sites beyond the local network. The default proxy setting is initialized from the global or application configuration file, and can be overridden for individual requests or disabled by setting the property to the result of the method. + The stores the proxy settings for the default proxy that instances use to contact Internet sites beyond the local network. The default proxy setting is initialized from the global or application configuration file, and can be overridden for individual requests or disabled by setting the property to the result of the method. The proxy settings stored in are used by any derived objects that support proxies and have their property value set to `null` (the default). Proxies are currently supported by , , and . diff --git a/xml/System.Net/HttpContinueDelegate.xml b/xml/System.Net/HttpContinueDelegate.xml index 6cd0d93483da5..6dc6bbd2f8f94 100644 --- a/xml/System.Net/HttpContinueDelegate.xml +++ b/xml/System.Net/HttpContinueDelegate.xml @@ -33,12 +33,12 @@ to specify the callback method to be called when an HTTP 100-continue response is received from the server. When set, the delegate is called whenever the first protocol response of type is received. This is a change from the behavior of the version 1.1 Framework. + Use to specify the callback method to be called when an HTTP 100-continue response is received from the server. When set, the delegate is called whenever the first protocol response of type is received. This is a change from the behavior of the version 1.1 Framework. Your event handler must declare the same parameters as the . > [!NOTE] -> `StatusCode` is always . +> `StatusCode` is always . This is useful when the client wants to display the status of data being received from the server. diff --git a/xml/System.Net/HttpListener.xml b/xml/System.Net/HttpListener.xml index bb775625e6c9b..fe37cf07c638d 100644 --- a/xml/System.Net/HttpListener.xml +++ b/xml/System.Net/HttpListener.xml @@ -48,7 +48,7 @@ In the more complex asynchronous model, your application does not block while waiting for requests and each request is processed in its own execution thread. Use the method to specify an application-defined method to be called for each incoming request. Within that method, call the method to obtain the request, process it, and respond. - In either model, incoming requests are accessed using the property and are represented by objects. Similarly, responses are accessed using the property and are represented by objects. These objects share some functionality with the and objects, but the latter objects cannot be used in conjunction with because they implement client, not server, behaviors. + In either model, incoming requests are accessed using the property and are represented by objects. Similarly, responses are accessed using the property and are represented by objects. These objects share some functionality with the and objects, but the latter objects cannot be used in conjunction with because they implement client, not server, behaviors. An can require client authentication. You can either specify a particular scheme to use for authentication, or you can specify a delegate that determines the scheme to use. You must require some form of authentication to obtain information about the client's identity. For additional information, see the , , and properties. @@ -190,7 +190,7 @@ ## Remarks The uses the specified scheme to authenticate all incoming requests. The and methods return an incoming client request only if the successfully authenticates the request. - You can interrogate the identity of a successfully authenticated client by using the property. + You can interrogate the identity of a successfully authenticated client by using the property. If you want an object to use different authentication mechanisms based on characteristics of the requests it receives (for example, the request's or property), you must implement a method that chooses the authentication scheme. For instructions about how to do this, see the property documentation. @@ -241,7 +241,7 @@ > [!NOTE] > If you want the same authentication protocol to be used for all requests handled by a particular instance of , you do not need to set this property. To specify a protocol to be used for all client requests, use the property. - If the client has not specified authentication information in its headers, the calls the specified delegate for each unauthenticated incoming request to determine which, if any, protocol to use to authenticate the client. The and methods return an incoming request only if the successfully authenticated the request. If a request cannot be authenticated, the automatically sends back a 401 response. You can get the identity of a successfully authenticated client using the property. + If the client has not specified authentication information in its headers, the calls the specified delegate for each unauthenticated incoming request to determine which, if any, protocol to use to authenticate the client. The and methods return an incoming request only if the successfully authenticated the request. If a request cannot be authenticated, the automatically sends back a 401 response. You can get the identity of a successfully authenticated client using the property. The ability to delegate the choice of authentication protocol to an application-specific method is useful if you want an instance of to use different authentication protocols depending on the characteristics of the requests it receives (for example, the request's or property). diff --git a/xml/System.Net/HttpListenerContext.xml b/xml/System.Net/HttpListenerContext.xml index 3869d53d4e763..3e804a061accd 100644 --- a/xml/System.Net/HttpListenerContext.xml +++ b/xml/System.Net/HttpListenerContext.xml @@ -403,7 +403,7 @@ ## Remarks An indicates that it requires authentication using the property or by specifying an delegate using the property. - To determine the client's login name and authentication information, check the property in the object returned by this property. + To determine the client's login name and authentication information, check the property in the object returned by this property. diff --git a/xml/System.Net/HttpListenerRequest.xml b/xml/System.Net/HttpListenerRequest.xml index 0f344611a1172..ebfb398104a9e 100644 --- a/xml/System.Net/HttpListenerRequest.xml +++ b/xml/System.Net/HttpListenerRequest.xml @@ -25,7 +25,7 @@ object, the provides a object that contains information about the sender, the request, and the response that is sent to the client. The property returns the object that describes the request. + When a client makes a request to a Uniform Resource Identifier (URI) handled by an object, the provides a object that contains information about the sender, the request, and the response that is sent to the client. The property returns the object that describes the request. The object contains information about the request, such as the request string, string, and request body data (see the property). @@ -193,7 +193,7 @@ object can be used to convert byte sequences into character sets (code pages) and characters into byte sequences. This property uses the charset value from the `Content-Type` header to determine the encoding. If that information is not available, this property returns . + An object can be used to convert byte sequences into character sets (code pages) and characters into byte sequences. This property uses the charset value from the `Content-Type` header to determine the encoding. If that information is not available, this property returns . @@ -1176,7 +1176,7 @@ The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. - When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. + When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. The `http.sys` service exposes two request URI strings: @@ -1184,7 +1184,7 @@ - Converted URI - The raw URI is the provided in the request line of a HTTP request: + The raw URI is the provided in the request line of a HTTP request: `GET /path/` @@ -1196,7 +1196,7 @@ `http://www.contoso.com/path/` - The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: + The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: - Un-escapes all percent encoded values. diff --git a/xml/System.Net/HttpListenerResponse.xml b/xml/System.Net/HttpListenerResponse.xml index 6ae2db6721f63..1f7e0befc3abd 100644 --- a/xml/System.Net/HttpListenerResponse.xml +++ b/xml/System.Net/HttpListenerResponse.xml @@ -29,9 +29,9 @@ object, the request and response are made available to your application in an object. The request is represented by an object and is available in the property. The response is represented by an object and is available in the property. + When a client makes a request for a resource handled by an object, the request and response are made available to your application in an object. The request is represented by an object and is available in the property. The response is represented by an object and is available in the property. - You can customize the response by setting various properties, such as , , and . Use the property to obtain a instance to which response data can be written. Finally, send the response data to the client by calling the method. + You can customize the response by setting various properties, such as , , and . Use the property to obtain a instance to which response data can be written. Finally, send the response data to the client by calling the method. diff --git a/xml/System.Net/HttpStatusCode.xml b/xml/System.Net/HttpStatusCode.xml index 09054cb5243d9..a0b128de6da8c 100644 --- a/xml/System.Net/HttpStatusCode.xml +++ b/xml/System.Net/HttpStatusCode.xml @@ -29,7 +29,7 @@ ## Remarks The enumeration contains the values of the status codes defined in RFC 2616 for HTTP 1.1. - The status of an HTTP request is contained in the property. + The status of an HTTP request is contained in the property. @@ -102,7 +102,7 @@ property is `false`, Ambiguous will cause an exception to be thrown. + If the property is `false`, Ambiguous will cause an exception to be thrown. Ambiguous is a synonym for MultipleChoices. @@ -336,7 +336,7 @@ property is `false`, Found will cause an exception to be thrown. + If the property is `false`, Found will cause an exception to be thrown. Found is a synonym for Redirect. @@ -614,7 +614,7 @@ property is `false`, MultipleChoices will cause an exception to be thrown. + If the property is `false`, MultipleChoices will cause an exception to be thrown. MultipleChoices is a synonym for Ambiguous. @@ -960,7 +960,7 @@ property is `false`, Redirect will cause an exception to be thrown. + If the property is `false`, Redirect will cause an exception to be thrown. Redirect is a synonym for Found. @@ -998,7 +998,7 @@ property is `false`, RedirectKeepVerb will cause an exception to be thrown. + If the property is `false`, RedirectKeepVerb will cause an exception to be thrown. RedirectKeepVerb is a synonym for TemporaryRedirect. @@ -1036,7 +1036,7 @@ property is `false`, RedirectMethod will cause an exception to be thrown. + If the property is `false`, RedirectMethod will cause an exception to be thrown. RedirectMethod is a synonym for SeeOther. @@ -1214,7 +1214,7 @@ property is `false`, SeeOther will cause an exception to be thrown. + If the property is `false`, SeeOther will cause an exception to be thrown. SeeOther is a synonym for RedirectMethod. @@ -1308,7 +1308,7 @@ property is `false`, TemporaryRedirect will cause an exception to be thrown. + If the property is `false`, TemporaryRedirect will cause an exception to be thrown. TemporaryRedirect is a synonym for RedirectKeepVerb. diff --git a/xml/System.Net/HttpWebRequest.xml b/xml/System.Net/HttpWebRequest.xml index a57da4a53ebc0..df819e7046132 100644 --- a/xml/System.Net/HttpWebRequest.xml +++ b/xml/System.Net/HttpWebRequest.xml @@ -32,7 +32,7 @@ ## Remarks The class provides support for the properties and methods defined in and for additional properties and methods that enable the user to interact directly with servers using HTTP. - Do not use the constructor. Use the method to initialize new objects. If the scheme for the Uniform Resource Identifier (URI) is `http://` or `https://`, returns an object. + Do not use the constructor. Use the method to initialize new objects. If the scheme for the Uniform Resource Identifier (URI) is `http://` or `https://`, returns an object. The method makes a synchronous request to the resource specified in the property and returns an that contains the response object. The response data can be received by using the stream returned by . If the response object or the response stream is closed, remaining data will be forfeited. The remaining data will be drained and the socket will be re-used for subsequent requests when closing the response object or stream if the following conditions hold: it's a keep-alive or pipelined request, only a small amount of data needs to be received, or the remaining data is received in a small time interval. If none of the mentioned conditions hold or the drain time is exceeded, the socket will be closed. For keep-alive or pipelined connections, we strongly recommend that the application reads the streams until EOF. This ensures that the socket will be re-used for subsequent requests resulting in better performance and less resources used. @@ -40,7 +40,7 @@ For client authentication with , the client certificate must be installed in the My certificate store of the current user. - The class throws a when errors occur while accessing a resource. The property contains a value that indicates the source of the error. When is , the property contains the received from the resource. + The class throws a when errors occur while accessing a resource. The property contains a value that indicates the source of the error. When is , the property contains the received from the resource. exposes common HTTP header values sent to the Internet resource as properties, set by methods, or set by the system; the following table contains a complete list. You can set other headers in the property as name/value pairs. Note that servers and caches may change or add headers during the request. @@ -62,7 +62,7 @@ |User-Agent|Set by the property.| > [!NOTE] -> is registered automatically. You do not need to call the method to register before using URIs beginning with `http://` or `https://`. +> is registered automatically. You do not need to call the method to register before using URIs beginning with `http://` or `https://`. The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet Explorer on the local computer. If there are no proxy settings in Internet Explorer, the request is sent directly to the server. @@ -322,7 +322,7 @@ method adds a byte range header to the request. + The method adds a byte range header to the request. If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. @@ -396,7 +396,7 @@ method adds a byte range header to the request. + The method adds a byte range header to the request. If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. @@ -462,7 +462,7 @@ method adds a byte range header to the request. + The method adds a byte range header to the request. Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. @@ -540,7 +540,7 @@ method adds a byte range header to the request. + The method adds a byte range header to the request. Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. @@ -608,7 +608,7 @@ method adds a Range header to the request. + The method adds a Range header to the request. If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. @@ -678,7 +678,7 @@ method adds a Range header to the request. + The method adds a Range header to the request. If `range` is positive, the `range` parameter specifies the starting point of the range. The server should start sending data from the `range` parameter specified to the end of the data in the HTTP entity. @@ -750,7 +750,7 @@ method adds a Range header to the request. + The method adds a Range header to the request. Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. @@ -826,7 +826,7 @@ method adds a Range header to the request. + The method adds a Range header to the request. Since all HTTP entities are represented in HTTP messages as sequences of bytes, the concept of a byte range is meaningful for any HTTP entity. However, not all clients and servers need to support byte-range operations. @@ -945,7 +945,7 @@ If is set to `false`, all responses with an HTTP status code from 300 to 399 is returned to the application. - The Authorization header is cleared on auto-redirects and automatically tries to re-authenticate to the redirected location. In practice, this means that an application can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the application must implement and register a custom authentication module. The and related class are used to implement a custom authentication module. The method registers a custom authentication module. + The Authorization header is cleared on auto-redirects and automatically tries to re-authenticate to the redirected location. In practice, this means that an application can't put custom authentication information into the Authorization header if it is possible to encounter redirection. Instead, the application must implement and register a custom authentication module. The and related class are used to implement a custom authentication module. The method registers a custom authentication module. @@ -1505,7 +1505,7 @@ ## Remarks The property specifies the callback method to call when the client receives a 100-Continue response. - When the property is set, the client calls the delegate whenever protocol responses of type (100) are received. This is useful if you want the client to display the status of the data being received from the Internet resource. + When the property is set, the client calls the delegate whenever protocol responses of type (100) are received. This is useful if you want the client to display the status of the data being received from the Internet resource. ]]> @@ -1683,20 +1683,20 @@ . + If the Date header is `null`, then the return value will be set to . - The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). + The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). The classes in the namespace always write it out the property on the wire during transmission in standard form using GMT (Utc) format. - If the property is set to , then the `Date` HTTP header is removed from the property and the . + If the property is set to , then the `Date` HTTP header is removed from the property and the . - If the property is , this indicates that the `Date` HTTP header is not included in the property and the . + If the property is , this indicates that the `Date` HTTP header is not included in the property and the . > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - If the is set and an attempt is made to send a with no body, then a will be thrown by the , , and methods. + If the is set and an attempt is made to send a with no body, then a will be thrown by the , , and methods. ]]> @@ -1736,7 +1736,7 @@ ## Remarks Setting this property registers the specified policy for the HTTP and HTTPS schemes. This policy is used for this request if: - There is no property specified for this request. + There is no property specified for this request. \- or - @@ -1859,13 +1859,13 @@ method completes an asynchronous request for a stream that was started by the method. After the object has been returned, you can send data with the by using the method. + The method completes an asynchronous request for a stream that was started by the method. After the object has been returned, you can send data with the by using the method. > [!NOTE] > You must set the value of the property before writing data to the stream. > [!CAUTION] -> You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. +> You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -1929,7 +1929,7 @@ method completes an asynchronous request for a stream that was started by the method and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. + The method completes an asynchronous request for a stream that was started by the method and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. @@ -1937,7 +1937,7 @@ > If an application needs to set the value of the property, then this must be done before retrieving the stream and writing data to it. > [!CAUTION] -> You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. +> You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -2132,11 +2132,11 @@ method returns a stream to use to send data for the . After the object has been returned, you can send data with the by using the method. + The method returns a stream to use to send data for the . After the object has been returned, you can send data with the by using the method. If an application needs to set the value of the property, then this must be done before retrieving the stream. - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. + You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > [!NOTE] > Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. @@ -2216,13 +2216,13 @@ method returns a stream to use to send data for the and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. + The method returns a stream to use to send data for the and outputs the associated with the stream. After the object has been returned, you can send data with the by using the method. Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. If an application needs to set the value of the property, then this must be done before retrieving the stream. - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. + You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > [!NOTE] > Your application cannot mix synchronous and asynchronous methods for a particular request. If you call the method, you must use the method to retrieve the response. @@ -2531,13 +2531,13 @@ property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). + The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). The classes in the namespace always write it out the property on the wire during transmission in standard form using GMT (Utc) format. - If the property is set to , then the `If-Modified-Since` HTTP header is removed from the property and the . + If the property is set to , then the `If-Modified-Since` HTTP header is removed from the property and the . - If the property is , this indicates that the `If-Modified-Since` HTTP header is not included in the property and the . + If the property is , this indicates that the `If-Modified-Since` HTTP header is not included in the property and the . > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -2999,7 +2999,7 @@ property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. + The property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet Explorer on the local computer. If there are no proxy settings in Internet Explorer, the request is sent directly to the server. @@ -3157,7 +3157,7 @@ object passed to by the call to . + The object passed to by the call to . Following a redirection header does not change the property. To get the actual URI that responded to the request, examine the property. @@ -3283,7 +3283,7 @@ property may be different from if the request is redirected. + The property may be different from if the request is redirected. @@ -3392,7 +3392,7 @@ is the number of milliseconds that a subsequent synchronous request made with the method waits for a response, and the method waits for a stream. The applies to the entire request and response, not individually to the and method calls. If the resource is not returned within the time-out period, the request throws a with the property set to . + is the number of milliseconds that a subsequent synchronous request made with the method waits for a response, and the method waits for a stream. The applies to the entire request and response, not individually to the and method calls. If the resource is not returned within the time-out period, the request throws a with the property set to . The property must be set before the or method is called. Changing the property after calling the or method has no effect diff --git a/xml/System.Net/HttpWebResponse.xml b/xml/System.Net/HttpWebResponse.xml index 6d83171a41602..16a60d3ef0617 100644 --- a/xml/System.Net/HttpWebResponse.xml +++ b/xml/System.Net/HttpWebResponse.xml @@ -38,7 +38,7 @@ > [!NOTE] > Do not confuse with the class that is used in ASP.NET applications and whose methods and properties are exposed through ASP.NET's intrinsic `Response` object. - You should never directly create an instance of the class. Instead, use the instance returned by a call to . You must call either the or the method to close the response and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. + You should never directly create an instance of the class. Instead, use the instance returned by a call to . You must call either the or the method to close the response and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Common header information returned from the Internet resource is exposed as properties of the class. See the following table for a complete list. Other headers can be read from the property as name/value pairs. @@ -211,7 +211,7 @@ ## Remarks The method closes the response stream and releases the connection to the resource for reuse by other requests. - You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream can cause your application to run out of connections. + You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream can cause your application to run out of connections. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -581,7 +581,7 @@ The method returns the data stream from the requested Internet resource. > [!NOTE] -> You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream will cause your application to run out of connections. +> You must call either the or the method to close the stream and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. Failure to close the stream will cause your application to run out of connections. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -861,7 +861,7 @@ The property will use the Content-Location header if present. - Applications that need to access the last redirected should use the property rather than , since the use of property may open security vulnerabilities. + Applications that need to access the last redirected should use the property rather than , since the use of property may open security vulnerabilities. diff --git a/xml/System.Net/IAuthenticationModule.xml b/xml/System.Net/IAuthenticationModule.xml index c82026c58017b..26f2136e61d72 100644 --- a/xml/System.Net/IAuthenticationModule.xml +++ b/xml/System.Net/IAuthenticationModule.xml @@ -26,7 +26,7 @@ Authentication modules conduct the entire authentication process with a server, responding to an authentication challenge as appropriate. This process may consist of requests to an authentication server separate from the resource server, as well as any other activities required to properly authenticate a request for a URI. - Custom authentication modules should implement the interface and then register with the method. Authentication modules are also registered at program initialization by reading the configuration file. + Custom authentication modules should implement the interface and then register with the method. Authentication modules are also registered at program initialization by reading the configuration file. @@ -123,7 +123,7 @@ property identifies the authentication type implemented by this authentication module. The property is used by the method to determine if the authentication module has been registered, and by the method to remove a registered authentication module. + The property identifies the authentication type implemented by this authentication module. The property is used by the method to determine if the authentication module has been registered, and by the method to remove a registered authentication module. diff --git a/xml/System.Net/ICertificatePolicy.xml b/xml/System.Net/ICertificatePolicy.xml index d9fe3d16031f5..51c4f45b81cb9 100644 --- a/xml/System.Net/ICertificatePolicy.xml +++ b/xml/System.Net/ICertificatePolicy.xml @@ -14,7 +14,7 @@ interface is used to provide custom security certificate validation for an application. The default policy is to allow valid certificates, as well as valid certificates that have expired. To change this policy, implement the interface with a different policy, and then assign that policy to . + The interface is used to provide custom security certificate validation for an application. The default policy is to allow valid certificates, as well as valid certificates that have expired. To change this policy, implement the interface with a different policy, and then assign that policy to . uses the Security Support Provider Interface (SSPI). For more information, see the SSPI documentation on MSDN. diff --git a/xml/System.Net/ICredentialPolicy.xml b/xml/System.Net/ICredentialPolicy.xml index afbeb8934d127..a09e324caaa4b 100644 --- a/xml/System.Net/ICredentialPolicy.xml +++ b/xml/System.Net/ICredentialPolicy.xml @@ -27,7 +27,7 @@ > [!NOTE] > policies are invoked only if the or the that is associated with the request has credentials that are not `null`. Setting this policy has no effect on requests that do not specify credentials. - Use the property to set an policy. The that handles authentication for the request will invoke the method before performing the authentication. If the method returns `false`, authentication is not performed. + Use the property to set an policy. The that handles authentication for the request will invoke the method before performing the authentication. If the method returns `false`, authentication is not performed. An policy affects all instances of with non-null credentials in the current application domain. The policy cannot be overridden on individual requests. @@ -82,9 +82,9 @@ policy has been specified by setting the property, the that handles authentication for a invokes the method before performing the authentication. If this method returns `false`, authentication is not performed. + After an policy has been specified by setting the property, the that handles authentication for a invokes the method before performing the authentication. If this method returns `false`, authentication is not performed. - When the original request has been redirected or proxy authentication is required, the resource identified by `challengeUri` can be different from the requested resource that is specified in . In the case of redirection, `challengeUri` contains the actual destination . If proxy authentication is required, `challengeUri` contains the address of the proxy server that requires client authentication. + When the original request has been redirected or proxy authentication is required, the resource identified by `challengeUri` can be different from the requested resource that is specified in . In the case of redirection, `challengeUri` contains the actual destination . If proxy authentication is required, `challengeUri` contains the address of the proxy server that requires client authentication. ]]> diff --git a/xml/System.Net/ICredentialsByHost.xml b/xml/System.Net/ICredentialsByHost.xml index 308a70a798eb5..b48c8386f3730 100644 --- a/xml/System.Net/ICredentialsByHost.xml +++ b/xml/System.Net/ICredentialsByHost.xml @@ -68,7 +68,7 @@ property. + The value of `authType` corresponds to the property. ]]> diff --git a/xml/System.Net/IPAddress.xml b/xml/System.Net/IPAddress.xml index c9c9a83394d6b..73100e1689fd8 100644 --- a/xml/System.Net/IPAddress.xml +++ b/xml/System.Net/IPAddress.xml @@ -290,7 +290,7 @@ method uses the field to indicate that a instance must listen for client activity on all network interfaces. + The method uses the field to indicate that a instance must listen for client activity on all network interfaces. The field is equivalent to 0.0.0.0 in dotted-quad notation. @@ -694,7 +694,7 @@ method uses the field to indicate that a must not listen for client activity. The field is equivalent to 0:0:0:0:0:0:0:0 in colon-hexadecimal notation, or to ::0 in compact notation. + The method uses the field to indicate that a must not listen for client activity. The field is equivalent to 0:0:0:0:0:0:0:0 in colon-hexadecimal notation, or to ::0 in compact notation. @@ -1219,7 +1219,7 @@ method uses the field to indicate that a must not listen for client activity. The field is equivalent to 255.255.255.255 in dotted-quad notation. + The method uses the field to indicate that a must not listen for client activity. The field is equivalent to 255.255.255.255 in dotted-quad notation. diff --git a/xml/System.Net/IPEndPointCollection.xml b/xml/System.Net/IPEndPointCollection.xml index 647969e2c96b0..cd5873ce93283 100644 --- a/xml/System.Net/IPEndPointCollection.xml +++ b/xml/System.Net/IPEndPointCollection.xml @@ -20,11 +20,11 @@ class is derived from the class. + The class is derived from the class. The class contains the host and local or remote port information needed by an application to connect to a service on a host. By combining the host's IP address and port number of a service, the class forms a connection point to a service. - The class is used by classes in the namespace. + The class is used by classes in the namespace. ]]> @@ -78,7 +78,7 @@ If `index` is equal to current count of items in the , then the `item` is added to the end of . - This method is an O(`n`) operation, where `n` is . + This method is an O(`n`) operation, where `n` is . ]]> diff --git a/xml/System.Net/IWebRequestCreate.xml b/xml/System.Net/IWebRequestCreate.xml index 31e6381ccb58b..8ac724f9f94f4 100644 --- a/xml/System.Net/IWebRequestCreate.xml +++ b/xml/System.Net/IWebRequestCreate.xml @@ -23,7 +23,7 @@ interface defines the method that descendants must use to register with the method. + The interface defines the method that descendants must use to register with the method. Classes that implement the interface can be registered with the class and associated with a specific URI scheme so that the calls the class's method when a URI that matches that scheme is requested. diff --git a/xml/System.Net/NetworkCredential.xml b/xml/System.Net/NetworkCredential.xml index 66c0879dc64cf..9d7947f51b671 100644 --- a/xml/System.Net/NetworkCredential.xml +++ b/xml/System.Net/NetworkCredential.xml @@ -391,7 +391,7 @@ property. + The value of `authType` corresponds to the property. ]]> diff --git a/xml/System.Net/ServicePoint.xml b/xml/System.Net/ServicePoint.xml index 2f5ce3e478327..e42f9aaeb80d3 100644 --- a/xml/System.Net/ServicePoint.xml +++ b/xml/System.Net/ServicePoint.xml @@ -27,9 +27,9 @@ ## Remarks The class handles connections to an Internet resource based on the host information passed in the resource's Uniform Resource Identifier (URI). The initial connection to the resource determines the information that the object maintains, which is then shared by all subsequent requests to that resource. - objects are managed by the class and are created, if necessary, by the method. objects are never created directly but are always created and managed by the class. The maximum number of objects that can be created is set by the property. + objects are managed by the class and are created, if necessary, by the method. objects are never created directly but are always created and managed by the class. The maximum number of objects that can be created is set by the property. - Each object maintains its connection to an Internet resource until it has been idle longer than the time specified in the property. When a exceeds the value, it can be recycled to another connection. The default value of is set by the property. + Each object maintains its connection to an Internet resource until it has been idle longer than the time specified in the property. When a exceeds the value, it can be recycled to another connection. The default value of is set by the property. When the property is set to a value other than -1, and after the specified time elapses, an active connection is closed after it services the next request. This is useful for applications that do not require active connections that are opened indefinitely, as they are by default. @@ -117,7 +117,7 @@ (or for Internet Protocol Version 6) and an ephemeral port. Your can satisfy this requirement. + Some load balancing techniques require a client to use a specific local IP address and port number, rather than (or for Internet Protocol Version 6) and an ephemeral port. Your can satisfy this requirement. ]]> @@ -326,7 +326,7 @@ property sets the maximum number of connections that the object can make to an Internet resource. The value of the property is set to the value of the property when the object is created; subsequent changes to have no effect on existing objects. + The property sets the maximum number of connections that the object can make to an Internet resource. The value of the property is set to the value of the property when the object is created; subsequent changes to have no effect on existing objects. @@ -551,9 +551,9 @@ to to indicate that a connection associated with the object should never time out. + You can set to to indicate that a connection associated with the object should never time out. - The default value of the property is the value of the property when the object is created. Subsequent changes to the property have no effect on existing objects. + The default value of the property is the value of the property when the object is created. Subsequent changes to the property have no effect on existing objects. When the for a connection associated with a is exceeded, the connection remains open until the application tries to use the connection. At that time, the Framework closes the connection and creates a new connection to the remote host. diff --git a/xml/System.Net/ServicePointManager.xml b/xml/System.Net/ServicePointManager.xml index 7764f8596f974..93abb3fe201bc 100644 --- a/xml/System.Net/ServicePointManager.xml +++ b/xml/System.Net/ServicePointManager.xml @@ -398,9 +398,9 @@ property defaults to . This is applied to an SSL/TLS session on this instance. + If a value is not specified in the configuration file, the property defaults to . This is applied to an SSL/TLS session on this instance. - The use of the Null cipher is required when the encryption policy is set to . + The use of the Null cipher is required when the encryption policy is set to . ]]> @@ -758,7 +758,7 @@ ## Remarks This property selects the version of the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocol to use for new connections; existing connections aren't changed. -Starting with the .NET Framework 4.7, the default value of this property is . This allows .NET Framework networking APIs based on (such as FTP, HTTP, and SMTP) to inherit the default security protocols from the operating system or from any custom configurations performed by a system administrator. For information about which SSL/TLS protocols are enabled by default on each version of the Windows operating system, see [Protocols in TLS/SSL (Schannel SSP)](https://msdn.microsoft.com/library/windows/desktop/mt808159.aspx). +Starting with the .NET Framework 4.7, the default value of this property is . This allows .NET Framework networking APIs based on (such as FTP, HTTP, and SMTP) to inherit the default security protocols from the operating system or from any custom configurations performed by a system administrator. For information about which SSL/TLS protocols are enabled by default on each version of the Windows operating system, see [Protocols in TLS/SSL (Schannel SSP)](https://msdn.microsoft.com/library/windows/desktop/mt808159.aspx). For versions of the .NET Framework through the .NET Framework 4.6.2, no default value is listed for this property. The security landscape changes constantly, and default protocols and protection levels are changed over time in order to avoid known weaknesses. Defaults vary depending on individual machine configuration, installed software, and applied patches. diff --git a/xml/System.Net/SocketPermission.xml b/xml/System.Net/SocketPermission.xml index 8f14296c27978..5263a57a7851f 100644 --- a/xml/System.Net/SocketPermission.xml +++ b/xml/System.Net/SocketPermission.xml @@ -116,7 +116,7 @@ The `hostName` can be a DNS name, an IP address, or a specified IP subnet, such as 192.168.1.*. - The `portNumber` can be any valid port number defined by the transport, or . + The `portNumber` can be any valid port number defined by the transport, or . diff --git a/xml/System.Net/WebClient.xml b/xml/System.Net/WebClient.xml index 3d2b98f2ed792..0c6adab179206 100644 --- a/xml/System.Net/WebClient.xml +++ b/xml/System.Net/WebClient.xml @@ -32,7 +32,7 @@ ## Remarks The class provides common methods for sending data to or receiving data from any local, intranet, or Internet resource identified by a URI. - The class uses the class to provide access to resources. instances can access data with any descendant registered with the method. + The class uses the class to provide access to resources. instances can access data with any descendant registered with the method. > [!NOTE] > By default, the .NET Framework supports URIs that begin with `http:`, `https:`, ftp:, and `file:` scheme identifiers. @@ -2600,7 +2600,7 @@ internal class MyWebClient:WebClient{ This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. > [!NOTE] -> You must call when finished with the to avoid running out of system resources. +> You must call when finished with the to avoid running out of system resources. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -2663,7 +2663,7 @@ internal class MyWebClient:WebClient{ This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. > [!NOTE] -> You must call when finished with the to avoid running out of system resources. +> You must call when finished with the to avoid running out of system resources. **Note** This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](~/docs/framework/network-programming/network-tracing.md). @@ -2711,7 +2711,7 @@ internal class MyWebClient:WebClient{ This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. This method does not block the calling thread while the stream is opening. To block while waiting for the stream, use the method. @@ -2774,7 +2774,7 @@ internal class MyWebClient:WebClient{ This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. This method does not block the calling thread while the stream is opening. To block while waiting for the stream, use the method. @@ -2891,7 +2891,7 @@ internal class MyWebClient:WebClient{ This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. Asynchronous operations that have not completed can be canceled using the method. @@ -2960,7 +2960,7 @@ internal class MyWebClient:WebClient{ This method retrieves a instance used to access the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. Asynchronous operations that have not completed can be canceled using the method. @@ -3451,7 +3451,7 @@ internal class MyWebClient:WebClient{ This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. Asynchronous operations that have not completed can be canceled using the method. @@ -3515,7 +3515,7 @@ internal class MyWebClient:WebClient{ This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. Asynchronous operations that have not completed can be canceled using the method. @@ -3581,7 +3581,7 @@ internal class MyWebClient:WebClient{ This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. @@ -3649,7 +3649,7 @@ internal class MyWebClient:WebClient{ This method retrieves a instance used to write data to the resource specified by the `address` parameter. The stream is obtained using thread resources that are automatically allocated from the thread pool. > [!NOTE] -> You must call when you are finished with the to avoid running out of system resources. +> You must call when you are finished with the to avoid running out of system resources. If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. diff --git a/xml/System.Net/WebException.xml b/xml/System.Net/WebException.xml index 7c4711cc4c491..56d14ef7f0d70 100644 --- a/xml/System.Net/WebException.xml +++ b/xml/System.Net/WebException.xml @@ -369,7 +369,7 @@ sets the property to and provides the that contains the error message in the property of the that was thrown. The application can examine the to determine the actual error. + Some Internet protocols, such as HTTP, return otherwise valid responses indicating that an error has occurred at the protocol level. When the response to an Internet request indicates an error, sets the property to and provides the that contains the error message in the property of the that was thrown. The application can examine the to determine the actual error. diff --git a/xml/System.Net/WebHeaderCollection.xml b/xml/System.Net/WebHeaderCollection.xml index a7a00845e3521..4434c038b01c6 100644 --- a/xml/System.Net/WebHeaderCollection.xml +++ b/xml/System.Net/WebHeaderCollection.xml @@ -36,7 +36,7 @@ class is generally accessed through or . Some common headers are considered restricted and are either exposed directly by the API (such as `Content-Type`) or protected by the system and cannot be changed. + The class is generally accessed through or . Some common headers are considered restricted and are either exposed directly by the API (such as `Content-Type`) or protected by the system and cannot be changed. The restricted headers are: diff --git a/xml/System.Net/WebPermission.xml b/xml/System.Net/WebPermission.xml index 03b177ffbd834..a8ee69f9f27d9 100644 --- a/xml/System.Net/WebPermission.xml +++ b/xml/System.Net/WebPermission.xml @@ -40,7 +40,7 @@ The and hold the URIs to which you have granted access permission. To add a URI to either of these lists, use . If you pass as the parameter, the URI will be added to the . will allow connections to your target class with URIs matching the . > [!CAUTION] -> To deny access to an Internet resource, you must deny access to all the possible paths to that resource. This requires calling with state parameter set to . A better approach is to allow access to the specific resource only. For more information about this subject, refer to the [NIB: Using the Deny Method](http://msdn.microsoft.com/en-us/6b4d2e01-c504-4ac3-b50e-d6f5e7f5df25) topic. +> To deny access to an Internet resource, you must deny access to all the possible paths to that resource. This requires calling with state parameter set to . A better approach is to allow access to the specific resource only. For more information about this subject, refer to the [NIB: Using the Deny Method](http://msdn.microsoft.com/en-us/6b4d2e01-c504-4ac3-b50e-d6f5e7f5df25) topic. > [!NOTE] > You need to deny access using only the resource canonical path. There is no need to use all the path's syntactical variations. @@ -112,7 +112,7 @@ or , respectively yielding fully restricted or fully unrestricted access to all security variables. If you specify , then you can give access to individual URIs using . + The value of the `state` parameter is either or , respectively yielding fully restricted or fully unrestricted access to all security variables. If you specify , then you can give access to individual URIs using . @@ -199,7 +199,7 @@ This constructor initializes a and grants its target permission to either make a remote host connection or accept a remote host connection using the URI described by the `uriRegex` parameter. > [!NOTE] -> It is recommended that you create `uriRegex` using the , , and flags. +> It is recommended that you create `uriRegex` using the , , and flags. > [!NOTE] > A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. @@ -207,7 +207,7 @@ ## Examples - The following example creates a new instance of with connect rights for the specified . + The following example creates a new instance of with connect rights for the specified . [!code-cpp[WebPermission_Constructor4#1](~/samples/snippets/cpp/VS_Snippets_Remoting/WebPermission_Constructor4/CPP/webpermission_constructor4.cpp#1)] [!code-csharp[WebPermission_Constructor4#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebPermission_Constructor4/CS/webpermission_constructor4.cs#1)] @@ -349,7 +349,7 @@ > Calling on an instance will have no effect as permission is granted to all URIs. > [!NOTE] -> It is recommended that you create `uriRegex` using the , , and flags. +> It is recommended that you create `uriRegex` using the , , and flags. > [!NOTE] > A candidate URI string is checked against the list of relevant regular expressions ( or ) in two ways. First, the candidate URI string is checked against the appropriate list; then, if there is no match, the candidate URI string is converted into a and checked against the appropriate list. @@ -487,7 +487,7 @@ ## Examples - The following example creates a , populates its attributes, and uses to transfer this information to an instance of . + The following example creates a , populates its attributes, and uses to transfer this information to an instance of . [!code-cpp[WebPermission_FromToXml#1](~/samples/snippets/cpp/VS_Snippets_Remoting/WebPermission_FromToXml/CPP/webpermission_fromtoxml.cpp#1)] [!code-csharp[WebPermission_FromToXml#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebPermission_FromToXml/CS/webpermission_fromtoxml.cs#1)] @@ -658,7 +658,7 @@ ## Examples - The following example demonstrates how to use to create a and print its attributes to the console. + The following example demonstrates how to use to create a and print its attributes to the console. [!code-cpp[WebPermission_FromToXml#1](~/samples/snippets/cpp/VS_Snippets_Remoting/WebPermission_FromToXml/CPP/webpermission_fromtoxml.cpp#1)] [!code-csharp[WebPermission_FromToXml#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebPermission_FromToXml/CS/webpermission_fromtoxml.cs#1)] diff --git a/xml/System.Net/WebPermissionAttribute.xml b/xml/System.Net/WebPermissionAttribute.xml index 14e6757026e5b..859b43857ca9e 100644 --- a/xml/System.Net/WebPermissionAttribute.xml +++ b/xml/System.Net/WebPermissionAttribute.xml @@ -28,7 +28,7 @@ ## Remarks allows you to declaratively specify which URI strings and regular expression strings your class can use. - The security information specified in the is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses this information at run time. The passed to the constructor determines the allowable targets. The system uses the returned by the method to convert the security information of the attribute target to a serializable form stored in metadata. + The security information specified in the is stored in the metadata of the attribute target, which is the class to which is applied. The system accesses this information at run time. The passed to the constructor determines the allowable targets. The system uses the returned by the method to convert the security information of the attribute target to a serializable form stored in metadata. > [!NOTE] > is used only for [Declarative Security](http://msdn.microsoft.com/en-us/97e21efd-6e89-4115-90d5-ad239513dad8). For [Imperative Security](http://msdn.microsoft.com/en-us/15aab1e1-6b7d-41ad-b102-c1ed7bedea27), use the corresponding . diff --git a/xml/System.Net/WebProxy.xml b/xml/System.Net/WebProxy.xml index ed066235e51b2..b72421c40661f 100644 --- a/xml/System.Net/WebProxy.xml +++ b/xml/System.Net/WebProxy.xml @@ -820,7 +820,7 @@ The method does not pick up any dynamic settings that are generated from scripts run by Internet Explorer, from automatic configuration entries, or from DHCP or DNS lookups. - Applications should use the property and the method instead of the method. + Applications should use the property and the method instead of the method. diff --git a/xml/System.Net/WebRequest.xml b/xml/System.Net/WebRequest.xml index 36005ff54a416..0b32113debcb2 100644 --- a/xml/System.Net/WebRequest.xml +++ b/xml/System.Net/WebRequest.xml @@ -35,7 +35,7 @@ Requests are sent from an application to a particular URI, such as a Web page on a server. The URI determines the proper descendant class to create from a list of descendants registered for the application. descendants are typically registered to handle a specific protocol, such as HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. - The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. + The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. Because the class is an `abstract` class, the actual behavior of instances at run time is determined by the descendant class returned by method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -175,7 +175,7 @@ The method cancels asynchronous requests to Internet resources started with the method. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ]]> @@ -263,7 +263,7 @@ The method starts an asynchronous request for a stream used to send data to an Internet resource. The callback method that implements the delegate uses the method to return the request stream. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -318,7 +318,7 @@ The method starts an asynchronous request for a response. The callback method that implements the delegate uses the method to return the from the Internet resource. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . > [!NOTE] > If a WebException is thrown, use the and properties of the exception to determine the response from the server. @@ -414,7 +414,7 @@ The property associates specific requests within an application to one or more connection pools. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . ]]> @@ -455,7 +455,7 @@ The property contains the number of bytes of data sent to the Internet resource by the instance. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -503,7 +503,7 @@ The property contains the media type of the request. This is typically the MIME encoding of the content. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -848,7 +848,7 @@ derived factory object was used to create the request. This object may be [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/subscriptions/index/system.net.browser.webrequestcreator.browserhttp\(v=vs.95\).aspx) or , but it may also be a custom instance derived from . This allows an application to determine whether the browser hosting [!INCLUDE[silverlight](~/includes/silverlight-md.md)], the [!INCLUDE[silverlight](~/includes/silverlight-md.md)] client, or some custom object handles HTTP requests and responses for the instance. The method allows an application to configure which derived type will be instantiated when making a request to a specific URI. creators are typically registered to handle a specific protocol, such HTTP or HTTPS, but can be registered to handle a request to a specific server or path on a server. This is useful when more than one derived type can process requests for the same protocol. The [!INCLUDE[sil3_first](~/includes/sil3-first-md.md)] and later runtime supports multiple HTTP handlers each having different capabilities. For example, a web service that uses Representational State Transfer (REST) might require the handler while a SOAP web service might be able to use the default [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/subscriptions/index/system.net.browser.webrequestcreator.browserhttp\(v=vs.95\).aspx) handler. + This property allows an application to determine which derived factory object was used to create the request. This object may be [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/subscriptions/index/system.net.browser.webrequestcreator.browserhttp\(v=vs.95\).aspx) or , but it may also be a custom instance derived from . This allows an application to determine whether the browser hosting [!INCLUDE[silverlight](~/includes/silverlight-md.md)], the [!INCLUDE[silverlight](~/includes/silverlight-md.md)] client, or some custom object handles HTTP requests and responses for the instance. The method allows an application to configure which derived type will be instantiated when making a request to a specific URI. creators are typically registered to handle a specific protocol, such HTTP or HTTPS, but can be registered to handle a request to a specific server or path on a server. This is useful when more than one derived type can process requests for the same protocol. The [!INCLUDE[sil3_first](~/includes/sil3-first-md.md)] and later runtime supports multiple HTTP handlers each having different capabilities. For example, a web service that uses Representational State Transfer (REST) might require the handler while a SOAP web service might be able to use the default [System.Net.Browser.WebRequestCreator.BrowserHttp](https://msdn.microsoft.com/subscriptions/index/system.net.browser.webrequestcreator.browserhttp\(v=vs.95\).aspx) handler. ]]> @@ -886,7 +886,7 @@ The property contains the authentication credentials required to access the Internet resource. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1037,7 +1037,7 @@ > To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by after calling . > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1089,7 +1089,7 @@ The method completes an asynchronous request for an Internet resource that was started with the method. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1179,7 +1179,7 @@ The method provides synchronous access to the . For asynchronous access, use the and methods. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1268,7 +1268,7 @@ The method provides synchronous access to the . For asynchronous access, use the and methods. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . > [!NOTE] > If a WebException is thrown, use the and properties of the exception to determine the response from the server. @@ -1393,7 +1393,7 @@ The property contains a instance containing the header information to send to the Internet resource. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1475,7 +1475,7 @@ When overridden in a descendant class, the property contains the request method to use in this request. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1526,7 +1526,7 @@ With the exception of the first request, the property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is `false`, the waits for an authentication challenge before sending authentication information. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1575,7 +1575,7 @@ The property identifies the network proxy that the request uses to access the Internet resource. The request is made through the proxy server rather than directly to the Internet resource. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1718,7 +1718,7 @@ When overridden in a descendant class, the property contains the instance that method uses to create the request. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1804,7 +1804,7 @@ The property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . diff --git a/xml/System.Net/WebResponse.xml b/xml/System.Net/WebResponse.xml index c393b8d90125d..f8222674db441 100644 --- a/xml/System.Net/WebResponse.xml +++ b/xml/System.Net/WebResponse.xml @@ -154,13 +154,13 @@ method cleans up the resources used by a and closes the underlying stream by calling the method. + The method cleans up the resources used by a and closes the underlying stream by calling the method. > [!NOTE] -> The response must be closed to avoid running out of system resources. The response stream can be closed by calling or . +> The response must be closed to avoid running out of system resources. The response stream can be closed by calling or . > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -208,7 +208,7 @@ The property contains the length, in bytes, of the response from the Internet resource. For request methods that contain header information, the does not include the length of the header information. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -256,7 +256,7 @@ The property contains the MIME content type of the response from the Internet resource, if known. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -416,7 +416,7 @@ The method returns the data stream from the Internet resource. > [!NOTE] -> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or +> The response stream must be closed to avoid running out of system resources. The response stream can be closed by calling or @@ -464,7 +464,7 @@ The property contains the name-value header pairs returned in the response. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -546,7 +546,7 @@ property using the or enumeration value. The default value for the property contains and . + To request mutual authentication, set the property using the or enumeration value. The default value for the property contains and . Note that getting this property can throw . @@ -594,7 +594,7 @@ The property contains the URI of the Internet resource that actually provided the response data. This resource might not be the originally requested URI if the underlying protocol allows redirection of the request. > [!NOTE] -> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . +> The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . diff --git a/xml/System.Net/WebUtility.xml b/xml/System.Net/WebUtility.xml index c41eab188c9bd..5cc011e20b8c7 100644 --- a/xml/System.Net/WebUtility.xml +++ b/xml/System.Net/WebUtility.xml @@ -28,7 +28,7 @@ class contains encoding and decoding utility methods for use with HTML-encode strings. The class also contains methods and properties that can be used for similar purposes. + The class contains encoding and decoding utility methods for use with HTML-encode strings. The class also contains methods and properties that can be used for similar purposes. ]]> diff --git a/xml/System.Numerics/BigInteger.xml b/xml/System.Numerics/BigInteger.xml index 7af156808a63a..f44364bf06f0a 100644 --- a/xml/System.Numerics/BigInteger.xml +++ b/xml/System.Numerics/BigInteger.xml @@ -69,7 +69,7 @@ These methods enable you to instantiate a object whose value is in the range of one of the existing numeric types only. You can instantiate a object whose value can exceed the range of the existing numeric types in one of three ways: -- You can use the `new` keyword and provide a byte array of any size to the constructor. For example: +- You can use the `new` keyword and provide a byte array of any size to the constructor. For example: [!code-csharp[System.Numerics.BigInteger.Class#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/cs/BigInteger_Examples.cs#4)] [!code-vb[System.Numerics.BigInteger.Class#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb#4)] @@ -79,7 +79,7 @@ [!code-csharp[System.Numerics.BigInteger.Class#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/cs/BigInteger_Examples.cs#5)] [!code-vb[System.Numerics.BigInteger.Class#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb#5)] -- You can call a `static` (`Shared` in Visual Basic) method that performs some operation on a numeric expression and returns a calculated result. The following example does this by cubing and assigning the result to a . +- You can call a `static` (`Shared` in Visual Basic) method that performs some operation on a numeric expression and returns a calculated result. The following example does this by cubing and assigning the result to a . [!code-csharp[System.Numerics.BigInteger.Class#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/cs/BigInteger_Examples.cs#6)] [!code-vb[System.Numerics.BigInteger.Class#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class/vb/BigInteger_Examples.vb#6)] @@ -129,7 +129,7 @@ [!code-csharp[System.Numerics.BigInteger.Class.ByteAndHex#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/cs/ByteAndHex_Examples.cs#1)] [!code-vb[System.Numerics.BigInteger.Class.ByteAndHex#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb#1)] - To instantiate a value from a byte array that represents a value of some other integral type, you can pass the integral value to the method, and then pass the resulting byte array to the constructor. The following example instantiates a value from a byte array that represents an value. + To instantiate a value from a byte array that represents a value of some other integral type, you can pass the integral value to the method, and then pass the resulting byte array to the constructor. The following example instantiates a value from a byte array that represents an value. [!code-csharp[System.Numerics.BigInteger.Class.ByteAndHex#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/cs/ByteAndHex_Examples.cs#2)] [!code-vb[System.Numerics.BigInteger.Class.ByteAndHex#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb#2)] @@ -144,9 +144,9 @@ [!code-csharp[System.Numerics.BigInteger.Class.ByteAndHex#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/cs/ByteAndHex_Examples.cs#4)] [!code-vb[System.Numerics.BigInteger.Class.ByteAndHex#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb#4)] - However, you may need to add this additional zero-value byte to byte arrays that are created dynamically by the developer or that are returned by methods that convert unsigned integers to byte arrays (such as , , and ). + However, you may need to add this additional zero-value byte to byte arrays that are created dynamically by the developer or that are returned by methods that convert unsigned integers to byte arrays (such as , , and ). - When parsing a hexadecimal string, the and methods assume that if the most significant bit of the first byte in the string is set, or if the first hexadecimal digit of the string represents the lower four bits of a byte value, the value is represented by using two's complement representation. For example, both "FF01" and "F01" represent the decimal value -255. To differentiate positive from negative values, positive values should include a leading zero. The relevant overloads of the method, when they are passed the "X" format string, add a leading zero to the returned hexadecimal string for positive values. This makes it possible to round-trip values by using the and methods, as the following example shows. + When parsing a hexadecimal string, the and methods assume that if the most significant bit of the first byte in the string is set, or if the first hexadecimal digit of the string represents the lower four bits of a byte value, the value is represented by using two's complement representation. For example, both "FF01" and "F01" represent the decimal value -255. To differentiate positive from negative values, positive values should include a leading zero. The relevant overloads of the method, when they are passed the "X" format string, add a leading zero to the returned hexadecimal string for positive values. This makes it possible to round-trip values by using the and methods, as the following example shows. [!code-csharp[System.Numerics.BigInteger.Class.ByteAndHex#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/cs/ByteAndHex_Examples.cs#5)] [!code-vb[System.Numerics.BigInteger.Class.ByteAndHex#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Class.ByteAndHex/vb/ByteAndHex_Examples.vb#5)] @@ -201,19 +201,19 @@ |Hexadecimal string|E8D4A51000| |Byte array (lowest index first)|00 10 A5 D4 E8 00| - Most methods that convert numeric values to byte arrays, such as and , return byte arrays in little-endian order. + Most methods that convert numeric values to byte arrays, such as and , return byte arrays in little-endian order. The constructor expects positive values in the byte array to use sign-and-magnitude representation, and negative values to use two's complement representation. In other words, if the highest-order bit of the highest-order byte in `value` is set, the resulting value is negative. Depending on the source of the byte array, this may cause a positive value to be misinterpreted as a negative value. Byte arrays are typically generated in the following ways: -- By calling the method. Because this method returns a byte array with the highest-order bit of the highest-order byte in the array set to zero for positive values, there is no chance of misinterpreting a positive value as negative. Unmodified byte arrays created by the method always successfully round-trip when they are passed to the constructor. +- By calling the method. Because this method returns a byte array with the highest-order bit of the highest-order byte in the array set to zero for positive values, there is no chance of misinterpreting a positive value as negative. Unmodified byte arrays created by the method always successfully round-trip when they are passed to the constructor. -- By calling the method and passing it a signed integer as a parameter. Because signed integers handle both sign-and-magnitude representation and two's complement representation, there is no chance of misinterpreting a positive value as negative. +- By calling the method and passing it a signed integer as a parameter. Because signed integers handle both sign-and-magnitude representation and two's complement representation, there is no chance of misinterpreting a positive value as negative. -- By calling the method and passing it an unsigned integer as a parameter. Because unsigned integers are represented by their magnitude only, positive values can be misinterpreted as negative values. To prevent this misinterpretation, you can add a zero-byte value to the end of the array. The example in the next section provides an illustration. +- By calling the method and passing it an unsigned integer as a parameter. Because unsigned integers are represented by their magnitude only, positive values can be misinterpreted as negative values. To prevent this misinterpretation, you can add a zero-byte value to the end of the array. The example in the next section provides an illustration. - By creating a byte array either dynamically or statically without necessarily calling any of the previous methods, or by modifying an existing byte array. To prevent positive values from being misinterpreted as negative values, you can add a zero-byte value to the end of the array. - If `value` is an empty array, the new object is initialized to a value of . If `value` is `null`, the constructor throws an . + If `value` is an empty array, the new object is initialized to a value of . If `value` is `null`, the constructor throws an . @@ -645,7 +645,7 @@ |`value` >= 0|`value`| |`value` < 0|`value` * -1| - The method is equivalent to the method for the primitive numeric types. + The method is equivalent to the method for the primitive numeric types. @@ -883,17 +883,17 @@ method implements the method. It is used by generic collection objects to order the items in the collection. + This overload of the method implements the method. It is used by generic collection objects to order the items in the collection. ## Examples - The following example illustrates the use of the method to order a list of `StarInfo` objects. Each `StarInfo` object provides information about a star's name and its distance from the Earth in miles. `StarInfo` implements the interface, which enables `StarInfo` objects to be sorted by generic collection classes. Its implementation just wraps a call to . + The following example illustrates the use of the method to order a list of `StarInfo` objects. Each `StarInfo` object provides information about a star's name and its distance from the Earth in miles. `StarInfo` implements the interface, which enables `StarInfo` objects to be sorted by generic collection classes. Its implementation just wraps a call to . [!code-csharp[System.Numerics.BigInteger.CompareTo#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/cs/Example1.cs#1)] [!code-vb[System.Numerics.BigInteger.CompareTo#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example1.vb#1)] - The following code then instantiates four `StarInfo` objects and stores them in a generic object. After the method is called, `StarInfo` objects are displayed in order of their distance from the Earth. + The following code then instantiates four `StarInfo` objects and stores them in a generic object. After the method is called, `StarInfo` objects are displayed in order of their distance from the Earth. [!code-csharp[System.Numerics.BigInteger.CompareTo#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/cs/Example1.cs#2)] [!code-vb[System.Numerics.BigInteger.CompareTo#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.CompareTo/vb/Example1.vb#2)] @@ -952,7 +952,7 @@ method implements the method. It is used by non-generic collection objects to order the items in the collection. + This overload of the method implements the method. It is used by non-generic collection objects to order the items in the collection. The `obj` parameter must be one of the following: @@ -1128,7 +1128,7 @@ The sign of the returned `remainder` value is the same as the sign of the `dividend` parameter. - The behavior of the method is identical to that of the method. + The behavior of the method is identical to that of the method. @@ -1180,7 +1180,7 @@ ## Remarks If `other` is a , , , , , or value, it is implicitly converted to an value when the method is called. - To determine the relationship between the two objects instead of just testing for equality, call the method. + To determine the relationship between the two objects instead of just testing for equality, call the method. @@ -1231,7 +1231,7 @@ ## Remarks This method implements the interface and performs slightly better than because it does not have to convert the `other` parameter to a object. - To determine the relationship between the two objects instead of just testing for equality, call the method. + To determine the relationship between the two objects instead of just testing for equality, call the method. @@ -1340,7 +1340,7 @@ method. + To determine the relationship between the two objects instead of just testing for equality, call the method. @@ -1490,7 +1490,7 @@ value % 2 == 0; value Mod 2 = 0 ``` - If the value of the current object is , the property returns `true`. + If the value of the current object is , the property returns `true`. ]]> @@ -1659,12 +1659,12 @@ value Mod 2 = 0 To calculate the base 10 logarithm of a value, call the method. To calculate the logarithm of a number in another base, call the method. - You can find the square root of a number by calling the method along with the method. Note that the result is if the result is greater than . The following example calculates the square root of each element in an array of values. + You can find the square root of a number by calling the method along with the method. Note that the result is if the result is greater than . The following example calculates the square root of each element in an array of values. [!code-csharp[System.Numerics.BigInteger.Log#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.biginteger.log/cs/log1.cs#1)] [!code-vb[System.Numerics.BigInteger.Log#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.biginteger.log/vb/log1.vb#1)] - This method corresponds to the method for the primitive numeric types. + This method corresponds to the method for the primitive numeric types. ]]> @@ -1713,20 +1713,20 @@ value Mod 2 = 0 |`value` parameter|`baseValue` parameter|Return value| |-----------------------|---------------------------|------------------| |`value` > 0|(0 < `baseValue` < 1) -or-(`baseValue` > 1)|logbaseValue(`value`)| -|`value` < 0|(any value)|| -|(any value)|`baseValue` < 0|| -|`value` != 1|`baseValue` = 0|| -|`value` != 1|`baseValue` = || -|(any value)|`baseValue` = || -|(any value)|`baseValue` = 1|| -|`value` = 0|0 < `baseValue` < 1|| -|`value` = 0|`baseValue` > 1|| +|`value` < 0|(any value)|| +|(any value)|`baseValue` < 0|| +|`value` != 1|`baseValue` = 0|| +|`value` != 1|`baseValue` = || +|(any value)|`baseValue` = || +|(any value)|`baseValue` = 1|| +|`value` = 0|0 < `baseValue` < 1|| +|`value` = 0|`baseValue` > 1|| |`value` = 1|`baseValue` = 0|0| -|`value` = 1|`baseValue` = |0| +|`value` = 1|`baseValue` = |0| To calculate the base 10 logarithm of a value, call the method. To calculate the natural logarithm of a number, call the method. - This method corresponds to the method for the primitive numeric types. + This method corresponds to the method for the primitive numeric types. ]]> @@ -1773,12 +1773,12 @@ value Mod 2 = 0 |Sign of value parameter|Return value| |-----------------------------|------------------| |Positive|The base 10 log of `value`; that is, log10`value`.| -|Zero|.| -|Negative|.| +|Zero|.| +|Negative|.| - To calculate the natural logarithm of a value, call the method. To calculate the logarithm of a number in another base, call the method. + To calculate the natural logarithm of a value, call the method. To calculate the logarithm of a number in another base, call the method. - This method corresponds to the method for the primitive numeric types. + This method corresponds to the method for the primitive numeric types. ]]> @@ -1820,7 +1820,7 @@ value Mod 2 = 0 method for primitive numeric types. + This method corresponds to the method for primitive numeric types. @@ -1869,7 +1869,7 @@ value Mod 2 = 0 method for primitive numeric types. + This method corresponds to the method for primitive numeric types. @@ -2328,7 +2328,7 @@ value Mod 2 = 0 Because objects are immutable, the operator creates a new object whose value is one less than the object represented by `value`. This means that repeated calls to may be expensive. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -2379,7 +2379,7 @@ value Mod 2 = 0 Languages that do not support custom operators and operator overloading can call the method instead. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example creates an array of values. It then uses each element as the quotient in a division operation that uses the method, the division operator (/), and the method. @@ -2434,11 +2434,11 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#4)] [!code-vb[System.Numerics.BigInteger.Operators#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#4)] - Languages that do not support custom operators can call the instance method instead. + Languages that do not support custom operators can call the instance method instead. If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -2483,11 +2483,11 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#5)] [!code-vb[System.Numerics.BigInteger.Operators#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#5)] - Languages that do not support custom operators can call the instance method instead. + Languages that do not support custom operators can call the instance method instead. If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -2537,9 +2537,9 @@ value Mod 2 = 0 [!code-csharp[System.Numeric.BigInteger.Class#19](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/cs/BigInteger_Examples.cs#19)] [!code-vb[System.Numeric.BigInteger.Class#19](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#19)] - Languages that do not support custom operators can call the instance method instead. + Languages that do not support custom operators can call the instance method instead. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -2589,7 +2589,7 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#6)] [!code-vb[System.Numerics.BigInteger.Operators#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#6)] - Languages that do not support custom operators can call the instance method instead. + Languages that do not support custom operators can call the instance method instead. ]]> @@ -2641,7 +2641,7 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#7)] [!code-vb[System.Numerics.BigInteger.Operators#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#7)] - Languages that do not support custom operators can call the instance method instead. + Languages that do not support custom operators can call the instance method instead. ]]> @@ -2739,7 +2739,7 @@ value Mod 2 = 0 The overloads of the method define the types to which or from which a object can be converted. Because the conversion from to can involve truncating any fractional part of `value`, language compilers do not perform this conversion automatically. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` in Visual Basic) is used. Otherwise, they display a compiler error. - For languages that do not support custom operators, the alternative method is . + For languages that do not support custom operators, the alternative method is . ## Examples @@ -2789,7 +2789,7 @@ value Mod 2 = 0 The overloads of the method define the types to which or from which a object can be converted. Because the conversion from to can involve truncating any fractional part of `value`, language compilers do not perform this conversion automatically. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` in Visual Basic) is used. Otherwise, they display a compiler error. - For languages that do not support custom operators, the alternative method is . + For languages that do not support custom operators, the alternative method is . ## Examples @@ -2955,9 +2955,9 @@ value Mod 2 = 0 ## Remarks The overloads of the method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CDbl` in Visual Basic) is used. - Because the value can be outside the range of the data type, this operation is a narrowing conversion. If the conversion is unsuccessful, it does not throw an . Instead, if the value is less than , the resulting value is . If the value is greater than , the resulting value is . + Because the value can be outside the range of the data type, this operation is a narrowing conversion. If the conversion is unsuccessful, it does not throw an . Instead, if the value is less than , the resulting value is . If the value is greater than , the resulting value is . - The conversion of a to a may involve a loss of precision. In some cases, the loss of precision may cause the casting or conversion operation to succeed even if the value is outside the range of the data type. The following example provides an illustration. It assigns the maximum value of a to two variables, increments one variable by 9.999e291, and tests the two variables for equality. As expected, the call to the method shows that they are unequal. However, the conversion of the larger value back to a succeeds, although the value now exceeds . + The conversion of a to a may involve a loss of precision. In some cases, the loss of precision may cause the casting or conversion operation to succeed even if the value is outside the range of the data type. The following example provides an illustration. It assigns the maximum value of a to two variables, increments one variable by 9.999e291, and tests the two variables for equality. As expected, the call to the method shows that they are unequal. However, the conversion of the larger value back to a succeeds, although the value now exceeds . [!code-csharp[System.Numerics.BigInteger.Explicit#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/cs/Explicit1.cs#4)] [!code-vb[System.Numerics.BigInteger.Explicit#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb#4)] @@ -3234,9 +3234,9 @@ value Mod 2 = 0 ## Remarks The overloads of the method define the types to which or from which a object can be converted. Language compilers do not perform this conversion automatically because it can involve data loss or a loss of precision. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` or `CSng` in Visual Basic) is used. Otherwise, they display a compiler error. - Because the value can be outside the range of the data type, this operation is a narrowing conversion. If the conversion is unsuccessful, it does not throw an . Instead, if the value is less than , the resulting value is . If the value is greater than , the resulting value is . + Because the value can be outside the range of the data type, this operation is a narrowing conversion. If the conversion is unsuccessful, it does not throw an . Instead, if the value is less than , the resulting value is . If the value is greater than , the resulting value is . - The conversion of a to a may involve a loss of precision. In some cases, the loss of precision may cause the casting or conversion operation to succeed even if the value is outside the range of the data type. The following example provides an illustration. It assigns the maximum value of a to two variables, increments one variable by 9.999e291, and tests the two variables for equality. As expected, the call to the method shows that they are unequal. However, the conversion of the larger value back to a succeeds, although the value now exceeds . + The conversion of a to a may involve a loss of precision. In some cases, the loss of precision may cause the casting or conversion operation to succeed even if the value is outside the range of the data type. The following example provides an illustration. It assigns the maximum value of a to two variables, increments one variable by 9.999e291, and tests the two variables for equality. As expected, the call to the method shows that they are unequal. However, the conversion of the larger value back to a succeeds, although the value now exceeds . [!code-csharp[System.Numerics.BigInteger.Explicit#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/cs/Explicit1.cs#5)] [!code-vb[System.Numerics.BigInteger.Explicit#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Explicit/vb/Explicit1.vb#5)] @@ -3467,7 +3467,7 @@ value Mod 2 = 0 The overloads of the method define the types to which or from which a object can be converted. Because the conversion from to can involve truncating any fractional part of `value`, language compilers do not perform this conversion automatically. Instead, they perform the conversion only if a casting operator (in C#) or a conversion function (such as `CType` in Visual Basic) is used. Otherwise, they display a compiler error. - For languages that do not support custom operators, the alternative method is . + For languages that do not support custom operators, the alternative method is . ## Examples @@ -3530,13 +3530,13 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#9](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#9)] [!code-vb[System.Numerics.BigInteger.Operators#9](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#9)] - Languages that do not support custom operators can call the instance method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the instance method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#10](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#10)] If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -3581,13 +3581,13 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#11)] [!code-vb[System.Numerics.BigInteger.Operators#11](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#11)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#12)] If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -3637,11 +3637,11 @@ value Mod 2 = 0 [!code-csharp[System.Numeric.BigInteger.Class#20](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/cs/BigInteger_Examples.cs#20)] [!code-vb[System.Numeric.BigInteger.Class#20](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#20)] - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. [!code-vb[System.Numeric.BigInteger.Class#21](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#21)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -3691,7 +3691,7 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#13](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#13)] [!code-vb[System.Numerics.BigInteger.Operators#13](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#13)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#14](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#14)] @@ -3745,7 +3745,7 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#15](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#15)] [!code-vb[System.Numerics.BigInteger.Operators#15](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#15)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#16](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#16)] @@ -3794,13 +3794,13 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#17](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#17)] [!code-vb[System.Numerics.BigInteger.Operators#17](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#17)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#18](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#18)] If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -3845,13 +3845,13 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#19](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#19)] [!code-vb[System.Numerics.BigInteger.Operators#19](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#19)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#20](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#20)] If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -3901,11 +3901,11 @@ value Mod 2 = 0 [!code-csharp[System.Numeric.BigInteger.Class#22](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/cs/BigInteger_Examples.cs#22)] [!code-vb[System.Numeric.BigInteger.Class#22](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#22)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numeric.BigInteger.Class#23](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#23)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -3955,11 +3955,11 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#21](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#21)] [!code-vb[System.Numerics.BigInteger.Operators#21](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#21)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#22](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#22)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -4009,11 +4009,11 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#23](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#23)] [!code-vb[System.Numerics.BigInteger.Operators#23](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#23)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#24](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#24)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -4052,7 +4052,7 @@ value Mod 2 = 0 ## Remarks Any fractional part of the `value` parameter is truncated before conversion. - For languages that do not support implicit operators, the alternative method is . + For languages that do not support implicit operators, the alternative method is . The overloads of the method define the types to which or from which a compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an . This overload lets the compiler handle conversions from a value to a value, as the following example shows. @@ -4096,7 +4096,7 @@ value Mod 2 = 0 . + For languages that do not support implicit operators, the alternative method is . The overloads of the method define the types to which or from which a compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an . This overload lets the compiler handle conversions from a value to a value, as the following example shows. @@ -4140,7 +4140,7 @@ value Mod 2 = 0 . + For languages that do not support implicit operators, the alternative method is . The overloads of the method define the types to which or from which a compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an . This overload lets the compiler handle conversions from a value to a value, as the following example shows. @@ -4184,7 +4184,7 @@ value Mod 2 = 0 . + For languages that do not support implicit operators, the alternative method is . The overloads of the method define the types to which or from which a compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an . This overload lets the compiler handle conversions from a value to a value, as the following example shows. @@ -4235,7 +4235,7 @@ value Mod 2 = 0 . + For languages that do not support implicit operators, the alternative method is . The overloads of the method define the types to which or from which a compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an . This overload lets the compiler handle conversions from a value to a value, as the following example shows. @@ -4286,7 +4286,7 @@ value Mod 2 = 0 . + For languages that do not support implicit operators, the alternative method is . The overloads of the method define the types to which or from which a compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an . This overload lets the compiler handle conversions from a value to a value, as the following example shows. @@ -4337,7 +4337,7 @@ value Mod 2 = 0 . + For languages that do not support implicit operators, the alternative method is . The overloads of the method define the types to which or from which a compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an . This overload lets the compiler handle conversions from a value to a value, as the following example shows. @@ -4388,7 +4388,7 @@ value Mod 2 = 0 . + For languages that do not support implicit operators, the alternative method is . The overloads of the method define the types to which or from which a compiler can automatically convert a value without an explicit casting operator (in C#) or a call to a conversion function (in Visual Basic). They are widening conversions that do not involve data loss and do not throw an . This overload lets the compiler handle conversions from a value to a value, as the following example shows. @@ -4442,7 +4442,7 @@ value Mod 2 = 0 Because objects are immutable, the operator creates a new object whose value is one more than the object represented by `value`. Therefore, repeated calls to may be expensive. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -4489,9 +4489,9 @@ value Mod 2 = 0 Languages that do not support custom operators can test for inequality by using one of the following techniques: -- Calling the instance method, which indicates the relationship between a and a signed long integer value. +- Calling the instance method, which indicates the relationship between a and a signed long integer value. -- Calling the instance method and reversing its value. +- Calling the instance method and reversing its value. If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. @@ -4542,13 +4542,13 @@ value Mod 2 = 0 Languages that do not support custom operators can test for inequality by using one of the following techniques: -- Calling the method, which indicates the relationship between a and a signed long integer value. +- Calling the method, which indicates the relationship between a and a signed long integer value. -- Calling the method and reversing its value. +- Calling the method and reversing its value. If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -4600,11 +4600,11 @@ value Mod 2 = 0 Languages that do not support custom operators can test for inequality by using one of the following techniques: -- Calling the method, which indicates the relationship between two objects. +- Calling the method, which indicates the relationship between two objects. -- Calling the method and reversing its value. +- Calling the method and reversing its value. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -4656,9 +4656,9 @@ value Mod 2 = 0 Languages that do not support custom operators can test for inequality by using one of the following techniques: -- Calling the method, which indicates the relationship between a and an unsigned long integer value. +- Calling the method, which indicates the relationship between a and an unsigned long integer value. -- Calling the method and reversing its value. +- Calling the method and reversing its value. ]]> @@ -4712,9 +4712,9 @@ value Mod 2 = 0 Languages that do not support custom operators can test for inequality by using one of the following techniques: -- Calling the method, which indicates the relationship between a and an unsigned long integer value. +- Calling the method, which indicates the relationship between a and an unsigned long integer value. -- Calling the method and reversing its value. +- Calling the method and reversing its value. ]]> @@ -4813,13 +4813,13 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#31](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#31)] [!code-vb[System.Numerics.BigInteger.Operators#31](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#31)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#32](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#32)] If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -4864,13 +4864,13 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#33](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#33)] [!code-vb[System.Numerics.BigInteger.Operators#33](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#33)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#34](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#34)] If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -4920,11 +4920,11 @@ value Mod 2 = 0 [!code-csharp[System.Numeric.BigInteger.Class#27](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/cs/BigInteger_Examples.cs#27)] [!code-vb[System.Numeric.BigInteger.Class#27](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#27)] - Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. Some languages can also call the method directly, as the following example shows. [!code-vb[System.Numeric.BigInteger.Class#28](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#28)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -4974,11 +4974,11 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#35](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#35)] [!code-vb[System.Numerics.BigInteger.Operators#35](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#35)] - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#36](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#36)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5028,11 +5028,11 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#37](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#37)] [!code-vb[System.Numerics.BigInteger.Operators#37](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#37)] - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#38](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#38)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5077,13 +5077,13 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#39](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#39)] [!code-vb[System.Numerics.BigInteger.Operators#39](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#39)] - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#40](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#40)] If `left` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5128,13 +5128,13 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#41](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#41)] [!code-vb[System.Numerics.BigInteger.Operators#41](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#41)] - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#42](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#42)] If `right` is a , , , , , or value, it is implicitly converted to an value when the operation is performed. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5188,7 +5188,7 @@ value Mod 2 = 0 [!code-vb[System.Numeric.BigInteger.Class#30](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#30)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5238,11 +5238,11 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#43](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#43)] [!code-vb[System.Numerics.BigInteger.Operators#43](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#43)] - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#44](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#44)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5292,11 +5292,11 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#45](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/Operator1.cs#45)] [!code-vb[System.Numerics.BigInteger.Operators#45](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#45)] - Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. + Languages that do not support custom operators can call the method instead. They can also call the method directly, as the following example shows. [!code-vb[System.Numerics.BigInteger.Operators#46](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#46)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5345,11 +5345,11 @@ value Mod 2 = 0 [!code-csharp[System.Numeric.BigInteger.Class#31](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/cs/BigInteger_Examples.cs#31)] [!code-vb[System.Numeric.BigInteger.Class#31](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#31)] - Languages that do not support custom operators can call the method instead. + Languages that do not support custom operators can call the method instead. The sign of the value returned by the modulus operation depends on the sign of `dividend`: If `dividend` is positive, the modulus operation returns a positive result; if it is negative, the modulus operation returns a negative result. The behavior of the modulus operation with values is identical to the modulus operation with other integral types. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> is 0 (zero). @@ -5400,7 +5400,7 @@ value Mod 2 = 0 [!code-csharp[System.Numeric.BigInteger.Class#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/cs/BigInteger_Examples.cs#11)] [!code-vb[System.Numeric.BigInteger.Class#11](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#11)] - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5495,7 +5495,7 @@ value Mod 2 = 0 [!code-csharp[System.Numerics.BigInteger.Operators#48](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/cs/RightShift1.cs#48)] [!code-vb[System.Numerics.BigInteger.Operators#48](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numerics.BigInteger.Operators/vb/Operator1.vb#48)] - If `shift` is greater than or equal to the number of bits in a positive value, the result of the right-shift operation is . If `shift` is greater than the number of bits in a negative value, the result of the right-shift operation is . + If `shift` is greater than or equal to the number of bits in a positive value, the result of the right-shift operation is . If `shift` is greater than the number of bits in a negative value, the result of the right-shift operation is . ]]> @@ -5546,9 +5546,9 @@ value Mod 2 = 0 [!code-csharp[System.Numeric.BigInteger.Class#14](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/cs/BigInteger_Examples.cs#14)] [!code-vb[System.Numeric.BigInteger.Class#14](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Numeric.BigInteger.Class/vb/BigInteger_Examples.vb#14)] - Languages that do not support custom operators can call the method instead. + Languages that do not support custom operators can call the method instead. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -5592,7 +5592,7 @@ value Mod 2 = 0 ## Remarks The method defines the operation of the unary negation operator (or the additive inverse operator) for values. The operation produces a value that results in 0 (zero) when it is added to the original number. Languages that do not support custom operators can call the method instead. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example illustrates three different ways to negate the value of a object. @@ -5695,16 +5695,16 @@ value Mod 2 = 0 |Element|Description| |-------------|-----------------| |*ws*|Optional white space.| -|*sign*|An optional sign. Valid sign characters are determined by the and properties of the current culture.| +|*sign*|An optional sign. Valid sign characters are determined by the and properties of the current culture.| |*digits*|A sequence of digits ranging from 0 to 9. Any leading zeros are ignored.| > [!NOTE] -> The string specified by the `value` parameter is interpreted by using the style. It cannot contain any group separators or decimal separator, and it cannot have a decimal portion. +> The string specified by the `value` parameter is interpreted by using the style. It cannot contain any group separators or decimal separator, and it cannot have a decimal portion. - The `value` parameter is parsed by using the formatting information in a object that is initialized for the current system culture. For more information, see . To parse a string by using the formatting information of a specific culture, use the method. + The `value` parameter is parsed by using the formatting information in a object that is initialized for the current system culture. For more information, see . To parse a string by using the formatting information of a specific culture, use the method. > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. @@ -5763,7 +5763,7 @@ value Mod 2 = 0 [*ws*][*$*][*sign*][*digits*,]*digits*[.*fractional_digits*][E[*sign*]*exponential_digits*][*ws*] - If `style` includes , the `value` parameter may contain the following elements: + If `style` includes , the `value` parameter may contain the following elements: [*ws*]*hexdigits*[*ws*] @@ -5771,16 +5771,16 @@ value Mod 2 = 0 |Element|Description| |-------------|-----------------| -|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag.| -|*$*|A culture-specific currency symbol. Its position in the string is defined by the and properties of the current culture. The current culture's currency symbol can appear in `value` if `style` includes the flag.| -|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| +|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag.| +|*$*|A culture-specific currency symbol. Its position in the string is defined by the and properties of the current culture. The current culture's currency symbol can appear in `value` if `style` includes the flag.| +|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| |*digits*

*fractional_digits*

*exponential_digits*|A sequence of digits from 0 through 9. For *fractional_digits*, only the digit 0 is valid.| -|*,*|A culture-specific group separator symbol. The current culture's group separator can appear in `value` if `style` includes the flag.| -|*.*|A culture-specific decimal point symbol. The current culture's decimal point symbol can appear in `value` if `style` includes the flag. Only the digit 0 can appear as a fractional digit for the parse operation to succeed; if *fractional_digits* includes any other digit, a is thrown.| -|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| +|*,*|A culture-specific group separator symbol. The current culture's group separator can appear in `value` if `style` includes the flag.| +|*.*|A culture-specific decimal point symbol. The current culture's decimal point symbol can appear in `value` if `style` includes the flag. Only the digit 0 can appear as a fractional digit for the parse operation to succeed; if *fractional_digits* includes any other digit, a is thrown.| +|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| |*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| - A string with digits only (which corresponds to the style) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in the input string. The following table indicates how individual members affect the elements that may be present in `value`. + A string with digits only (which corresponds to the style) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in the input string. The following table indicates how individual members affect the elements that may be present in `value`. |`NumberStyles` value|Elements permitted in `value` in addition to digits| |--------------------------|---------------------------------------------------------| @@ -5800,9 +5800,9 @@ value Mod 2 = 0 ||All elements. However, `value` cannot represent a hexadecimal number.| > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. - Unlike the other values, which allow for, but do not require, the presence of particular style elements in `value`, the style value means that the individual numeric characters in `value` are always interpreted as hexadecimal characters. Valid hexadecimal characters are 0-9, A-F, and a-f. The only other flags that can be combined with the `style` parameter are and . (The enumeration includes a composite number style, , that includes both white-space flags.) + Unlike the other values, which allow for, but do not require, the presence of particular style elements in `value`, the style value means that the individual numeric characters in `value` are always interpreted as hexadecimal characters. Valid hexadecimal characters are 0-9, A-F, and a-f. The only other flags that can be combined with the `style` parameter are and . (The enumeration includes a composite number style, , that includes both white-space flags.) > [!NOTE] > If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. @@ -5880,14 +5880,14 @@ value Mod 2 = 0 |Element|Description| |-------------|-----------------| |*ws*|Optional white space.| -|*sign*|An optional sign. Valid sign characters are determined by the and properties of the object that is returned by the `provider` object's method.| +|*sign*|An optional sign. Valid sign characters are determined by the and properties of the object that is returned by the `provider` object's method.| |*digits*|A sequence of digits ranging from 0 to 9. Any leading zeros are ignored.| > [!NOTE] -> The string specified by the `value` parameter is interpreted using the style. It cannot contain any group separators or decimal separator, and it cannot have a decimal portion. +> The string specified by the `value` parameter is interpreted using the style. It cannot contain any group separators or decimal separator, and it cannot have a decimal portion. > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. The `provider` parameter is an implementation whose method returns a object that provides culture-specific formatting information. When the method is invoked, it calls the `provider` parameter's method and passes it a object that represents the type. The method then returns the object that provides information about the format of the `value` parameter. There are three ways to use the `provider` parameter to supply custom formatting information to the parse operation: @@ -5902,7 +5902,7 @@ value Mod 2 = 0 ## Examples - The following examples show two ways to define the tilde (~) as a negative sign for formatting values. Note that to display the values in the same format as the original strings, your code must call the method and pass it the object that provides formatting information. + The following examples show two ways to define the tilde (~) as a negative sign for formatting values. Note that to display the values in the same format as the original strings, your code must call the method and pass it the object that provides formatting information. The first example defines a class that implements and uses the method to return the object that provides formatting information. @@ -5970,7 +5970,7 @@ value Mod 2 = 0 [*ws*][*$*][*sign*][*digits*,]*digits*[*.fractional_digits*][E[*sign*]*exponential_digits*][*ws*] - If `style` includes , the `value` parameter may include the following elements: + If `style` includes , the `value` parameter may include the following elements: [*ws*]*hexdigits*[*ws*] @@ -5978,16 +5978,16 @@ value Mod 2 = 0 |Element|Description| |-------------|-----------------| -|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag.| -|*$*|A culture-specific currency symbol. Its position in the string is defined by the and properties of the culture indicated by the `provider` parameter. The current culture's currency symbol can appear in `value` if `style` includes the flag.| -|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| +|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag.| +|*$*|A culture-specific currency symbol. Its position in the string is defined by the and properties of the culture indicated by the `provider` parameter. The current culture's currency symbol can appear in `value` if `style` includes the flag.| +|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| |*digits*

*fractional_digits*

*exponential_digits*|A sequence of digits from 0 through 9. For *fractional_digits*, only the digit 0 is valid.| -|*,*|A culture-specific group separator symbol. The group separator symbol of the culture specified by `provider` can appear in `value` if `style` includes the flag.| -|*.*|A culture-specific decimal point symbol. The decimal point symbol of the culture designated by `provider` can appear in `value` if `style` includes the flag. Only the digit 0 can appear as a fractional digit for the parse operation to succeed; if *fractional_digits* includes any other digit, a is thrown.| -|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| +|*,*|A culture-specific group separator symbol. The group separator symbol of the culture specified by `provider` can appear in `value` if `style` includes the flag.| +|*.*|A culture-specific decimal point symbol. The decimal point symbol of the culture designated by `provider` can appear in `value` if `style` includes the flag. Only the digit 0 can appear as a fractional digit for the parse operation to succeed; if *fractional_digits* includes any other digit, a is thrown.| +|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| |*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| - A string with digits only (which corresponds to the style) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in the input string. The following table indicates how individual members affect the elements that may be present in `value`. + A string with digits only (which corresponds to the style) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in the input string. The following table indicates how individual members affect the elements that may be present in `value`. |NumberStyles value|Elements permitted in value in addition to digits| |------------------------|-------------------------------------------------------| @@ -6007,9 +6007,9 @@ value Mod 2 = 0 ||All elements. However, `value` cannot represent a hexadecimal number.| > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. - Unlike the other values, which allow for but do not require the presence of particular style elements in `value`, the style value means that the individual numeric characters in `value` are always interpreted as hexadecimal characters. Valid hexadecimal characters are 0-9, A-F, and a-f. The only other flags that can be combined with the `style` parameter are and . (The enumeration includes a composite number style, , that includes both white-space flags.) + Unlike the other values, which allow for but do not require the presence of particular style elements in `value`, the style value means that the individual numeric characters in `value` are always interpreted as hexadecimal characters. Valid hexadecimal characters are 0-9, A-F, and a-f. The only other flags that can be combined with the `style` parameter are and . (The enumeration includes a composite number style, , that includes both white-space flags.) > [!NOTE] > If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. @@ -6098,7 +6098,7 @@ value Mod 2 = 0 ## Remarks The method returns 1 if the value of the exponent parameter is 0, or if the values of both the `value` and `exponent` parameters are 0. If `exponent` is 1, the method returns `value`. If `value` is negative, the method returns a negative result. - This method corresponds to the method for primitive numeric types. + This method corresponds to the method for primitive numeric types. @@ -6220,7 +6220,7 @@ value Mod 2 = 0 property is equivalent to the method for the primitive numeric types. + The property is equivalent to the method for the primitive numeric types. ]]> @@ -6333,7 +6333,7 @@ value Mod 2 = 0 Negative values are written to the array using two's complement representation in the most compact form possible. For example, -1 is represented as a single byte whose value is `0xFF` instead of as an array with multiple elements, such as `0xFF`, `0xFF` or `0xFF`, `0xFF`, `0xFF`, `0xFF`. - Because two's complement representation always interprets the highest-order bit of the last byte in the array (the byte at position `- 1`) as the sign bit, the method returns a byte array with an extra element whose value is zero to disambiguate positive values that could otherwise be interpreted as having their sign bits set. For example, the value 120 or `0x78` is represented as a single-byte array: `0x78`. However, 128, or `0x80`, is represented as a two-byte array: `0x80`, `0x00`. + Because two's complement representation always interprets the highest-order bit of the last byte in the array (the byte at position `- 1`) as the sign bit, the method returns a byte array with an extra element whose value is zero to disambiguate positive values that could otherwise be interpreted as having their sign bits set. For example, the value 120 or `0x78` is represented as a single-byte array: `0x78`. However, 128, or `0x80`, is represented as a two-byte array: `0x80`, `0x00`. You can round-trip a value by storing it to a byte array and then restoring it using the constructor. @@ -6450,7 +6450,7 @@ value Mod 2 = 0 |A specific format|Default (current) culture|| |A specific format|A specific culture|| - The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of the string returned by this method. If `provider` is `null`, the value is formatted using the object of the current culture. The only property of the object that controls the string representation of the value using the general format specifier is , which defines the character that represents the negative sign. + The `provider` parameter is an implementation. Its method returns a object that provides culture-specific information about the format of the string returned by this method. If `provider` is `null`, the value is formatted using the object of the current culture. The only property of the object that controls the string representation of the value using the general format specifier is , which defines the character that represents the negative sign. The `provider` parameter can be one of the following: @@ -6513,7 +6513,7 @@ value Mod 2 = 0 |Round-trip ("R") format|A specific culture|| |A specific format|A specific culture|| - The `format` parameter can be any valid [standard numeric string](~/docs/standard/base-types/standard-numeric-format-strings.md), or any combination of [custom numeric format strings](~/docs/standard/base-types/custom-numeric-format-strings.md). If `format` is equal to or is `null`, the return value of the current object is formatted with the round-trip format specifier ("R"). If `format` is any other value, the method throws a . + The `format` parameter can be any valid [standard numeric string](~/docs/standard/base-types/standard-numeric-format-strings.md), or any combination of [custom numeric format strings](~/docs/standard/base-types/custom-numeric-format-strings.md). If `format` is equal to or is `null`, the return value of the current object is formatted with the round-trip format specifier ("R"). If `format` is any other value, the method throws a . The .NET Framework provides extensive formatting support, which is described in greater detail in the following formatting topics: @@ -6580,7 +6580,7 @@ value Mod 2 = 0 |Round-trip ("R") format|A specific culture|| |A specific format|Default (current) culture|| - The `format` parameter can be any valid [standard numeric string](~/docs/standard/base-types/standard-numeric-format-strings.md), or any combination of [custom numeric format strings](~/docs/standard/base-types/custom-numeric-format-strings.md). If `format` is equal to or is `null`, the return value of the current object is formatted with the round-trip format specifier ("R"). If `format` is any other value, the method throws a . + The `format` parameter can be any valid [standard numeric string](~/docs/standard/base-types/standard-numeric-format-strings.md), or any combination of [custom numeric format strings](~/docs/standard/base-types/custom-numeric-format-strings.md). If `format` is equal to or is `null`, the return value of the current object is formatted with the round-trip format specifier ("R"). If `format` is any other value, the method throws a . The .NET Framework provides extensive formatting support, which is described in greater detail in the following formatting topics: @@ -6659,15 +6659,15 @@ value Mod 2 = 0 |Element|Description| |-------------|-----------------| |*ws*|Optional white space.| -|*sign*|An optional sign. Valid sign characters are determined by the and properties of the current culture.| +|*sign*|An optional sign. Valid sign characters are determined by the and properties of the current culture.| |*digits*|A sequence of decimal digits ranging from 0 to 9.| > [!NOTE] > The string specified by the `value` parameter cannot contain any group separators or decimal separator, and it cannot have a decimal portion. - The `value` parameter is interpreted by using the style. In addition to the decimal digits, only leading and trailing spaces with a leading sign are allowed. To explicitly define the style elements with the culture-specific formatting information that can be present in `value`, call the method. + The `value` parameter is interpreted by using the style. In addition to the decimal digits, only leading and trailing spaces with a leading sign are allowed. To explicitly define the style elements with the culture-specific formatting information that can be present in `value`, call the method. - The `value` parameter is parsed by using the formatting information in a object for the current culture. For more information, see . + The `value` parameter is parsed by using the formatting information in a object for the current culture. For more information, see . This overload interprets all digits in the `value` parameter as decimal digits. To parse the string representation of a hexadecimal number, call the overload instead. @@ -6739,18 +6739,18 @@ value Mod 2 = 0 |Element|Description| |-------------|-----------------| -|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, or at the end of `value` if `style` includes the flag.| -|*$*|A culture-specific currency symbol. Its position in the string is defined by the property of the object returned by the method of the `provider` parameter. The currency symbol can appear in `value` if `style` includes the flag.| -|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| +|*ws*|Optional white space. White space can appear at the start of `value` if `style` includes the flag, or at the end of `value` if `style` includes the flag.| +|*$*|A culture-specific currency symbol. Its position in the string is defined by the property of the object returned by the method of the `provider` parameter. The currency symbol can appear in `value` if `style` includes the flag.| +|*sign*|An optional sign. The sign can appear at the start of `value` if `style` includes the flag, and it can appear at the end of `value` if `style` includes the flag. Parentheses can be used in `value` to indicate a negative value if `style` includes the flag.| |*digits*|A sequence of digits from 0 through 9.| -|*,*|A culture-specific group separator. The group separator of the culture specified by `provider` can appear in `value` if `style` includes the flag.| -|*.*|A culture-specific decimal point symbol. The decimal point symbol of the culture specified by `provider` can appear in `value` if `style` includes the flag.| -|*fractional_digits*|One or more occurrences of the digit 0. Fractional digits can appear in `value` only if `style` includes the flag.| -|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| -|*exponential_digits*|A sequence of digits from 0 through 9. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| +|*,*|A culture-specific group separator. The group separator of the culture specified by `provider` can appear in `value` if `style` includes the flag.| +|*.*|A culture-specific decimal point symbol. The decimal point symbol of the culture specified by `provider` can appear in `value` if `style` includes the flag.| +|*fractional_digits*|One or more occurrences of the digit 0. Fractional digits can appear in `value` only if `style` includes the flag.| +|E|The "e" or "E" character, which indicates that the value is represented in exponential (scientific) notation. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| +|*exponential_digits*|A sequence of digits from 0 through 9. The `value` parameter can represent a number in exponential notation if `style` includes the flag.| |*hexdigits*|A sequence of hexadecimal digits from 0 through f, or 0 through F.| - A string with decimal digits only (which corresponds to the flag) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in this input string. The following table indicates how individual members affect the elements that may be present in `value`. + A string with decimal digits only (which corresponds to the flag) always parses successfully. Most of the remaining members control elements that may be present, but are not required to be present, in this input string. The following table indicates how individual members affect the elements that may be present in `value`. |Non-composite `NumberStyles` values|Elements permitted in value in addition to digits| |------------------------------------------|-------------------------------------------------------| @@ -6770,9 +6770,9 @@ value Mod 2 = 0 ||All elements. However, `value` cannot represent a hexadecimal number.| > [!IMPORTANT] -> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. +> If you use the method to round-trip the string representation of a value that was output by the method, you should use the method with the "R" format specifier to generate the string representation of the value. Otherwise, the string representation of the preserves only the 50 most significant digits of the original value, and data may be lost when you use the method to restore the value. - If the flag is used, `value` must be a hexadecimal value. The only other flags that can be present in `style` are and . (The enumeration has a composite style, , that includes both white-space flags.) + If the flag is used, `value` must be a hexadecimal value. The only other flags that can be present in `style` are and . (The enumeration has a composite style, , that includes both white-space flags.) > [!NOTE] > If `value` is the string representation of a hexadecimal number, it cannot be preceded by any decoration (such as `0x` or `&h`) that differentiates it as a hexadecimal number. This causes the conversion to fail. diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml index 6ef616a3a80d7..2cd4ec1c9cc3d 100644 --- a/xml/System.Numerics/Complex.xml +++ b/xml/System.Numerics/Complex.xml @@ -48,13 +48,13 @@ - By passing two values to its constructor. The first value represents the real part of the complex number, and the second value represents its imaginary part. These values represent the position of the complex number in the two-dimensional Cartesian coordinate system. -- By calling the static (`Shared` in Visual Basic) method to create a complex number from its polar coordinates. +- By calling the static (`Shared` in Visual Basic) method to create a complex number from its polar coordinates. - By assigning a , , , , , , , , , or value to a object. The value becomes the real part of the complex number, and its imaginary part equals 0. - By casting (in C#) or converting (in Visual Basic) a or value to a object. The value becomes the real part of the complex number, and its imaginary part equals 0. -- By assigning the complex number that is returned by a method or operator to a object. For example, is a static method that returns a complex number that is the sum of two complex numbers, and the operator adds two complex numbers and returns the result. +- By assigning the complex number that is returned by a method or operator to a object. For example, is a static method that returns a complex number that is the sum of two complex numbers, and the operator adds two complex numbers and returns the result. The following example demonstrates each of these five ways of assigning a value to a complex number. @@ -88,33 +88,33 @@ [!code-vb[System.Numerics.Complex.Class#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.class/vb/precision1.vb#6)] ## Complex Numbers, Infinity, and NaN - The real and imaginary parts of a complex number are represented by values. In addition to ranging from to , the real or imaginary part of a complex number can have a value of , , or . , , and all propagate in any arithmetic or trigonometric operation. + The real and imaginary parts of a complex number are represented by values. In addition to ranging from to , the real or imaginary part of a complex number can have a value of , , or . , , and all propagate in any arithmetic or trigonometric operation. - In the following example, division by produces a complex number whose real and imaginary parts are both . As a result, performing multiplication with this value also produces a complex number whose real and imaginary parts are . Similarly, performing a multiplication that overflows the range of the type produces a complex number whose real part is and whose imaginary part is . Subsequently performing division with this complex number returns a complex number whose real part is and whose imaginary part is . + In the following example, division by produces a complex number whose real and imaginary parts are both . As a result, performing multiplication with this value also produces a complex number whose real and imaginary parts are . Similarly, performing a multiplication that overflows the range of the type produces a complex number whose real part is and whose imaginary part is . Subsequently performing division with this complex number returns a complex number whose real part is and whose imaginary part is . [!code-csharp[System.Numerics.Complex.Class#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.class/cs/nan1.cs#3)] [!code-vb[System.Numerics.Complex.Class#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.class/vb/nan1.vb#3)] - Mathematical operations with complex numbers that are invalid or that overflow the range of the data type do not throw an exception. Instead, they return a , , or under the following conditions: + Mathematical operations with complex numbers that are invalid or that overflow the range of the data type do not throw an exception. Instead, they return a , , or under the following conditions: -- The division of a positive number by zero returns . +- The division of a positive number by zero returns . -- Any operation that overflows the upper bound of the data type returns . +- Any operation that overflows the upper bound of the data type returns . -- The division of a negative number by zero returns . +- The division of a negative number by zero returns . -- Any operation that overflows the lower bound of the data type returns . +- Any operation that overflows the lower bound of the data type returns . -- The division of a zero by zero returns . +- The division of a zero by zero returns . -- Any operation that is performed on operands whose values are , , or returns , , or , depending on the specific operation. +- Any operation that is performed on operands whose values are , , or returns , , or , depending on the specific operation. - Note that this applies to any intermediate calculations performed by a method. For example, the multiplication of `new Complex(9e308, 9e308) and new Complex(2.5, 3.5)` uses the formula (ac - bd) + (ad + bc)i. The calculation of the real component that results from the multiplication evaluates the expression 9e308 * 2.5 - 9e308 * 3.5. Each intermediate multiplication in this expression returns , and the attempt to subtract from returns . + Note that this applies to any intermediate calculations performed by a method. For example, the multiplication of `new Complex(9e308, 9e308) and new Complex(2.5, 3.5)` uses the formula (ac - bd) + (ad + bc)i. The calculation of the real component that results from the multiplication evaluates the expression 9e308 * 2.5 - 9e308 * 3.5. Each intermediate multiplication in this expression returns , and the attempt to subtract from returns . ## Formatting a Complex Number By default, the string representation of a complex number takes the form `(`*real*`,` *imaginary*`)`, where *real* and *imaginary* are the string representations of the values that form the complex number's real and imaginary components. Some overloads of the method allow customization of the string representations of these values to reflect the formatting conventions of a particular culture or to appear in a particular format defined by a standard or custom numeric format string. (For more information, see [Standard Numeric Format Strings](~/docs/standard/base-types/standard-numeric-format-strings.md) and [Custom Numeric Format Strings](~/docs/standard/base-types/custom-numeric-format-strings.md).) - One of the more common ways of expressing the string representation of a complex number takes the form a + bi, where a is the complex number's real component, and b is the complex number's imaginary component. In electrical engineering, a complex number is most commonly expressed as a + bj. You can return the string representation of a complex number in either of these two forms. To do this, define a custom format provider by implementing the and interfaces, and then call the method. + One of the more common ways of expressing the string representation of a complex number takes the form a + bi, where a is the complex number's real component, and b is the complex number's imaginary component. In electrical engineering, a complex number is most commonly expressed as a + bj. You can return the string representation of a complex number in either of these two forms. To do this, define a custom format provider by implementing the and interfaces, and then call the method. The following example defines a `ComplexFormatter` class that represents a complex number as a string in the form of either a + bi or a + bj. @@ -212,11 +212,11 @@ - If b = 0, the result is 0. -- If a > b, the result is a *(1 + b2/a2). +- If a > b, the result is a *(1 + b2/a2). -- If b > a, the result is b * (1 + a2/b2). +- If b > a, the result is b * (1 + a2/b2). - If the calculation of the absolute value results in an overflow, the method returns either or . If either the or property is and the other property is neither nor , the method returns . + If the calculation of the absolute value results in an overflow, the method returns either or . If either the or property is and the other property is neither nor , the method returns . @@ -263,7 +263,7 @@ method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula: @@ -320,7 +320,7 @@ (a + c) + (b + d)i. - If the method call results in an overflow in either the real or imaginary component, the value of the component is either or . + If the method call results in an overflow in either the real or imaginary component, the value of the component is either or . Languages that do not support custom operators can use the method to perform addition with complex numbers. @@ -369,7 +369,7 @@ method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula: @@ -420,7 +420,7 @@ method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula: @@ -518,7 +518,7 @@ method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula to calculate the cosine of the complex number a + bi: @@ -569,7 +569,7 @@ method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula to calculate the hyperbolic cosine of the complex number a + bi: @@ -618,7 +618,7 @@ ((ac + bd) / (c2 + d2)) + ((bc - ad) / (c2 + d2)i - If the calculation of the quotient results in an overflow in either the real or imaginary component, the value of that component is either or . + If the calculation of the quotient results in an overflow in either the real or imaginary component, the value of that component is either or . The method can be used by languages that do not support custom operators. Its behavior is identical to division using the division operator. @@ -784,7 +784,7 @@ ## Remarks Use the method to calculate the powers of other bases. - The method for complex numbers corresponds to the method for real numbers. is the inverse of . + The method for complex numbers corresponds to the method for real numbers. is the inverse of . @@ -837,7 +837,7 @@ Because there are multiple representations of a point on a complex plane, the return value of the method is normalized. The magnitude is normalized to a positive number, and the phase is normalized to a value in the range of - to . As a result, the values of the and properties of the resulting complex number may not equal the original values of the `magnitude` and `phase` parameters. - To convert a value from degrees to radians for the `phase` parameter, multiply it by /180. + To convert a value from degrees to radians for the `phase` parameter, multiply it by /180. @@ -993,7 +993,7 @@ method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. @@ -1042,7 +1042,7 @@ method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. ]]> @@ -1081,7 +1081,7 @@ method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. ]]> @@ -1118,9 +1118,9 @@ ## Remarks The property is equivalent to the absolute value of a complex number. It specifies the distance from the origin (the intersection of the x-axis and the y-axis in the Cartesian coordinate system) to the two-dimensional point represented by a complex number. The absolute value is calculated as follows: - | a + bi | = (a * a + b * b) + | a + bi | = (a * a + b * b) - If the calculation of the absolute value results in an overflow, this property returns either or . + If the calculation of the absolute value results in an overflow, this property returns either or . The and the properties define the position of a point that represents a complex number in the polar coordinate system. @@ -1177,7 +1177,7 @@ (ac - bd) + (ad + bc)i - If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either or . + If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either or . The method is implemented for languages that do not support custom operators. Its behavior is identical to multiplication using the multiplication operator. @@ -1323,11 +1323,11 @@ (a + c) + (b + d)i - If the method call results in an overflow in either the real or imaginary component, the value of that component is either or . + If the method call results in an overflow in either the real or imaginary component, the value of that component is either or . Languages that do not support custom operators can call the method instead. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example illustrates addition with complex numbers. @@ -1383,11 +1383,11 @@ ((ac + bd) / (c2 + d2)) + ((bc - ad) / (c2 + d2)i - If the division results in an overflow in either the real or imaginary component, the value of that component is either or . + If the division results in an overflow in either the real or imaginary component, the value of that component is either or . Languages that do not support custom operators and operator overloading can call the method instead. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -1441,7 +1441,7 @@ Note that, because of differences in precision, two complex numbers that are apparently equivalent can be considered unequal. For more information and a possible workaround, see the method. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2106,11 +2106,11 @@ This API is not CLS-compliant. (ac - bd) + (ad + bc)i - If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either or . + If the multiplication results in an overflow in either the real or imaginary component, the value of that component is either or . Languages that do not support custom operators can call the method instead. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2154,7 +2154,7 @@ This API is not CLS-compliant. [!code-csharp[System.Numerics.Complex.Subtract#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.subtract/cs/subtract2.cs#2)] [!code-vb[System.Numerics.Complex.Subtract#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.subtract/vb/subtract2.vb#2)] - If the method call results in an overflow in either the real or imaginary component, the value of that component is either or . + If the method call results in an overflow in either the real or imaginary component, the value of that component is either or . The subtraction of a complex number, c + di, from another complex number, a + bi, takes the following form: @@ -2162,7 +2162,7 @@ This API is not CLS-compliant. Languages that do not support custom operators can call the method instead. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2206,7 +2206,7 @@ This API is not CLS-compliant. The resulting complex number produces a value of 0 (zero) when it is added to the original complex number. Languages that do not support custom operators can call the method instead. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2239,13 +2239,13 @@ This API is not CLS-compliant. (b, a). + For a complex number a + bi, the phase is computed as (b, a). You can identify a complex number by its Cartesian coordinates on the complex plane or by its polar coordinates. The phase (argument) of a complex number is the angle to the real axis of a line drawn from the point of origin (the intersection of the x-axis and the y-axis) to the point represented by the complex number. The magnitude (represented by the property) is the distance from the point of origin to the point that is represented by the complex number. You can instantiate a complex number based on its polar coordinates instead of its Cartesian coordinates by calling the method. - To convert the phase from radians to degrees, multiply it by 180/. + To convert the phase from radians to degrees, multiply it by 180/. @@ -2294,9 +2294,9 @@ This API is not CLS-compliant. , the method returns . For other values, if `power` is 0, the method returns , and if `power` is 1, it returns `value`. + If `value` is , the method returns . For other values, if `power` is 0, the method returns , and if `power` is 1, it returns `value`. - This method corresponds to the method for primitive numeric types. + This method corresponds to the method for primitive numeric types. @@ -2420,14 +2420,14 @@ This API is not CLS-compliant. when the two numbers are multiplied. If a complex number is represented by a +bi, its reciprocal is represented by the expression a/(a2+b2) + -b/(a2 + b2). + The reciprocal, or multiplicative inverse, of a number *x* is a number *y* where *x* multiplied by *y* yields 1. The reciprocal of a complex number is the complex number that produces when the two numbers are multiplied. If a complex number is represented by a +bi, its reciprocal is represented by the expression a/(a2+b2) + -b/(a2 + b2). - If value is , the method returns . Otherwise, it returns the result of the expression /`value`. + If value is , the method returns . Otherwise, it returns the result of the expression /`value`. ## Examples - The following example uses the method to calculate the reciprocal values of several complex numbers. It also demonstrates that the result of multiplying a complex number by its reciprocal is . + The following example uses the method to calculate the reciprocal values of several complex numbers. It also demonstrates that the result of multiplying a complex number by its reciprocal is . [!code-csharp[System.Numerics.Complex.Reciprocal#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.numerics.complex.reciprocal/cs/reciprocal1.cs#1)] [!code-vb[System.Numerics.Complex.Reciprocal#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.numerics.complex.reciprocal/vb/reciprocal1.vb#1)] @@ -2469,7 +2469,7 @@ This API is not CLS-compliant. method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula to calculate the sine of the complex number a + bi: @@ -2520,7 +2520,7 @@ This API is not CLS-compliant. method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula to calculate the hyperbolic sine of the complex number a + bi: @@ -2565,9 +2565,9 @@ This API is not CLS-compliant. ## Remarks The square root of the complex number `value` is calculated by using the following formula: - ((`value`.), `value`./2.0) + ((`value`.), `value`./2.0) - The method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. ]]> @@ -2612,7 +2612,7 @@ This API is not CLS-compliant. (a - c) + (b - d)i - If the method call results in an overflow in either the real or imaginary component, the value of that component is either or . + If the method call results in an overflow in either the real or imaginary component, the value of that component is either or . Languages that do not support custom operators can use the method to perform subtraction using complex numbers. @@ -2661,7 +2661,7 @@ This API is not CLS-compliant. method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula to calculate the tangent of the complex number `value`: @@ -2712,7 +2712,7 @@ This API is not CLS-compliant. method for complex numbers corresponds to the method for real numbers. + The method for complex numbers corresponds to the method for real numbers. The method uses the following formula to calculate the hyperbolic tangent of the complex number `value`: @@ -2856,7 +2856,7 @@ This API is not CLS-compliant. or is `null`, the real and imaginary parts of the complex number are formatted with the general format specifier ("G"). If `format` is any other value, the method throws a . + The string representation of the complex number returned by this method displays the number using its Cartesian coordinates in the form `(`*a*`,` *b*`)`, where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the format string specified by `format`. The `format` parameter can be any valid standard numeric format specifier, or any combination of custom numeric format specifiers. If `format` is equal to or is `null`, the real and imaginary parts of the complex number are formatted with the general format specifier ("G"). If `format` is any other value, the method throws a . The .NET Framework provides extensive formatting support, which is described in greater detail in the following topics: @@ -2915,7 +2915,7 @@ This API is not CLS-compliant. or is `null`, the real and imaginary parts of the complex number are formatted with the general format specifier ("G"). If `format` is any other value, the method throws a . + The string representation of the complex number returned by this method displays the number using its Cartesian coordinates in the form `(`*a*`,` *b*`)`, where *a* is the real part of the complex number, and *b* is its imaginary part. Both *a* and *b* are formatted using the format string specified by `format`. The `format` parameter can be any valid standard numeric format specifier, or any combination of custom numeric format specifiers. If `format` is equal to or is `null`, the real and imaginary parts of the complex number are formatted with the general format specifier ("G"). If `format` is any other value, the method throws a . The .NET Framework provides extensive formatting support, which is described in greater detail in the following topics: diff --git a/xml/System.Numerics/Vector2.xml b/xml/System.Numerics/Vector2.xml index fe097673ba70f..a01c459d36978 100644 --- a/xml/System.Numerics/Vector2.xml +++ b/xml/System.Numerics/Vector2.xml @@ -1509,7 +1509,7 @@ " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current thread culture. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -1549,7 +1549,7 @@ " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and the current culture's formatting conventions. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -1591,7 +1591,7 @@ " characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and `formatProvider`. The "\<" and ">" characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. ]]> diff --git a/xml/System.Numerics/Vector3.xml b/xml/System.Numerics/Vector3.xml index 16bea3d38430c..edf39d746ca7b 100644 --- a/xml/System.Numerics/Vector3.xml +++ b/xml/System.Numerics/Vector3.xml @@ -1577,7 +1577,7 @@ " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current thread culture. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -1617,7 +1617,7 @@ " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and the current culture's formatting conventions. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -1659,7 +1659,7 @@ " characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and `formatProvider`. The "\<" and ">" characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. ]]> diff --git a/xml/System.Numerics/Vector4.xml b/xml/System.Numerics/Vector4.xml index c044fb03a5ebb..27b269cc5a32f 100644 --- a/xml/System.Numerics/Vector4.xml +++ b/xml/System.Numerics/Vector4.xml @@ -1549,7 +1549,7 @@ " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current thread culture. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -1589,7 +1589,7 @@ " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and the current culture's formatting conventions. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -1631,7 +1631,7 @@ " characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and `formatProvider`. The "\<" and ">" characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. ]]> diff --git a/xml/System.Numerics/Vector`1.xml b/xml/System.Numerics/Vector`1.xml index a8bc6bb4d3741..d7214118f1053 100644 --- a/xml/System.Numerics/Vector`1.xml +++ b/xml/System.Numerics/Vector`1.xml @@ -76,7 +76,7 @@ property returns `true`. + `value` can be any primitive numeric type (that is, a numeric type whose property returns `true`. ]]> @@ -146,7 +146,7 @@ elements from the specified index. + The array must contain at least [Vector(T) Constructor (T\ elements from the specified index. ]]> @@ -190,7 +190,7 @@ elements. + The copy operation begins at index 0 of `destination`. The destination array must have at least elements. ]]> @@ -1343,7 +1343,7 @@ property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current thread culture. The current culture's property followed by a space is used to separate each element. ]]> @@ -1380,7 +1380,7 @@ property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and the current culture's formatting conventions. The current culture's property followed by a space is used to separate each element. ]]> @@ -1419,7 +1419,7 @@ property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and `formatProvider`, and the format provider's property followed by a space is used to separate each element. ]]> diff --git a/xml/System.Printing/PrintCapabilities.xml b/xml/System.Printing/PrintCapabilities.xml index 4bd7a84bfd014..6a58d165d3717 100644 --- a/xml/System.Printing/PrintCapabilities.xml +++ b/xml/System.Printing/PrintCapabilities.xml @@ -590,7 +590,7 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) - In all other cases, the property's behavior is as follows. - The property of the property's object is the smallest of the following values. + The property of the property's object is the smallest of the following values. - The **MinValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option’s **ScaleWidth** `ScoredProperty`. @@ -598,7 +598,7 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) - The **MinValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option’s **Scale** `ScoredProperty`. - The property of the property's object is the largest of the following values. + The property of the property's object is the largest of the following values. - The **MaxValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option’s **ScaleWidth** `ScoredProperty`. diff --git a/xml/System.Printing/PrintPort.xml b/xml/System.Printing/PrintPort.xml index 5992ac81cf2e1..6eb6aa7c12fea 100644 --- a/xml/System.Printing/PrintPort.xml +++ b/xml/System.Printing/PrintPort.xml @@ -16,7 +16,7 @@ property holds the object that is assigned to the queue. + The property holds the object that is assigned to the queue. > [!CAUTION] > Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. diff --git a/xml/System.Printing/PrintQueue.xml b/xml/System.Printing/PrintQueue.xml index 2ecd9a88bf0fd..01ed2819c9950 100644 --- a/xml/System.Printing/PrintQueue.xml +++ b/xml/System.Printing/PrintQueue.xml @@ -323,7 +323,7 @@ ## Remarks Unless the queue is paused or in an error state, the job prints when it reaches the top of the queue, so this is a printing function. - Other ways to print in [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] include the method, which can be used with or without opening the dialog, and the many and methods of the . + Other ways to print in [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] include the method, which can be used with or without opening the dialog, and the many and methods of the . ]]> @@ -363,7 +363,7 @@ In the print queue's [!INCLUDE[TLA#tla_gui](~/includes/tlasharptla-gui-md.md)], the job has the name "Print System Document". To give the job a different name, use the overload. - Other ways to print in [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] include the method, which can be used with or without opening the dialog, and the many and methods of the . + Other ways to print in [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] include the method, which can be used with or without opening the dialog, and the many and methods of the . @@ -412,7 +412,7 @@ > [!CAUTION] > If the is not closed with before the end of the thread in which is called, then an is thrown when that thread ends because the spooler thread cannot gain control over the object. - Other ways to print in [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] include the method, which can be used with or without opening the dialog, and the many and methods of the . + Other ways to print in [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] include the method, which can be used with or without opening the dialog, and the many and methods of the . @@ -506,7 +506,7 @@ > [!NOTE] > You cannot apply the to any method except `Main` and you cannot use for the `Main` thread. - Other ways to print in [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] include the method, which can be used with or without opening the dialog, and the many and methods of the . + Other ways to print in [!INCLUDE[TLA#tla_winclient](~/includes/tlasharptla-winclient-md.md)] include the method, which can be used with or without opening the dialog, and the many and methods of the . @@ -1086,7 +1086,7 @@ method for the same purpose. + You can also use the method for the same purpose. diff --git a/xml/System.Printing/PrintQueueStream.xml b/xml/System.Printing/PrintQueueStream.xml index e260860db5fa8..0ee65970b4470 100644 --- a/xml/System.Printing/PrintQueueStream.xml +++ b/xml/System.Printing/PrintQueueStream.xml @@ -308,7 +308,7 @@ . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + This method overrides . Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). diff --git a/xml/System.Printing/PrintSystemJobInfo.xml b/xml/System.Printing/PrintSystemJobInfo.xml index 8669440e591de..c5e85a1699ded 100644 --- a/xml/System.Printing/PrintSystemJobInfo.xml +++ b/xml/System.Printing/PrintSystemJobInfo.xml @@ -16,7 +16,7 @@ object, use the static method or one of the following instance methods: , , or . + This class has no public constructor. To get a reference to a object, use the static method or one of the following instance methods: , , or . Many print job properties, such as whether a job is completed, must be passed from the printer to the object before your application reads the corresponding property (). The method provides this functionality. @@ -112,7 +112,7 @@ method for the same purpose. + You can also use the method for the same purpose. ]]> @@ -432,7 +432,7 @@ can be `false` even when the value of the property is `true`. + The entire print queue can also be paused. For example, the value of can be `false` even when the value of the property is `true`. @@ -990,9 +990,9 @@ object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is earlier than is changed to the value of . + This value is propagated to each object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is earlier than is changed to the value of . - After the job is added to the queue, it can be given a new value through the [!INCLUDE[TLA#tla_win](~/includes/tlasharptla-win-md.md)] [!INCLUDE[TLA#tla_ui](~/includes/tlasharptla-ui-md.md)], provided that it is not earlier than . + After the job is added to the queue, it can be given a new value through the [!INCLUDE[TLA#tla_win](~/includes/tlasharptla-win-md.md)] [!INCLUDE[TLA#tla_ui](~/includes/tlasharptla-ui-md.md)], provided that it is not earlier than . If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. @@ -1099,9 +1099,9 @@ object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is later than is changed to the value of . + This value is propagated to each object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is later than is changed to the value of . - After the job is added to the queue, it can be given a new value through the [!INCLUDE[TLA#tla_win](~/includes/tlasharptla-win-md.md)] [!INCLUDE[TLA#tla_ui](~/includes/tlasharptla-ui-md.md)], provided that it is not later than . + After the job is added to the queue, it can be given a new value through the [!INCLUDE[TLA#tla_win](~/includes/tlasharptla-win-md.md)] [!INCLUDE[TLA#tla_ui](~/includes/tlasharptla-ui-md.md)], provided that it is not later than . If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. diff --git a/xml/System.Reflection.Emit/AssemblyBuilder.xml b/xml/System.Reflection.Emit/AssemblyBuilder.xml index f07ce326489ba..ea5a295f38856 100644 --- a/xml/System.Reflection.Emit/AssemblyBuilder.xml +++ b/xml/System.Reflection.Emit/AssemblyBuilder.xml @@ -45,7 +45,7 @@ The signing of a dynamic assembly using is not effective until the assembly is saved to disk. So, strong names will not work with transient dynamic assemblies. - To get an object, use the method. + To get an object, use the method. ## Reflection emit dynamic assembly scenarios The following are some things to consider when using the class to create dynamic assemblies. @@ -62,26 +62,26 @@ ### Dynamic assembly access modes Dynamic assemblies can be created using one of the following access modes: -- +- The dynamic assembly represented by an object is transient. The dynamic assembly can only be used to execute the emitted code. -- +- The dynamic assembly represented by an object is persistable but cannot be executed until the saved portable executable (PE) file has been loaded from disk. -- +- The dynamic assembly represented by an object is persistable, but can also be executed before and/or after the assembly is saved to disk. - The access mode must be specified by providing the appropriate value in the call to the method when the dynamic assembly is defined and cannot be changed later. The runtime uses the access mode of a dynamic assembly to optimize the assembly's internal representation. + The access mode must be specified by providing the appropriate value in the call to the method when the dynamic assembly is defined and cannot be changed later. The runtime uses the access mode of a dynamic assembly to optimize the assembly's internal representation. ## Examples The following code example shows how to define a dynamic assembly with one module. The module in the example assembly contains one type, `MyDynamicType`, which has a private field, a property that gets and sets the private field, constructors that initialize the private field, and a method that multiplies a user-supplied number by the private field value and returns the result. - is specified when the assembly is created. The assembly code is used immediately, and the assembly is also saved to disk so that it can be examined with [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) or used in another program. + is specified when the assembly is created. The assembly code is used immediately, and the assembly is also saved to disk so that it can be examined with [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) or used in another program. [!code-cpp[AssemblyBuilderClass#1](~/samples/snippets/cpp/VS_Snippets_CLR/AssemblyBuilderClass/cpp/24895.cpp#1)] [!code-csharp[AssemblyBuilderClass#1](~/samples/snippets/csharp/VS_Snippets_CLR/AssemblyBuilderClass/cs/24895.cs#1)] @@ -139,7 +139,7 @@ The specified resource file must be in the directory where the assembly will be saved. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -208,7 +208,7 @@ The specified resource file must be in the directory where the assembly will be saved. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -263,7 +263,7 @@ property. + To get the absolute path to the loaded manifest-containing file, use the property. ]]> @@ -389,7 +389,7 @@ > To suppress optimizations when debugging dynamic modules, apply the attribute to the dynamic assembly before calling . Create an instance of with the flag and apply it using the method. The attribute must be applied to the dynamic assembly. It has no effect if applied to the module. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -460,7 +460,7 @@ > To suppress optimizations when debugging dynamic modules, apply the attribute to the dynamic assembly before calling . Create an instance of with the flag and apply it using the method. The attribute must be applied to the dynamic assembly. It has no effect if applied to the module. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -524,7 +524,7 @@ ## Remarks To define a persistable dynamic module, this assembly needs to be created with the or the attribute. - If you want the module to contain the assembly manifest, `name` should be the same as the name of the assembly (that is, the property of the used to create the dynamic assembly) and `fileName` should be the same as the filename you specify when you save the assembly. + If you want the module to contain the assembly manifest, `name` should be the same as the name of the assembly (that is, the property of the used to create the dynamic assembly) and `fileName` should be the same as the filename you specify when you save the assembly. In an assembly with only one module, that module should contain the assembly manifest. @@ -532,7 +532,7 @@ > To suppress optimizations when debugging dynamic modules, apply the attribute to the dynamic assembly before calling . Create an instance of with the flag and apply it using the method. The attribute must be applied to the dynamic assembly. It has no effect if applied to the module. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -604,7 +604,7 @@ ## Remarks To define a persistable dynamic module, this assembly needs to be created with the or the attribute. - If you want the module to contain the assembly manifest, `name` should be the same as the name of the assembly (that is, the property of the used to create the dynamic assembly) and `fileName` should be the same as the filename you specify when you save the assembly. + If you want the module to contain the assembly manifest, `name` should be the same as the name of the assembly (that is, the property of the used to create the dynamic assembly) and `fileName` should be the same as the filename you specify when you save the assembly. In an assembly with only one module, that module should contain the assembly manifest. @@ -612,7 +612,7 @@ > To suppress optimizations when debugging dynamic modules, apply the attribute to the dynamic assembly before calling . Create an instance of with the flag and apply it using the method. The attribute must be applied to the dynamic assembly. It has no effect if applied to the module. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -689,7 +689,7 @@ The runtime calls the method when the dynamic assembly is saved. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -764,7 +764,7 @@ The runtime calls the method when the dynamic assembly is saved. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -858,7 +858,7 @@ An assembly can be associated with only one unmanaged resource. This means that calling or after either one of the methods was called previously will throw the System.ArgumentException. Multiple unmanaged resources need to be merged with a tool such as the Microsoft ResMerge utility (not supplied with the common language runtime). > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -920,7 +920,7 @@ The information is inferred from the `AssemblyName` object used to define this dynamic assembly. This assembly's custom attributes override information specified in the `AssemblyName` object. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -980,7 +980,7 @@ The structure of the version resource includes data that identifies the version, language, and distribution of the file. Installation programs use the functions in the file installation library (VER.DLL) to retrieve the version information resource from a file and to extract the version information blocks from the resource. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1173,7 +1173,7 @@ and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. + Use this method to examine the custom attributes of code in the reflection-only context, in cases where the custom attributes themselves are defined in code that is loaded into the reflection-only context. Methods such as and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. ]]> @@ -1569,7 +1569,7 @@ ## Remarks This method does not return a complete list of referenced assemblies. For example, if you apply a custom attribute to the , the assembly in which the attribute was defined is included in the list returned by this method. However, if you use a object to specify the type of a method parameter, that type is not included. - To get a complete list of referenced assemblies, save the assembly, load it into another application domain, and call the method. + To get a complete list of referenced assemblies, save the assembly, load it into another application domain, and call the method. ]]> @@ -1925,10 +1925,10 @@ when you create the . If a dynamic assembly is emitted in the reflection-only context, its code cannot be executed. + To emit a dynamic assembly in the reflection-only context, specify when you create the . If a dynamic assembly is emitted in the reflection-only context, its code cannot be executed. > [!NOTE] -> After you have saved a dynamic assembly to disk, you can use the method to load the completed assembly into the reflection-only context. However, the assembly can no longer be modified. +> After you have saved a dynamic assembly to disk, you can use the method to load the completed assembly into the reflection-only context. However, the assembly can no longer be modified. ]]> @@ -2034,7 +2034,7 @@ with , is ignored. + If `imageFileMachine` and `portableExecutableKind` are incompatible, `imageFileMachine` takes precedence over `portableExecutableKind`. No exception is thrown. For example, if you specify with , is ignored. This method saves all non-transient dynamic modules defined in this dynamic assembly. Transient dynamic modules are not saved. The assembly file name can be the same as the name of one of the module. If so, the assembly manifest is stored within that module. `assemblyFileName` can be different from the names of all of the modules contained within the assembly. If so, the assembly file contains only the assembly manifest. @@ -2094,7 +2094,7 @@ ) for the dynamic assemblies it generates. + The [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)] always enforces level 2 transparency () for the dynamic assemblies it generates. ]]> @@ -2133,7 +2133,7 @@ > cannot be used to set declarative security attributes. Use one of the overloads of that takes required, optional, and refused permissions. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -2195,7 +2195,7 @@ > cannot be used to set declarative security attributes. Use one of the overloads of that takes required, optional, and refused permissions. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -2271,7 +2271,7 @@ ## Remarks > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> diff --git a/xml/System.Reflection.Emit/ConstructorBuilder.xml b/xml/System.Reflection.Emit/ConstructorBuilder.xml index 4db682494ac5b..742f8311fcabb 100644 --- a/xml/System.Reflection.Emit/ConstructorBuilder.xml +++ b/xml/System.Reflection.Emit/ConstructorBuilder.xml @@ -43,9 +43,9 @@ If you use to define a constructor for your dynamic type, a default constructor is not provided. You have the following options for providing a default constructor in addition to the constructor you defined: -- If you want a default constructor that simply calls the default constructor of the base class, you can use the method to create one (and optionally restrict access to it). Do not provide an implementation for this default constructor. If you do, an exception is thrown when you try to use the constructor. No exception is thrown when the method is called. +- If you want a default constructor that simply calls the default constructor of the base class, you can use the method to create one (and optionally restrict access to it). Do not provide an implementation for this default constructor. If you do, an exception is thrown when you try to use the constructor. No exception is thrown when the method is called. -- If you want a default constructor that does something more than simply calling the default constructor of the base class, or that calls another constructor of the base class, or that does something else entirely, you must use the method to create a , and provide your own implementation. +- If you want a default constructor that does something more than simply calling the default constructor of the base class, or that calls another constructor of the base class, or that does something else entirely, you must use the method to create a , and provide your own implementation. @@ -520,7 +520,7 @@ method has been called. In the .NET Framework versions 1.0 and 1.1, is thrown. In the .NET Framework version 2.0, is thrown. + This property is not supported until after the method has been called. In the .NET Framework versions 1.0 and 1.1, is thrown. In the .NET Framework version 2.0, is thrown. diff --git a/xml/System.Reflection.Emit/DynamicILInfo.xml b/xml/System.Reflection.Emit/DynamicILInfo.xml index be734fe5bfb96..e38020e128e41 100644 --- a/xml/System.Reflection.Emit/DynamicILInfo.xml +++ b/xml/System.Reflection.Emit/DynamicILInfo.xml @@ -24,7 +24,7 @@ ## Remarks The class allows developers to write their own MSIL generators instead of using . - To create instances of other types, call methods, and so on, the MSIL you generate must include tokens for those entities. The class provides several overloads of the method, which return tokens valid in the scope of the current . For example, if you need to call an overload of the method, you can obtain a for that overload and pass it to the method to obtain a token to embed in your MSIL. + To create instances of other types, call methods, and so on, the MSIL you generate must include tokens for those entities. The class provides several overloads of the method, which return tokens valid in the scope of the current . For example, if you need to call an overload of the method, you can obtain a for that overload and pass it to the method to obtain a token to embed in your MSIL. Once you have created arrays for your local variable signature, exceptions, and code body, you can use the , , and methods to insert them into the associated with your object. @@ -147,7 +147,7 @@ object. Use the method to get a for the field you want to access, then use the property to get the . + You must obtain a token for any field that will be accessed by the dynamic method associated with the current object. Use the method to get a for the field you want to access, then use the property to get the . ]]> @@ -177,7 +177,7 @@ object. Use the method to get a for the method you want to access, and then use the property to get the . + You must obtain a token for any method that will be accessed by the dynamic method associated with the current object. Use the method to get a for the method you want to access, and then use the property to get the . > [!NOTE] > For a method that belongs to a generic type, use the method overload and specify a for the generic type. @@ -212,7 +212,7 @@ ## Remarks The token returned by this method overload allows you to define a local variable type, and emit MSIL to create an instance of a type in the dynamic method associated with the current object. - To get a representing a type, use the property. + To get a representing a type, use the property. ]]> @@ -267,7 +267,7 @@ object. Use the method to get a for the field you want to access, and then use the property to get the . + You must obtain a token for any field that will be accessed by the dynamic method associated with the current object. Use the method to get a for the field you want to access, and then use the property to get the . ]]> @@ -299,7 +299,7 @@ object. Use the method to get a for the method you want to call, and then use the property to get the . + You must obtain a token for any method that will be called by the dynamic method associated with the current object. Use the method to get a for the method you want to call, and then use the property to get the . ]]> @@ -482,7 +482,7 @@ method to get a for the local signature. + The local variable signature describes the layout of a method's local variables. To simplify construction of the local variable signature, use the `static` (`Shared` in Visual Basic) method to get a for the local signature. For information on local variable signatures, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the Ecma International Web site. @@ -520,7 +520,7 @@ method to get a for the local signature. + The local variable signature describes the layout of a method's local variables. To simplify construction of the local variable signature, use the `static` (`Shared` in Visual Basic) method to get a for the local signature. For information on local variable signatures, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the Ecma International Web site. diff --git a/xml/System.Reflection.Emit/DynamicMethod.xml b/xml/System.Reflection.Emit/DynamicMethod.xml index 59bee0b475e69..f0a1b96c1c751 100644 --- a/xml/System.Reflection.Emit/DynamicMethod.xml +++ b/xml/System.Reflection.Emit/DynamicMethod.xml @@ -31,9 +31,9 @@ A dynamic method can be anonymously hosted, or it can belogically associated with a module or with a type. -- If the dynamic method is anonymously hosted, it is located in a system-provided assembly, and therefore is isolated from other code. By default, it does not have access to any non-public data. An anonymously hosted dynamic method can have restricted ability to skip the JIT compiler's visibility checks, if it has been granted with the flag. The trust level of the assembly whose non-public members are accessed by the dynamic method must be equal to, or a subset of, the trust level of the call stack that emitted the dynamic method. For more information about anonymously hosted dynamic methods, see [Walkthrough: Emitting Code in Partial Trust Scenarios](~/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md). +- If the dynamic method is anonymously hosted, it is located in a system-provided assembly, and therefore is isolated from other code. By default, it does not have access to any non-public data. An anonymously hosted dynamic method can have restricted ability to skip the JIT compiler's visibility checks, if it has been granted with the flag. The trust level of the assembly whose non-public members are accessed by the dynamic method must be equal to, or a subset of, the trust level of the call stack that emitted the dynamic method. For more information about anonymously hosted dynamic methods, see [Walkthrough: Emitting Code in Partial Trust Scenarios](~/docs/framework/reflection-and-codedom/walkthrough-emitting-code-in-partial-trust-scenarios.md). -- If the dynamic method is associated with a module that you specify, the dynamic method is effectively global to that module. It can access all types in the module and all `internal` (`Friend` in Visual Basic) members of the types. You can associate a dynamic method with any module, regardless of whether you created the module, provided that a demand for with the flag can be satisfied by the call stack that includes your code. If the flag is included in the grant, the dynamic method can skip the JIT compiler's visibility checks and access the private data of all types declared in the module or in any other module in any assembly. +- If the dynamic method is associated with a module that you specify, the dynamic method is effectively global to that module. It can access all types in the module and all `internal` (`Friend` in Visual Basic) members of the types. You can associate a dynamic method with any module, regardless of whether you created the module, provided that a demand for with the flag can be satisfied by the call stack that includes your code. If the flag is included in the grant, the dynamic method can skip the JIT compiler's visibility checks and access the private data of all types declared in the module or in any other module in any assembly. > [!NOTE] > When you specify the module with which a dynamic method is associated, that module must not be in the system-provided assembly that is used for anonymous hosting. @@ -48,7 +48,7 @@ |Skipping JIT visibility checks, with restrictions|Public members of public types in any assembly.|All members of all types, only in assemblies whose trust levels are equal to or less than the trust level of the assembly that emitted the dynamic method.| > [!NOTE] -> Prior to the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], emitting code required with the flag. This permission is included by default in the FullTrust and LocalIntranet named permission sets, but not in the Internet permission set. Therefore, in earlier versions of the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] a library can be used with Internet permissions only if it has the attribute and also executes an for . Such libraries require careful security review because coding errors could result in security holes. The [!INCLUDE[net_v20SP1_short](~/includes/net-v20sp1-short-md.md)] allows code to be emitted in partial trust scenarios without issuing any security demands, because generating code is not inherently a privileged operation. That is, the generated code has no more permissions than the assembly that emits it. This allows libraries that emit code to be security transparent and removes the need to assert , which simplifies the task of writing a secure library. To use this feature, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Prior to the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], emitting code required with the flag. This permission is included by default in the FullTrust and LocalIntranet named permission sets, but not in the Internet permission set. Therefore, in earlier versions of the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)] a library can be used with Internet permissions only if it has the attribute and also executes an for . Such libraries require careful security review because coding errors could result in security holes. The [!INCLUDE[net_v20SP1_short](~/includes/net-v20sp1-short-md.md)] allows code to be emitted in partial trust scenarios without issuing any security demands, because generating code is not inherently a privileged operation. That is, the generated code has no more permissions than the assembly that emits it. This allows libraries that emit code to be security transparent and removes the need to assert , which simplifies the task of writing a secure library. To use this feature, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. The following table shows which types and members are accessible to a dynamic method that is associated with a module or with a type in a module. @@ -127,7 +127,7 @@ When an anonymously hosted dynamic method is constructed, the call stack of the emitting assembly is included. When the method is invoked, the permissions of the emitting assembly are used instead of the permissions of the actual caller. Thus, the dynamic method cannot execute at a higher level of privilege than that of the assembly that emitted it, even if it is passed to and executed by an assembly that has a higher trust level. - This constructor specifies the method attributes and , and the calling convention . + This constructor specifies the method attributes and , and the calling convention . > [!NOTE] > This constructor was introduced in the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -181,7 +181,7 @@ - The target members belong to an assembly that has a level of trust equal to or lower than the call stack that emits the dynamic method. -- The call stack that emits the dynamic method is granted with the flag. This is always true when the code is executed with full trust. For partially trusted code, it is true only if the host explicitly grants the permission. +- The call stack that emits the dynamic method is granted with the flag. This is always true when the code is executed with full trust. For partially trusted code, it is true only if the host explicitly grants the permission. > [!IMPORTANT] > If the permission has not been granted, a security exception is thrown when is called or when the dynamic method is invoked, not when this constructor is called. No special permissions are required to emit the dynamic method. @@ -192,7 +192,7 @@ When an anonymously hosted dynamic method is constructed, the call stack of the emitting assembly is included. When the method is invoked, the permissions of the emitting call stack are used instead of the permissions of the actual caller. Thus, the dynamic method cannot execute at a higher level of privilege than that of the assembly that emitted it, even if it is passed to and executed by an assembly that has a higher trust level. - This constructor specifies the method attributes and , and the calling convention . + This constructor specifies the method attributes and , and the calling convention . > [!NOTE] > This constructor was introduced in the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -237,15 +237,15 @@ and , calling convention , and does not skip just-in-time (JIT) visibility checks. + This constructor specifies method attributes and , calling convention , and does not skip just-in-time (JIT) visibility checks. The dynamic method created with this constructor has access to public and `internal` (`Friend` in Visual Basic) members of all the types contained in module `m`. > [!NOTE] -> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. +> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -307,13 +307,13 @@ ## Remarks The dynamic method created with this constructor has access to all members of the type `owner`, and to public and `internal` (`Friend` in Visual Basic) members of all the other types in the module that contains `owner`. - This constructor specifies method attributes and , calling convention , and does not skip just-in-time (JIT) visibility checks. + This constructor specifies method attributes and , calling convention , and does not skip just-in-time (JIT) visibility checks. > [!NOTE] -> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. +> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -330,7 +330,7 @@ The example code creates an instance of `Example` and then creates two delegates. The first is of type `UseLikeStatic`, which has the same parameters as the dynamic method. The second is of type `UseLikeInstance`, which lacks the first parameter (of type `Example`). This delegate is created using the method overload; the second parameter of that method overload is an instance of `Example`, in this case the instance just created, which is bound to the newly created delegate. Whenever that delegate is invoked, the dynamic method acts on the bound instance of `Example`. > [!NOTE] -> This is an example of the relaxed rules for delegate binding introduced in the [!INCLUDE[dnprdnlong](~/includes/dnprdnlong-md.md)], along with new overloads of the method. For more information, see the class. +> This is an example of the relaxed rules for delegate binding introduced in the [!INCLUDE[dnprdnlong](~/includes/dnprdnlong-md.md)], along with new overloads of the method. For more information, see the class. The `UseLikeStatic` delegate is invoked, passing in the instance of `Example` that is bound to the `UseLikeInstance` delegate. Then the `UseLikeInstance` delegate is invoked, so that both delegates act on the same instance of `Example`. The changes in the values of the internal field are displayed after each call. Finally, a `UseLikeInstance` delegate is bound to an instance of `DerivedFromxample`, and the delegate calls are repeated. @@ -389,15 +389,15 @@ and , and calling convention . + This constructor specifies method attributes and , and calling convention . The dynamic method created with this constructor has access to public and `internal` (`Friend` in Visual Basic) members of all the types in contained module `m`. Skipping the JIT compiler's visibility checks allows the dynamic method to access private and protected members of all other types as well. This is useful, for example, when writing code to serialize objects. > [!NOTE] -> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. +> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -453,13 +453,13 @@ ## Remarks The dynamic method created with this constructor has access to all members of the type `owner`, and to public and `internal` (`Friend` in Visual Basic) members of all the other types in the module that contains `owner`. Skipping the JIT compiler's visibility checks allows the dynamic method to access private and protected members of all other types as well. This is useful, for example, when writing code to serialize objects. - This constructor specifies method attributes and , and calling convention . + This constructor specifies method attributes and , and calling convention . > [!NOTE] -> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. +> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -522,10 +522,10 @@ Skipping the JIT compiler's visibility checks allows the dynamic method to access private and protected members of all other types in the module and in all other assemblies as well. This is useful, for example, when writing code to serialize objects. > [!NOTE] -> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. +> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `m` is a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -596,10 +596,10 @@ The dynamic method created with this constructor has access to all members of the type `owner`, and to public and `internal` (`Friend` in Visual Basic) members of all the types contained in the module that contains `owner`. Skipping the JIT compiler's visibility checks allows the dynamic method to access private and protected members of all other types as well. This is useful, for example, when writing code to serialize objects. > [!NOTE] -> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. +> For backward compatibility, this constructor demands with the flag if the following conditions are both true: `owner` is in a module other than the calling module, and the demand for with the flag has failed. If the demand for succeeds, the operation is allowed. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -820,7 +820,7 @@ The example code creates an instance of `Example` and then creates two delegates. The first is of type `UseLikeStatic`, which has the same parameters as the dynamic method. The second is of type `UseLikeInstance`, which lacks the first parameter (of type `Example`). This delegate is created using the method overload; the second parameter of that method overload is an instance of `Example`, in this case the instance just created, which is bound to the newly created delegate. Whenever that delegate is invoked, the dynamic method acts on the bound instance of `Example`. > [!NOTE] -> This is an example of the relaxed rules for delegate binding introduced in the [!INCLUDE[dnprdnext](~/includes/dnprdnext-md.md)], along with new overloads of the method. For more information, see the class. +> This is an example of the relaxed rules for delegate binding introduced in the [!INCLUDE[dnprdnext](~/includes/dnprdnext-md.md)], along with new overloads of the method. For more information, see the class. The `UseLikeStatic` delegate is invoked, passing in the instance of `Example` that is bound to the `UseLikeInstance` delegate. Then the `UseLikeInstance` delegate is invoked, so that both delegates act on the same instance of `Example`. The changes in the values of the internal field are displayed after each call. Finally, a `UseLikeInstance` delegate is bound to an instance of `DerivedFromxample`, and the delegate calls are repeated. @@ -1324,7 +1324,7 @@ > [!NOTE] > This method overload is called by the method overload inherited from the class, so the preceding remarks apply to both overloads. - This method does not demand permissions directly, but invoking the dynamic method can result in security demands, depending on the method. For example, no demands are made for anonymously hosted dynamic methods that are created with the `restrictedSkipVisibility` parameter set to `false`. On the other hand, if you create a method with `restrictedSkipVisibility` set to `true` so it can access a hidden member of a target assembly, the method will cause a demand for the permissions of the target assembly plus with the flag. + This method does not demand permissions directly, but invoking the dynamic method can result in security demands, depending on the method. For example, no demands are made for anonymously hosted dynamic methods that are created with the `restrictedSkipVisibility` parameter set to `false`. On the other hand, if you create a method with `restrictedSkipVisibility` set to `true` so it can access a hidden member of a target assembly, the method will cause a demand for the permissions of the target assembly plus with the flag. > [!NOTE] > Prior to the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method required with the flag. @@ -1795,7 +1795,7 @@ . + If `null` was specified for the return type when the dynamic method was created, this property returns . diff --git a/xml/System.Reflection.Emit/EnumBuilder.xml b/xml/System.Reflection.Emit/EnumBuilder.xml index 4d1a5d959334f..7d5a7fc2b05aa 100644 --- a/xml/System.Reflection.Emit/EnumBuilder.xml +++ b/xml/System.Reflection.Emit/EnumBuilder.xml @@ -555,7 +555,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the constructor of a finished type, you can retrieve the type using or and use reflection on the retrieved type. ]]> @@ -590,7 +590,7 @@ and call on the returned . + As a workaround, to retrieve the custom attributes of a finished type, retrieve the type using and call on the returned . The following code sample illustrates the use of `GetCustomAttribute` in the context of . @@ -633,7 +633,7 @@ and call on the returned . + As a workaround, to retrieve the custom attributes of a finished type, retrieve the type using and call on the returned . The following code sample illustrates the use of `GetCustomAttribute` in the context of . @@ -726,7 +726,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the event of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -758,7 +758,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the events of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -793,7 +793,7 @@ or and use reflection on the retrieved type to retrieve the events. + As a workaround, to retrieve the events of a finished type, retrieve the type using or and use reflection on the retrieved type to retrieve the events. ]]> @@ -830,7 +830,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the field of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -865,7 +865,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the field of a finished type, retrieve the type using or and use reflection on the retrieved type. The method does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned, because that order can vary. @@ -942,7 +942,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the interface of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -982,7 +982,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the interface mapping types of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -1014,7 +1014,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the interface of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -1052,7 +1052,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the member of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -1087,7 +1087,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the members of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -1159,7 +1159,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the methods of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -1200,7 +1200,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the nested type of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -1237,7 +1237,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the nested types of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -1272,7 +1272,7 @@ or and use reflection on the retrieved type. + As a workaround, to retrieve the properties of a finished type, retrieve the type using or and use reflection on the retrieved type. ]]> @@ -1418,7 +1418,7 @@ or and use reflection on the retrieved type. + You can retrieve the type using or and use reflection on the retrieved type. ]]> @@ -2326,7 +2326,7 @@ or and use reflection on the retrieved type. + You can retrieve the type using or and use reflection on the retrieved type. Use this handle to access the underlying metadata handle. diff --git a/xml/System.Reflection.Emit/EventToken.xml b/xml/System.Reflection.Emit/EventToken.xml index 1dc81f9ef9759..a4e169fffddfc 100644 --- a/xml/System.Reflection.Emit/EventToken.xml +++ b/xml/System.Reflection.Emit/EventToken.xml @@ -130,7 +130,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -158,7 +158,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/FieldToken.xml b/xml/System.Reflection.Emit/FieldToken.xml index 00a5c5ef2a072..0ab225faf6951 100644 --- a/xml/System.Reflection.Emit/FieldToken.xml +++ b/xml/System.Reflection.Emit/FieldToken.xml @@ -130,7 +130,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -158,7 +158,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml b/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml index c30b13ff0ec3e..b9aa8e29271b5 100644 --- a/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml +++ b/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml @@ -28,7 +28,7 @@ objects by using the method to add type parameters to a dynamic type, thus making it a generic type, or by using the method to add type parameters to a dynamic method. Use the objects to add constraints to the type parameters. Constraints are of three kinds: + You can get an array of objects by using the method to add type parameters to a dynamic type, thus making it a generic type, or by using the method to add type parameters to a dynamic method. Use the objects to add constraints to the type parameters. Constraints are of three kinds: - The base type constraint specifies that any type assigned to the generic type parameter must derive from a particular base type. Set this constraint by using the method. @@ -36,7 +36,7 @@ - Special constraints specify that any type assigned to the generic type parameter must have a default constructor, must be a reference type, or must be a value type. Set the special constraints for a type parameter by using the method. - Interface constraints and special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameters, you can use its object to reflect the constraints. Use the method to get the type parameters, and for each type parameter use the method to get the base type constraint and interface constraints, and the property to get the special constraints. + Interface constraints and special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameters, you can use its object to reflect the constraints. Use the method to get the type parameters, and for each type parameter use the method to get the base type constraint and interface constraints, and the property to get the special constraints. @@ -2253,7 +2253,7 @@ ## Remarks To retrieve the base type constraint use the property. - Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameter and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method, and get the special constraints by using the property. + Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameter and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method, and get the special constraints by using the property. @@ -2371,7 +2371,7 @@ ## Remarks Special constraints can specify that any type assigned to the generic type parameter must have a default constructor, must be a reference type, or must be a value type. - Special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. To get the special constraints for each type parameter, use the property. + Special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. To get the special constraints for each type parameter, use the property. The enumeration values that refer to the variance characteristics of a type parameter are relevant only in languages that support covariance and contravariance, such as Microsoft intermediate language (MSIL). Visual Basic and C# currently do not support covariance and contravariance. @@ -2427,7 +2427,7 @@ class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method. + Interface constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method. diff --git a/xml/System.Reflection.Emit/ILGenerator.xml b/xml/System.Reflection.Emit/ILGenerator.xml index 928fac01c31be..470f978170e10 100644 --- a/xml/System.Reflection.Emit/ILGenerator.xml +++ b/xml/System.Reflection.Emit/ILGenerator.xml @@ -37,7 +37,7 @@ is used to generate method bodies for methods and constructors in dynamic assemblies (represented by the and classes) and for standalone dynamic methods (represented by the class). To obtain an , use the , , and methods. + is used to generate method bodies for methods and constructors in dynamic assemblies (represented by the and classes) and for standalone dynamic methods (represented by the class). To obtain an , use the , , and methods. MSIL is used as input to a just-in-time (JIT) compiler. @@ -955,7 +955,7 @@ The location of `meth` is recorded so that the instruction stream can be patched if necessary when persisting the module to a portable executable (PE) file. - If `meth` represents a generic method, it must be a generic method definition. That is, its property must be `true`. + If `meth` represents a generic method, it must be a generic method definition. That is, its property must be `true`. ]]> @@ -1255,7 +1255,7 @@ ## Remarks Use to put a instruction onto the stream. Do not use . - If `optionalParameterTypes` specifies optional arguments, `callingConvention` must include the flag. + If `optionalParameterTypes` specifies optional arguments, `callingConvention` must include the flag. ]]> @@ -1291,7 +1291,7 @@ method. + The type of `localBuilder` must match the parameter type of an overload of the method. @@ -1341,7 +1341,7 @@ method. + The type of `fld` must match the parameter type of an overload of the method. diff --git a/xml/System.Reflection.Emit/Label.xml b/xml/System.Reflection.Emit/Label.xml index 09411f220b8ba..17b1b884fcaa6 100644 --- a/xml/System.Reflection.Emit/Label.xml +++ b/xml/System.Reflection.Emit/Label.xml @@ -137,7 +137,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -170,7 +170,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/MethodBuilder.xml b/xml/System.Reflection.Emit/MethodBuilder.xml index e4a20fcbf1651..933943f5fd854 100644 --- a/xml/System.Reflection.Emit/MethodBuilder.xml +++ b/xml/System.Reflection.Emit/MethodBuilder.xml @@ -43,37 +43,37 @@ You can use reflection emit to define global methods and to define methods as type members. The APIs that define methods return objects. ### Global methods - A global method is defined by using the method, which returns a **MethodBuilder** object. + A global method is defined by using the method, which returns a **MethodBuilder** object. - Global methods must be static. If a dynamic module contains global methods, the method must be called before persisting the dynamic module or the containing dynamic assembly because the common language runtime postpones fixing up the dynamic module until all global functions have been defined. + Global methods must be static. If a dynamic module contains global methods, the method must be called before persisting the dynamic module or the containing dynamic assembly because the common language runtime postpones fixing up the dynamic module until all global functions have been defined. - A global native method is defined by using the method. Platform invoke (PInvoke) methods must not be declared abstract or virtual. The runtime sets the attribute for a platform invoke method. + A global native method is defined by using the method. Platform invoke (PInvoke) methods must not be declared abstract or virtual. The runtime sets the attribute for a platform invoke method. ### Methods as members of types - A method is defined as a type member by using the method, which returns a object. + A method is defined as a type member by using the method, which returns a object. The method is used to set the name and parameter attributes of a parameter, or of the return value. The object returned by this method represents a parameter or the return value. The object can be used to set the marshaling, to set the constant value, and to apply custom attributes. ## Attributes Members of the enumeration define the precise character of a dynamic method: -- Static methods are specified using the attribute. +- Static methods are specified using the attribute. -- Final methods (methods that cannot be overridden) are specified using the attribute. +- Final methods (methods that cannot be overridden) are specified using the attribute. -- Virtual methods are specified using the attribute. +- Virtual methods are specified using the attribute. -- Abstract methods are specified using the attribute. +- Abstract methods are specified using the attribute. - Several attributes determine method visibility. See the description of the enumeration. -- Methods that implement overloaded operators must set the attribute. +- Methods that implement overloaded operators must set the attribute. -- Finalizers must set the attribute. +- Finalizers must set the attribute. ## Known Issues -- Although is derived from , some of the abstract methods defined in the class are not fully implemented in . These methods throw the . For example the method is not fully implemented. You can reflect on these methods by retrieving the enclosing type using the or methods. +- Although is derived from , some of the abstract methods defined in the class are not fully implemented in . These methods throw the . For example the method is not fully implemented. You can reflect on these methods by retrieving the enclosing type using the or methods. - Custom modifiers are supported starting with the .NET Framework version 2.0. They are not supported in earlier versions. @@ -235,7 +235,7 @@ ## Remarks A always represents a generic method definition, and thus cannot be invoked. - For more information, see and . For information on generic types, see . + For more information, see and . For information on generic types, see . ]]> @@ -371,7 +371,7 @@ By convention, a type parameter name is a single uppercase letter. - For more information, see and . For information on generic types, see . + For more information, see and . For information on generic types, see . @@ -619,7 +619,7 @@ ## Remarks The type parameters of a generic method also are returned by the method that is used to define them. - For more information, see and . For information on generic types, see . + For more information, see and . For information on generic types, see . ]]> @@ -653,7 +653,7 @@ ## Remarks A cannot be used to emit a constructed generic method directly. The emitted method is a generic method definition. - For more information, see and . For information on generic types, see . + For more information, see and . For information on generic types, see . ]]> @@ -1093,7 +1093,7 @@ , call the method on the completed type, and get the property on the resulting . + To determine whether a method in a dynamic assembly is security-critical, complete the type by calling , call the method on the completed type, and get the property on the resulting . ]]> @@ -1119,7 +1119,7 @@ , call the method on the completed type, and get the property on the resulting . + To determine whether a method in a dynamic assembly is security-safe-critical, complete the type by calling , call the method on the completed type, and get the property on the resulting . ]]> @@ -1145,7 +1145,7 @@ , call the method on the completed type, and get the property on the resulting . + To determine whether a method in a dynamic assembly is security-transparent, complete the type by calling , call the method on the completed type, and get the property on the resulting . ]]> @@ -1387,7 +1387,7 @@ ## Remarks > [!NOTE] -> Starting with the .NET Framework 2.0 and the .NET Compact Framework 2.0, this member is inherited from the base class, . See . +> Starting with the .NET Framework 2.0 and the .NET Compact Framework 2.0, this member is inherited from the base class, . See . ]]> @@ -1534,7 +1534,7 @@ method in combination with the method, be aware of potential interactions. For example, using the method to add the attribute also sets the flag. If you subsequently call the method, the flag is overwritten. There are two ways to avoid this: + When you use the method in combination with the method, be aware of potential interactions. For example, using the method to add the attribute also sets the flag. If you subsequently call the method, the flag is overwritten. There are two ways to avoid this: - Call the method before you call the method. The method always respects existing method implementation flags. @@ -1682,11 +1682,11 @@ method that accepts an array of parameter types. However, a generic method can have parameters whose types are specified by one or more of its own generic type parameters, which cannot be defined until after the method has been defined. Use this method to set the parameter types in that case. + If the number and types of the parameters are known when the method is defined, they can be set using any overload of the method that accepts an array of parameter types. However, a generic method can have parameters whose types are specified by one or more of its own generic type parameters, which cannot be defined until after the method has been defined. Use this method to set the parameter types in that case. If the return type has optional or required custom modifiers, such as , use the method overload. - Calling this method replaces any parameter types that were set using the method. + Calling this method replaces any parameter types that were set using the method. @@ -1737,7 +1737,7 @@ ## Remarks Use this method to set the return type of a generic method, when the return type is specified by one of the generic type parameters of the method. If the return type has optional or required custom modifiers, such as , use the method overload. - Calling this method replaces a return type established using the method. + Calling this method replaces a return type established using the method. @@ -1796,18 +1796,18 @@ method that accepts an array of parameter types. However, a generic method can have parameters whose types are specified by one or more of its own generic type parameters, which cannot be defined until after the method has been defined. Use this method to set the parameter types in that case. + If the return type and the number and types of the parameters are known when the method is defined, they can be established using any overload of the method that accepts an array of parameter types. However, a generic method can have parameters whose types are specified by one or more of its own generic type parameters, which cannot be defined until after the method has been defined. Use this method to set the parameter types in that case. If neither the return type nor the parameter types have optional or required custom modifiers, such as , you can use the and methods. - Calling this method replaces the parameters and return type established using the method. + Calling this method replaces the parameters and return type established using the method. ## Examples The following code example contains source code for a generic class named Sample that has a type parameter `T`. The class has a field named `Field`, of type `T`, and a generic method `GM` with its own type parameter, `U`. Method `GM` creates an instance of Sample, substituting its own type parameter `U` for the type parameter of Sample, and stores its input parameter in `Field`. This source code is compiled but not used; you can view it with the [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md), and compare it to the code emitted by class `Example`. - The code in class `Example` demonstrates the use of the method in emitting generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample`, and uses the method to make it generic by adding a type parameter named `T`. A default constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added, and turned into a generic method using the method. The type parameter of `GM` is named `U`. Once the type parameter is defined, the signature of `GM` is added, using the method. There is no return type, and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`, which sets the type of the only parameter of the method; this is set to the method's type parameter, `U`. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. A dummy type is defined, to hold the entry point method `Main`. In the body of `Main`, the static `GM` method is invoked on the constructed generic type `Sample` (`Sample(Of Integer)` in Visual Basic), with type substituted for `U`. The method is used to create a for the static `GM` method of the constructed generic type `Sample`, and the method is then used to create a that can emitted in a method call. + The code in class `Example` demonstrates the use of the method in emitting generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample`, and uses the method to make it generic by adding a type parameter named `T`. A default constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added, and turned into a generic method using the method. The type parameter of `GM` is named `U`. Once the type parameter is defined, the signature of `GM` is added, using the method. There is no return type, and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`, which sets the type of the only parameter of the method; this is set to the method's type parameter, `U`. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. A dummy type is defined, to hold the entry point method `Main`. In the body of `Main`, the static `GM` method is invoked on the constructed generic type `Sample` (`Sample(Of Integer)` in Visual Basic), with type substituted for `U`. The method is used to create a for the static `GM` method of the constructed generic type `Sample`, and the method is then used to create a that can emitted in a method call. When the code example is run, it saves the emitted assembly as TypeBuilderGetFieldExample.exe. You can run TypeBuilderGetFieldExample.exe, and you can use the [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) to compare the emitted code with the code for the `Sample` class that is compiled into the code example itself. diff --git a/xml/System.Reflection.Emit/MethodToken.xml b/xml/System.Reflection.Emit/MethodToken.xml index f908b6368eeb8..f121d5175d897 100644 --- a/xml/System.Reflection.Emit/MethodToken.xml +++ b/xml/System.Reflection.Emit/MethodToken.xml @@ -131,7 +131,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -159,7 +159,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/ModuleBuilder.xml b/xml/System.Reflection.Emit/ModuleBuilder.xml index 8f2f0b8afcecb..79115d5ce87b1 100644 --- a/xml/System.Reflection.Emit/ModuleBuilder.xml +++ b/xml/System.Reflection.Emit/ModuleBuilder.xml @@ -37,7 +37,7 @@ , use the method. + To get an instance of , use the method. @@ -126,7 +126,7 @@ This method should be called when the user is done with defining all the global functions within this dynamic module. After calling this function, no more new global functions or new global data are allowed. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -233,7 +233,7 @@ > In the .NET Framework versions 1.0 and 1.1, it is necessary to define enumerations using because emits enumerations whose elements are of type instead of the enumeration type. In the .NET Framework version 2.0, emits enumerations whose elements have the correct type. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -300,7 +300,7 @@ The global method that this method defines is not usable until you call . > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -368,7 +368,7 @@ You cannot use the global method that this method defines until you call . > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -442,7 +442,7 @@ You cannot use the global method that this method defines until you call . > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -494,7 +494,7 @@ The data defined by this method is not created until the method is called. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -549,13 +549,13 @@ - This method allows you to embed a manifest resource BLOB into a dynamic assembly. -- To embed a managed resource into the manifest module of a dynamic assembly or into a satellite module, use the method to get a resource writer, and use the method to add the resource. +- To embed a managed resource into the manifest module of a dynamic assembly or into a satellite module, use the method to get a resource writer, and use the method to add the resource. -- To link a managed resource into a dynamic assembly, use the method to get a resource writer, and use the method to add the linked resource. +- To link a managed resource into a dynamic assembly, use the method to get a resource writer, and use the method to add the linked resource. -- To link a manifest resource BLOB into a dynamic assembly, use the method to add the linked resource. +- To link a manifest resource BLOB into a dynamic assembly, use the method to add the linked resource. - In addition, a single Win32 resource can be attached to an assembly by using the method or the method. This resource does not appear in the assembly manifest. + In addition, a single Win32 resource can be attached to an assembly by using the method or the method. This resource does not appear in the assembly manifest. @@ -626,7 +626,7 @@ Some DLL import attributes (see the description of System.Runtime.InteropServices.DllImportAttribute) cannot be specified as arguments to this method. Such attributes should be set by emitting a custom attribute for the method. For example, the DLL import attribute `PreserveSig` is set by emitting a custom attribute. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -634,7 +634,7 @@ The following example illustrates the use of the `DefinePInvokeMethod` method to create a for an external unmanaged method, `MessageBoxA`, in the Win32 API. The example displays a message box with **Retry** and **Cancel** buttons, and displays the return value from the message box. > [!IMPORTANT] -> To get a non-zero return value, you must add to the method implementation flags after you create the , by using the and methods. +> To get a non-zero return value, you must add to the method implementation flags after you create the , by using the and methods. [!code-cpp[ModuleBuilder_DefinePInvokeMethod1#1](~/samples/snippets/cpp/VS_Snippets_CLR/ModuleBuilder_DefinePInvokeMethod1/CPP/modulebuilder_definepinvokemethod1.cpp#1)] [!code-csharp[ModuleBuilder_DefinePInvokeMethod1#1](~/samples/snippets/csharp/VS_Snippets_CLR/ModuleBuilder_DefinePInvokeMethod1/CS/modulebuilder_definepinvokemethod1.cs#1)] @@ -699,7 +699,7 @@ Some DLL import attributes (see the description of ) cannot be specified as arguments to this method. Such attributes should be set by emitting a custom attribute for the method. For example, the DLL import attribute `PreserveSig` is set by emitting a custom attribute. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -707,7 +707,7 @@ The following example illustrates the use of the `DefinePInvokeMethod` method to create a for an external unmanaged method, `MessageBoxA`, in the Win32 API. The example displays a message box with **Retry** and **Cancel** buttons, and displays the return value from the message box. > [!IMPORTANT] -> To get a non-zero return value, you must add to the method implementation flags after you create the , by using the and methods. +> To get a non-zero return value, you must add to the method implementation flags after you create the , by using the and methods. This example uses a different overload of the method, but the technique is the same. @@ -754,7 +754,7 @@ Use this method to embed a managed resource. To embed a manifest resource blob, use the method. For a summary of embedding and linking managed resources and manifest resource blobs, see the method. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -810,7 +810,7 @@ Use this method to embed a managed resource. To embed a manifest resource blob, use the method. For a summary of embedding and linking managed resources and manifest resource blobs, see the method. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -865,7 +865,7 @@ Type names must be unique within an assembly. You cannot have two types with the same name in two different modules of an assembly. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -921,7 +921,7 @@ Type names must be unique within an assembly. You cannot have two types with the same name in two different modules of an assembly. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -979,7 +979,7 @@ Type names must be unique within an assembly. You cannot have two types with the same name in two different modules of an assembly. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1039,7 +1039,7 @@ Type names must be unique within an assembly. It is forbidden to have two types with the same name in two different modules of an assembly. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1099,7 +1099,7 @@ Type names must be unique within an assembly. You cannot have two types with the same name in two different modules of an assembly. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1164,7 +1164,7 @@ Type names must be unique within an assembly. You cannot have two types with the same name in two different modules of an assembly. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1226,7 +1226,7 @@ Type names must be unique within an assembly. You cannot have two types with the same name in two different modules of an assembly. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1286,7 +1286,7 @@ The data defined by this method is not created until the method is called. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -1327,7 +1327,7 @@ An assembly can be associated with only one unmanaged resource. This means that calling `DefineVersionInfoResource` or `DefineUnmanagedResource` after either one of the methods was called previously throws . Multiple unmanaged resources need to be merged with a tool such as the Microsoft ResMerge utility (not supplied with the common language runtime). > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -1362,7 +1362,7 @@ An assembly can be associated with only one unmanaged resource. This means that calling `DefineVersionInfoResource` or `DefineUnmanagedResource` after either one of the methods was called previously throws . Multiple unmanaged resources need to be merged with a tool such as the Microsoft ResMerge utility (not supplied with the common language runtime). > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -1685,7 +1685,7 @@ and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. + Use this method to examine the custom attributes of code in the reflection-only context, in cases where the custom attributes themselves are defined in code that is loaded into the reflection-only context. Methods like and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. ]]> @@ -1845,7 +1845,7 @@ method. Use the inherited method to get methods that have been declared at the module level. Module-level methods are defined in emitted code by using the method. + This method provides the implementation for all overloads of the inherited method. Use the inherited method to get methods that have been declared at the module level. Module-level methods are defined in emitted code by using the method. > [!IMPORTANT] > Module-level methods cannot be retrieved until after the method has been called for the module. @@ -1967,7 +1967,7 @@ and `machine` is always 0 (zero). + For dynamic modules, `peKind` is always and `machine` is always 0 (zero). ]]> @@ -2106,7 +2106,7 @@ ## Remarks > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -2141,10 +2141,10 @@ , , and methods instead. + Do not use this method to generate array types, pointer types, or byref types. Use the , , and methods instead. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -2187,10 +2187,10 @@ , , and methods instead. + Do not use this method to generate array types, pointer types, or byref types. Use the , , and methods instead. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -2237,10 +2237,10 @@ ## Remarks The `throwOnError` parameter only affects what happens when the type is not found. It does not affect any other exceptions that might be thrown. In particular, if the type is found but cannot be loaded, can be thrown even if `throwOnError` is `false`. - Do not use this method to generate array types, pointer types, or byref types. Use the , , and methods instead. + Do not use this method to generate array types, pointer types, or byref types. Use the , , and methods instead. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -2279,7 +2279,7 @@ For example, if the class initializers of one of the classes throws an exception while it is being loaded, a `TargetInvocationException` is stored in the corresponding element of the `LoaderExceptions` array. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -2581,12 +2581,12 @@ method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + Use the method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the ECMA Web site. - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. ]]> @@ -2628,12 +2628,12 @@ method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + Use the method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the ECMA Web site. - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. ]]> @@ -2679,12 +2679,12 @@ method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericMethodArguments`. It is always safe to provide these arguments, even when they are not needed. + Use the method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericMethodArguments`. It is always safe to provide these arguments, even when they are not needed. > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the ECMA Web site. - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. ]]> @@ -2798,12 +2798,12 @@ method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + Use the method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the ECMA Web site. - For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. + For code that demonstrates token resolution using the generic context (that is, the generic type parameters of the generic type and/or the generic method in which the token is embedded) see the method. ]]> @@ -2866,7 +2866,7 @@ ## Remarks > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -2912,7 +2912,7 @@ For more information about how to format `binaryAttribute`, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the Ecma International Web site. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -2948,7 +2948,7 @@ This method does nothing. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -2982,7 +2982,7 @@ The compiler might generate a startup stub before calling user main. The startup stub will be the entry point. While the user main will be the user entry point so that debugger will not step into the compiler entry point. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> diff --git a/xml/System.Reflection.Emit/OpCode.xml b/xml/System.Reflection.Emit/OpCode.xml index 60ef609787c29..e8add2eb31fb1 100644 --- a/xml/System.Reflection.Emit/OpCode.xml +++ b/xml/System.Reflection.Emit/OpCode.xml @@ -221,7 +221,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -258,7 +258,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> @@ -465,7 +465,7 @@ ## Examples - The following example displays the property values of the instruction. + The following example displays the property values of the instruction. [!code-csharp[System.Reflection.Emit.OpCode.Value#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.reflection.emit.opcode.value/cs/value1.cs#1)] [!code-vb[System.Reflection.Emit.OpCode.Value#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.emit.opcode.value/vb/value1.vb#1)] diff --git a/xml/System.Reflection.Emit/PackingSize.xml b/xml/System.Reflection.Emit/PackingSize.xml index 84426106a61dc..956c402b1ff93 100644 --- a/xml/System.Reflection.Emit/PackingSize.xml +++ b/xml/System.Reflection.Emit/PackingSize.xml @@ -30,7 +30,7 @@ . The packing size is one of two factors that determine the offset of a field when the structure or class is marshaled; the other factor is the effective size of the field. To determine the offset of a field: + Packing size affects the alignment of fields in structures and classes whose organization is . The packing size is one of two factors that determine the offset of a field when the structure or class is marshaled; the other factor is the effective size of the field. To determine the offset of a field: 1. Compute the minimum value for the offset by adding the size of the preceding field to the offset of the preceding field. diff --git a/xml/System.Reflection.Emit/ParameterToken.xml b/xml/System.Reflection.Emit/ParameterToken.xml index e02f2cbf7d8b7..6dda951e5a03f 100644 --- a/xml/System.Reflection.Emit/ParameterToken.xml +++ b/xml/System.Reflection.Emit/ParameterToken.xml @@ -131,7 +131,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -159,7 +159,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/PropertyBuilder.xml b/xml/System.Reflection.Emit/PropertyBuilder.xml index b0d2a827cfa5a..b5217f0f67b3b 100644 --- a/xml/System.Reflection.Emit/PropertyBuilder.xml +++ b/xml/System.Reflection.Emit/PropertyBuilder.xml @@ -42,7 +42,7 @@ ## Examples - The following code sample demonstrates how to implement properties in a dynamic type using a `PropertyBuilder` obtained via to create the property framework and an associated to implement the IL logic within the property. + The following code sample demonstrates how to implement properties in a dynamic type using a `PropertyBuilder` obtained via to create the property framework and an associated to implement the IL logic within the property. [!code-cpp[System.Reflection.Emit.PropertyBuilder Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.PropertyBuilder Example/CPP/source.cpp#1)] [!code-csharp[System.Reflection.Emit.PropertyBuilder Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Reflection.Emit.PropertyBuilder Example/CS/source.cs#1)] @@ -911,7 +911,7 @@ or , retrieve the object from the type, and call . + To set the value of a property, reflect on the property's parent type using or , retrieve the object from the type, and call . ]]> @@ -955,7 +955,7 @@ or , retrieve the object from the type, and call . + To set the value of a property, reflect on the property's parent type using or , retrieve the object from the type, and call . ]]> diff --git a/xml/System.Reflection.Emit/PropertyToken.xml b/xml/System.Reflection.Emit/PropertyToken.xml index 197e01ea0379f..46c8ad66668e8 100644 --- a/xml/System.Reflection.Emit/PropertyToken.xml +++ b/xml/System.Reflection.Emit/PropertyToken.xml @@ -131,7 +131,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -159,7 +159,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/SignatureHelper.xml b/xml/System.Reflection.Emit/SignatureHelper.xml index d32cd50530564..a6578c1410cf3 100644 --- a/xml/System.Reflection.Emit/SignatureHelper.xml +++ b/xml/System.Reflection.Emit/SignatureHelper.xml @@ -37,7 +37,7 @@ class to create a signature blob that can be passed to the method of the class. A object can also be passed to the method overload to insert an instruction and a signature token into a Microsoft intermediate language (MSIL) stream. For information on signature blobs and signature metadata, see the ECMA Partition II Metadata documentation. + Use the class to create a signature blob that can be passed to the method of the class. A object can also be passed to the method overload to insert an instruction and a signature token into a Microsoft intermediate language (MSIL) stream. For information on signature blobs and signature metadata, see the ECMA Partition II Metadata documentation. > [!NOTE] > The ECMA Partition II documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the Ecma International Web site. diff --git a/xml/System.Reflection.Emit/SignatureToken.xml b/xml/System.Reflection.Emit/SignatureToken.xml index 8588acd5e10db..005c6dfa2cf05 100644 --- a/xml/System.Reflection.Emit/SignatureToken.xml +++ b/xml/System.Reflection.Emit/SignatureToken.xml @@ -131,7 +131,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -159,7 +159,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/StringToken.xml b/xml/System.Reflection.Emit/StringToken.xml index ac65f8b23db80..33363453ef08d 100644 --- a/xml/System.Reflection.Emit/StringToken.xml +++ b/xml/System.Reflection.Emit/StringToken.xml @@ -113,7 +113,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -141,7 +141,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/TypeBuilder.xml b/xml/System.Reflection.Emit/TypeBuilder.xml index e78281b9bf697..67149438f5327 100644 --- a/xml/System.Reflection.Emit/TypeBuilder.xml +++ b/xml/System.Reflection.Emit/TypeBuilder.xml @@ -38,7 +38,7 @@ is the root class used to control the creation of dynamic classes in the runtime. It provides a set of routines that are used to define classes, add methods and fields, and create the class inside a module. A new can be created from a dynamic module by calling the method, which returns a object. + is the root class used to control the creation of dynamic classes in the runtime. It provides a set of routines that are used to define classes, add methods and fields, and create the class inside a module. A new can be created from a dynamic module by calling the method, which returns a object. Reflection emit provides the following options for defining types: @@ -58,28 +58,28 @@ To create an array type, pointer type, or byref type for an incomplete type that is represented by a object, use the method, method, or method, respectively. - Before a type is used, the method must be called. **CreateType** completes the creation of the type. Following the call to **CreateType**, the caller can instantiate the type by using the method, and invoke members of the type by using the method. It is an error to invoke methods that change the implementation of a type after **CreateType** has been called. For example, the common language runtime throws an exception if the caller tries to add new members to a type. + Before a type is used, the method must be called. **CreateType** completes the creation of the type. Following the call to **CreateType**, the caller can instantiate the type by using the method, and invoke members of the type by using the method. It is an error to invoke methods that change the implementation of a type after **CreateType** has been called. For example, the common language runtime throws an exception if the caller tries to add new members to a type. - A class initializer is created by using the method. **DefineTypeInitializer** returns a object. + A class initializer is created by using the method. **DefineTypeInitializer** returns a object. - Nested types are defined by calling one of the methods. + Nested types are defined by calling one of the methods. ## Attributes The class uses the enumeration to further specify the characteristics of the type to be created: -- Interfaces are specified using the and attributes. +- Interfaces are specified using the and attributes. -- Concrete classes (classes that cannot be extended) are specified using the attribute. +- Concrete classes (classes that cannot be extended) are specified using the attribute. - Several attributes determine type visibility. See the description of the enumeration. -- If is specified, the class loader lays out fields in the order they are read from metadata. The class loader considers the specified packing size but ignores any specified field offsets. The metadata preserves the order in which the field definitions are emitted. Even across a merge, the metadata will not reorder the field definitions. The loader will honor the specified field offsets only if is specified. +- If is specified, the class loader lays out fields in the order they are read from metadata. The class loader considers the specified packing size but ignores any specified field offsets. The metadata preserves the order in which the field definitions are emitted. Even across a merge, the metadata will not reorder the field definitions. The loader will honor the specified field offsets only if is specified. ## Known Issues - Reflection emit does not verify whether a non-abstract class that implements an interface has implemented all the methods declared in the interface. However, if the class does not implement all the methods declared in an interface, the runtime does not load the class. -- Although is derived from , some of the abstract methods defined in the class are not fully implemented in the class. Calls to these methods throw a exception. The desired functionality can be obtained by retrieving the created type using the or and reflecting on the retrieved type. +- Although is derived from , some of the abstract methods defined in the class are not fully implemented in the class. Calls to these methods throw a exception. The desired functionality can be obtained by retrieving the created type using the or and reflecting on the retrieved type. @@ -90,7 +90,7 @@ The following code example shows how to define a dynamic assembly with one module. The module in the example assembly contains one type, `MyDynamicType`, which has a private field, a property that gets and sets the private field, constructors that initialize the private field, and a method that multiplies a user-supplied number by the private field value and returns the result. - The field is specified when the assembly is created. The assembly code is used immediately, and the assembly is also saved to disk so that it can be examined with [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) or used in another program. + The field is specified when the assembly is created. The assembly code is used immediately, and the assembly is also saved to disk so that it can be examined with [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) or used in another program. [!code-cpp[AssemblyBuilderClass#1](~/samples/snippets/cpp/VS_Snippets_CLR/AssemblyBuilderClass/cpp/24895.cpp#1)] [!code-csharp[AssemblyBuilderClass#1](~/samples/snippets/csharp/VS_Snippets_CLR/AssemblyBuilderClass/cs/24895.cs#1)] @@ -156,7 +156,7 @@ ## Examples - The following example demonstrates the use of the `AddDeclarativeSecurity` method to add a security demand for with the flag to a dynamic type named `MyDynamicClass`, in an assembly named EmittedExample.dll. The example produces no console output; after you run it, you can use [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) to examine EmittedExample.dll. In `MyDynamicClass`, open the `.class public auto ansi` statement to see the declarative permission. + The following example demonstrates the use of the `AddDeclarativeSecurity` method to add a security demand for with the flag to a dynamic type named `MyDynamicClass`, in an assembly named EmittedExample.dll. The example produces no console output; after you run it, you can use [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) to examine EmittedExample.dll. In `MyDynamicClass`, open the `.class public auto ansi` statement to see the declarative permission. [!code-cpp[TypeBuilder_AddDeclarativeSecurity#1](~/samples/snippets/cpp/VS_Snippets_CLR/TypeBuilder_AddDeclarativeSecurity/CPP/typebuilder_adddeclarativesecurity.cpp#1)] [!code-csharp[TypeBuilder_AddDeclarativeSecurity#1](~/samples/snippets/csharp/VS_Snippets_CLR/TypeBuilder_AddDeclarativeSecurity/CS/typebuilder_adddeclarativesecurity.cs#1)] @@ -269,7 +269,7 @@ ) and the display name of the assembly (), separated by a comma and a space. + The format of the returned string is the concatenation of the full name of the type () and the display name of the assembly (), separated by a comma and a space. See for a description of the format of the display name of an assembly. @@ -374,14 +374,14 @@ If the current type derives from an incomplete type or implements incomplete interfaces, call the method on the parent type and the interface types before calling it on the current type. - If the enclosing type contains a field that is a value type defined as a nested type (for example, a field that is an enumeration defined as a nested type), calling the method on the enclosing type will generate a event. This is because the loader cannot determine the size of the enclosing type until the nested type has been completed. The caller should define a handler for the event to complete the definition of the nested type by calling on the object that represents the nested type. The code example for this topic shows how to define such an event handler. + If the enclosing type contains a field that is a value type defined as a nested type (for example, a field that is an enumeration defined as a nested type), calling the method on the enclosing type will generate a event. This is because the loader cannot determine the size of the enclosing type until the nested type has been completed. The caller should define a handler for the event to complete the definition of the nested type by calling on the object that represents the nested type. The code example for this topic shows how to define such an event handler. A type is created only once, no matter how many times the method is called. All calls return the same object. ## Examples - The following code example shows how to define an event handler for the event, in order to call the method on a nested type during a call on the enclosing type. + The following code example shows how to define an event handler for the event, in order to call the method on a nested type during a call on the enclosing type. [!code-cpp[System.Reflection.Emit.TypeBuilder.CreateType Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.Emit.TypeBuilder.CreateType Example/CPP/nestedenum.cpp#1)] [!code-csharp[System.Reflection.Emit.TypeBuilder.CreateType Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Reflection.Emit.TypeBuilder.CreateType Example/CS/nestedenum.cs#1)] @@ -532,7 +532,7 @@ - If you want a default constructor that simply calls the default constructor of the base class, you can use the method to create one (and optionally restrict access to it). Do not provide an implementation for this default constructor. If you do, an exception is thrown when you try to use the constructor. No exception is thrown when the method is called. -- If you want a default constructor that does something more than simply calling the default constructor of the base class, or that calls another constructor of the base class, or that does something else entirely, you must use the method to create one, and provide your own implementation. +- If you want a default constructor that does something more than simply calling the default constructor of the base class, or that calls another constructor of the base class, or that does something else entirely, you must use the method to create one, and provide your own implementation. @@ -941,14 +941,14 @@ method. + Use this method overload when you do not know the method signature at the time you define the method. For example, the parameter types and return type of a generic method might be specified by the method's generic type parameters, which must be defined after the method has been added to the type. The parameters and return type of the method can be set later using the method. - This method overload defines a method with . If you need to define a method without a signature, with a different calling convention, use the method overload. + This method overload defines a method with . If you need to define a method without a signature, with a different calling convention, use the method overload. ## Examples - The following code example defines a generic method named `DemoMethod` whose parameter type and return type are specified by its generic type parameters. The method is defined without a signature, using the standard calling convention. The method is used to make `DemoMethod` a generic method, and the newly defined type parameters are then used for the signature and return type. + The following code example defines a generic method named `DemoMethod` whose parameter type and return type are specified by its generic type parameters. The method is defined without a signature, using the standard calling convention. The method is used to make `DemoMethod` a generic method, and the newly defined type parameters are then used for the signature and return type. This code example is part of a larger example provided for the method. @@ -1011,7 +1011,7 @@ method. + Use this method overload when you do not know the method signature at the time you define the method. For example, the parameter types and return type of a generic method might be specified by the method's generic type parameters, which must be defined after the method has been added to the type. The parameters and return type of the method can be set later using the method. ]]> @@ -1190,7 +1190,7 @@ or method overloads to define the method and then use the method to define the parameter and return types with custom modifiers. + Use this overload if you need to specify custom modifiers. If you need to specify custom modifiers after the method has been created, as you would, for example, with a generic method whose parameter types are specified by its generic type parameters, you can use the or method overloads to define the method and then use the method to define the parameter and return types with custom modifiers. > [!NOTE] > For more information on custom modifiers, see the ECMA Partition II Metadata documentation. The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the Ecma International Web site. @@ -1758,15 +1758,15 @@ ) cannot be specified as arguments to this method. For example, the DLL import attribute must be added after the `PInvoke` method is created, if the method returns a value. The example shows how to do this. + Some DLL import attributes (see the description of ) cannot be specified as arguments to this method. For example, the DLL import attribute must be added after the `PInvoke` method is created, if the method returns a value. The example shows how to do this. ## Examples - The following example demonstrates how to use the method to create a `PInvoke` method, and how to add the flag to the method implementation flags after you create the , by using the and methods. + The following example demonstrates how to use the method to create a `PInvoke` method, and how to add the flag to the method implementation flags after you create the , by using the and methods. > [!IMPORTANT] -> To get a non-zero return value, you must add the flag. +> To get a non-zero return value, you must add the flag. The example creates a dynamic assembly with one dynamic module and a single type, `MyType`, that contains the `PInvoke` method. The `PInvoke` method represents the Win32 `GetTickCount` function. @@ -1840,15 +1840,15 @@ ) cannot be specified as arguments to this method. For example, the DLL import attribute must be added after the `PInvoke` method is created, if the method returns a value. The example shows how to do this. + Some DLL import attributes (see the description of ) cannot be specified as arguments to this method. For example, the DLL import attribute must be added after the `PInvoke` method is created, if the method returns a value. The example shows how to do this. ## Examples - The following code example demonstrates how to use the method to create a `PInvoke` method, and how to add the flag to the method implementation flags after you create the , by using the and methods. + The following code example demonstrates how to use the method to create a `PInvoke` method, and how to add the flag to the method implementation flags after you create the , by using the and methods. > [!IMPORTANT] -> To get a non-zero return value, you must add the flag. +> To get a non-zero return value, you must add the flag. The example creates a dynamic assembly with one dynamic module and a single type, `MyType`, that contains the `PInvoke` method. The `PInvoke` method represents the Win32 `GetTickCount` function. @@ -1930,7 +1930,7 @@ ) cannot be specified as arguments to this method. For example, the DLL import attribute must be added after the `PInvoke` method is created, if the method returns a value. The example shows how to do this. + Some DLL import attributes (see the description of ) cannot be specified as arguments to this method. For example, the DLL import attribute must be added after the `PInvoke` method is created, if the method returns a value. The example shows how to do this. > [!NOTE] > For more information on custom modifiers, see the ECMA Partition II Metadata documentation. The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the Ecma International Web site. @@ -1938,12 +1938,12 @@ ## Examples - The following code example demonstrates how to use the [\], Type\[\], Type\[\], Type\[\]\[\], Type\[\]\ method to create a `PInvoke` method, and how to add the flag to the method implementation flags after you create the , by using the and methods. + The following code example demonstrates how to use the [\], Type\[\], Type\[\], Type\[\]\[\], Type\[\]\ method to create a `PInvoke` method, and how to add the flag to the method implementation flags after you create the , by using the and methods. The example creates a dynamic assembly with one dynamic module and a single type, `MyType`, that contains the `PInvoke` method. The `PInvoke` method represents the Win32 `GetTickCount` function. > [!IMPORTANT] -> To get a non-zero return value, you must add the flag. +> To get a non-zero return value, you must add the flag. > [!NOTE] > The example uses an overload that does not specify custom modifiers. To specify custom modifiers, change the example code to use this method overload instead. @@ -2510,7 +2510,7 @@ ## Examples The following code example contains source code for a generic class named `Sample` that has a type parameter named `T`. The class has a field named `Field`, of type `T`, and a generic method named `GM` with its own type parameter, named `U`. Method `GM` creates an instance of `Sample`, substituting its own type parameter `U` for the type parameter of `Sample`, and stores its input parameter in `Field`. This source code is compiled but not used; you can view it with the [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) and compare it to the code emitted by class `Example`. - The code in class `Example` demonstrates the use of the method to emit generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample` and uses the method to make it generic by adding a type parameter named `T`. A default constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added and turned into a generic method by using the method. The type parameter of `GM` is named `U`. After the type parameter is defined, the signature of `GM` is added by using the method. There is no return type and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`; `parameterTypes` sets the type of the method's only parameter to `U`, the method's generic type parameter. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. The method is used to create a that represents the default constructor of the constructed generic type `Sample` in the instruction that creates the instance. + The code in class `Example` demonstrates the use of the method to emit generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample` and uses the method to make it generic by adding a type parameter named `T`. A default constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added and turned into a generic method by using the method. The type parameter of `GM` is named `U`. After the type parameter is defined, the signature of `GM` is added by using the method. There is no return type and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`; `parameterTypes` sets the type of the method's only parameter to `U`, the method's generic type parameter. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. The method is used to create a that represents the default constructor of the constructed generic type `Sample` in the instruction that creates the instance. A dummy type is defined to hold the entry-point method `Main`. In the body of `Main`, the static `GM` method is invoked on the constructed generic type `Sample` (`Sample(Of Integer)` in Visual Basic), with type substituted for `U`. @@ -2605,7 +2605,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -2699,7 +2699,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -2736,7 +2736,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -2803,7 +2803,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -2840,7 +2840,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -2887,7 +2887,7 @@ ## Examples The following code example contains source code for a generic class named Sample that has a type parameter named `T`. The class has a field named `Field`, of type `T`, and a generic method named `GM` with its own type parameter, named `U`. Method `GM` creates an instance of `Sample`, substituting its own type parameter `U` for the type parameter of `Sample`, and stores its input parameter in `Field`. This source code is compiled but not used; you can view it with the [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) and compare it to the code emitted by class `Example`. - The code in class `Example` demonstrates the use of the method to emit generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample`, and uses the method to make it generic by adding a type parameter named `T`. A default constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added and turned into a generic method by using the method. The type parameter of `GM` is named `U`. After the type parameter is defined, the signature of `GM` is added by using the method. There is no return type and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`; `parameterTypes` sets the type of the method's only parameter to `U`, the method's generic type parameter. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. The method is used to create a that represents the field of the constructed generic type `Sample` in the and instructions. + The code in class `Example` demonstrates the use of the method to emit generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample`, and uses the method to make it generic by adding a type parameter named `T`. A default constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added and turned into a generic method by using the method. The type parameter of `GM` is named `U`. After the type parameter is defined, the signature of `GM` is added by using the method. There is no return type and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`; `parameterTypes` sets the type of the method's only parameter to `U`, the method's generic type parameter. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. The method is used to create a that represents the field of the constructed generic type `Sample` in the and instructions. A dummy type is defined to hold the entry-point method `Main`. In the body of `Main`, the static `GM` method is invoked on the constructed generic type `Sample` (`Sample(Of Integer)` in Visual Basic), with type substituted for `U`. @@ -2944,7 +2944,7 @@ ## Remarks The method does not return fields in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which fields are returned, because that order can vary. - Retrieve the type using or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -2980,7 +2980,7 @@ A object represents a generic type definition if the method has been used to give it generic type parameters. This method retrieves the objects that represent the generic type parameters. - For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. + For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. ]]> @@ -3033,7 +3033,7 @@ ## Remarks If you call the method on a object for which the property returns `true`, the property returns the current instance. A that represents a generic type is always a generic type definition. - If you used the method to construct a generic type from a object that represents a generic type definition, using the method on the constructed type gets back the object that represents the generic type definition. + If you used the method to construct a generic type from a object that represents a generic type definition, using the method on the constructed type gets back the object that represents the generic type definition. ]]> @@ -3070,7 +3070,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3110,7 +3110,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3173,7 +3173,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3208,7 +3208,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3255,7 +3255,7 @@ ## Examples The following code example contains source code for a generic class named `Sample` that has a type parameter named `T`. The class has a field named `Field`, of type `T`, and a generic method named `GM` with its own type parameter, named `U`. Method `GM` creates an instance of `Sample`, substituting its own type parameter `U` for the type parameter of `Sample`, and stores its input parameter in `Field`. This source code is compiled but not used; you can view it with the [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) and compare it to the code emitted by class `Example`. - The code in class `Example` demonstrates the use of the method to emit generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample` and uses the method to make it generic by adding a type parameter named `T`. A default constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added and turned into a generic method by using the method. The type parameter of `GM` is named `U`. After the type parameter is defined, the signature of `GM` is added by using the method. There is no return type and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`; `parameterTypes` sets the type of the method's only parameter to `U`, the method's generic type parameter. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. A dummy type is defined to hold the entry-point method `Main`. In the body of `Main`, the static `GM` method is invoked on the constructed generic type `Sample` (`Sample(Of Integer)` in Visual Basic), with type substituted for `U`. The method is used to create a for the static `GM` method of the constructed generic type `Sample`, and the method is then used to create a that can emitted in a method call. + The code in class `Example` demonstrates the use of the method to emit generic code. The `Main` method of class `Example` creates a dynamic assembly containing a class named `Sample` and uses the method to make it generic by adding a type parameter named `T`. A default constructor and a field named `Field`, of type `T`, are added to class `Sample`. A method `GM` is added and turned into a generic method by using the method. The type parameter of `GM` is named `U`. After the type parameter is defined, the signature of `GM` is added by using the method. There is no return type and no required or custom modifiers, so all the parameters of this method are `null` except `parameterTypes`; `parameterTypes` sets the type of the method's only parameter to `U`, the method's generic type parameter. The body of the method creates an instance of the constructed type `Sample` (`Sample(Of U)` in Visual Basic), assigns the method's parameter to `Field`, and then prints the value of `Field`. A dummy type is defined to hold the entry-point method `Main`. In the body of `Main`, the static `GM` method is invoked on the constructed generic type `Sample` (`Sample(Of Integer)` in Visual Basic), with type substituted for `U`. The method is used to create a for the static `GM` method of the constructed generic type `Sample`, and the method is then used to create a that can emitted in a method call. When the code example is run, it saves the emitted assembly as TypeBuilderGetFieldExample.exe. You can run TypeBuilderGetFieldExample.exe, and you can use the [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) to compare the emitted code with the code for the `Sample` class that is compiled into the code example itself. @@ -3349,7 +3349,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3390,7 +3390,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. If this type is complete, for example, if `CreateType` has been called on this type, but there are nested types that are not complete, then `GetNestedTypes` will only return those nested types for which `CreateType` has been called. @@ -3429,7 +3429,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. If this type is complete, for example, if `CreateType` has been called on this type, but there are nested types that are not complete, then `GetNestedTypes` will only return those nested types for which `CreateType` has been called. @@ -3466,7 +3466,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3535,7 +3535,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3615,7 +3615,7 @@ > [!NOTE] > Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked using Reflection whenever the code is fully trusted. - This method is not currently supported. You can retrieve the type using or and use reflection on the retrieved type. + This method is not currently supported. You can retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3838,7 +3838,7 @@ or and use reflection on the retrieved type. + This method is not supported for incomplete generic type parameters. Retrieve the type using or and use reflection on the retrieved type. ]]> @@ -3929,7 +3929,7 @@ ## Remarks A object represents a generic type definition if the method has been used to give it generic type parameters. An instance of the class that is generic is always a generic type definition. - For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. + For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. ]]> @@ -3965,7 +3965,7 @@ A can be used to build generic type definitions, but not constructed generic types. To get a constructed generic type, call the method on a that represents a generic type definition. - For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. + For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. ]]> @@ -4055,7 +4055,7 @@ The runtime begins evaluating transparency levels at the assembly. For example, if the dynamic assembly is security-critical, annotations on types are ignored, and all types are security-critical. - By default, a dynamic assembly inherits the transparency of the assembly that emits it. You can override this default by using the , , or method overload and specifying security attributes. You cannot elevate security levels by doing this; that is, transparent code cannot emit security-critical or security-safe-critical code. Attributes must be specified when the dynamic assembly is created, or they do not take effect until the assembly has been saved to disk and reloaded. + By default, a dynamic assembly inherits the transparency of the assembly that emits it. You can override this default by using the , , or method overload and specifying security attributes. You cannot elevate security levels by doing this; that is, transparent code cannot emit security-critical or security-safe-critical code. Attributes must be specified when the dynamic assembly is created, or they do not take effect until the assembly has been saved to disk and reloaded. > [!NOTE] > Default inheritance is limited to the runtime's evaluation of transparency. No attributes are applied to the dynamic assembly. If you want to add security attributes, you must apply them yourself. @@ -4103,7 +4103,7 @@ The runtime begins evaluating transparency levels at the assembly. For example, if the dynamic assembly is security-critical, annotations on types are ignored, and all types are security-critical. - By default, a dynamic assembly inherits the transparency of the assembly that emits it. You can override this default by using the , , or method overload and specifying security attributes. You cannot elevate security levels by doing this; that is, transparent code cannot emit security-critical or security-safe-critical code. Attributes must be specified when the dynamic assembly is created, or they do not take effect until the assembly has been saved to disk and reloaded. + By default, a dynamic assembly inherits the transparency of the assembly that emits it. You can override this default by using the , , or method overload and specifying security attributes. You cannot elevate security levels by doing this; that is, transparent code cannot emit security-critical or security-safe-critical code. Attributes must be specified when the dynamic assembly is created, or they do not take effect until the assembly has been saved to disk and reloaded. > [!NOTE] > Default inheritance is limited to the runtime's evaluation of transparency. No attributes are applied to the dynamic assembly. If you want to add security attributes, you must apply them yourself. @@ -4151,7 +4151,7 @@ The runtime begins evaluating transparency levels at the assembly. For example, if the dynamic assembly is security-critical, annotations on types are ignored, and all types are security-critical. - By default, a dynamic assembly inherits the transparency of the assembly that emits it. You can override this default by using the , , or method overload and specifying security attributes. You cannot elevate security levels by doing this; that is, transparent code cannot emit security-critical or security-safe-critical code. Attributes must be specified when the dynamic assembly is created, or they do not take effect until the assembly has been saved to disk and reloaded. + By default, a dynamic assembly inherits the transparency of the assembly that emits it. You can override this default by using the , , or method overload and specifying security attributes. You cannot elevate security levels by doing this; that is, transparent code cannot emit security-critical or security-safe-critical code. Attributes must be specified when the dynamic assembly is created, or they do not take effect until the assembly has been saved to disk and reloaded. > [!NOTE] > Default inheritance is limited to the runtime's evaluation of transparency. No attributes are applied to the dynamic assembly. If you want to add security attributes, you must apply them yourself. @@ -4670,7 +4670,7 @@ ## Remarks > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -4717,7 +4717,7 @@ For more information on how to format `binaryAttribute`, see the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the Ecma International Web site. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this member no longer requires with the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ]]> @@ -4994,7 +4994,7 @@ or and use reflection on the retrieved type. + Retrieve the type using or and use reflection on the retrieved type. ]]> diff --git a/xml/System.Reflection.Emit/TypeToken.xml b/xml/System.Reflection.Emit/TypeToken.xml index bb8716d76ec03..f7e3a93f4aa35 100644 --- a/xml/System.Reflection.Emit/TypeToken.xml +++ b/xml/System.Reflection.Emit/TypeToken.xml @@ -138,7 +138,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -166,7 +166,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection.Emit/UnmanagedMarshal.xml b/xml/System.Reflection.Emit/UnmanagedMarshal.xml index adf45735e2052..d30882dfc3c5b 100644 --- a/xml/System.Reflection.Emit/UnmanagedMarshal.xml +++ b/xml/System.Reflection.Emit/UnmanagedMarshal.xml @@ -32,7 +32,7 @@ ## Examples - The following code example shows replacement code for the obsolete type. The example emits a single-module assembly named `EmitMarshalAs.dll`, containing a type named `Sample`. The type has a method named `Test`, with one parameter of type . The code example applies the with to the parameter. + The following code example shows replacement code for the obsolete type. The example emits a single-module assembly named `EmitMarshalAs.dll`, containing a type named `Sample`. The type has a method named `Test`, with one parameter of type . The code example applies the with to the parameter. You can use the [Ildasm.exe (IL Disassembler)](~/docs/framework/tools/ildasm-exe-il-disassembler.md) to examine the emitted assembly and observe that the parameter is marked `marshal(bstr)`. @@ -228,7 +228,7 @@ passed to this method must be a simple native type. None of the following values may be used: , , , , or . + The passed to this method must be a simple native type. None of the following values may be used: , , , , or . Only unmanaged marshal constructs can be made using this method. diff --git a/xml/System.Reflection/AmbiguousMatchException.xml b/xml/System.Reflection/AmbiguousMatchException.xml index 8a011f3d1deac..bc9fab257774d 100644 --- a/xml/System.Reflection/AmbiguousMatchException.xml +++ b/xml/System.Reflection/AmbiguousMatchException.xml @@ -39,7 +39,7 @@ ## Remarks `AmbiguousMatchException` uses the HRESULT COR_E_AMBIGUOUSMATCH which has the value 0x8000211D. - An `AmbiguousMatchException` is thrown when a member is invoked late-bound and multiple overloads satisfy the binding criteria, or when more than one member matches the binding criteria passed to a reflection method that can return only a single result (for example, or ). + An `AmbiguousMatchException` is thrown when a member is invoked late-bound and multiple overloads satisfy the binding criteria, or when more than one member matches the binding criteria passed to a reflection method that can return only a single result (for example, or ). ]]> diff --git a/xml/System.Reflection/Assembly.xml b/xml/System.Reflection/Assembly.xml index 95f54325a4180..4747af45ba9e5 100644 --- a/xml/System.Reflection/Assembly.xml +++ b/xml/System.Reflection/Assembly.xml @@ -57,7 +57,7 @@ ## Remarks Use the class to load assemblies, to explore the metadata and constituent parts of assemblies, to discover the types contained in assemblies, and to create instances of those types. - To get an array of objects representing the assemblies currently loaded into an application domain (for example, the default application domain of a simple project), use the method. + To get an array of objects representing the assemblies currently loaded into an application domain (for example, the default application domain of a simple project), use the method. To load assemblies dynamically, the class provides the following static methods (`Shared` methods in Visual Basic). Assemblies are loaded into the application domain where the load operation occurs. @@ -163,7 +163,7 @@ property instead. + To get the absolute path to the loaded manifest-containing file, use the property instead. If the assembly was loaded as a byte array, using an overload of the method that takes an array of bytes, this property returns the location of the caller of the method, not the location of the loaded assembly. @@ -221,7 +221,7 @@ - You haven't specified the fully qualified name of the type. -- You've specified the fully qualified type name, but its case doesn’t match the case of the type's property. For a case-insensitive comparison of `typeName` with the type's full name, call the overload and specify `true` for the `ignoreCase` argument. +- You've specified the fully qualified type name, but its case doesn’t match the case of the type's property. For a case-insensitive comparison of `typeName` with the type's full name, call the overload and specify `true` for the `ignoreCase` argument. - The type doesn’t exist in the current instance. @@ -456,7 +456,7 @@ See for a description of the format of the display name of an assembly. - To accommodate changes in versions of the common language runtime, use this method rather than constructing the qualified name yourself. For information about qualified assembly names, see . + To accommodate changes in versions of the common language runtime, use this method rather than constructing the qualified name yourself. For information about qualified assembly names, see . ]]> @@ -529,7 +529,7 @@ property is comparable to the method, except that the property returns a [collection](../Topic/IEnumerable\(T\)%20Interface.md) of objects, and the method returns an array of objects. + The property is comparable to the method, except that the property returns a [collection](../Topic/IEnumerable\(T\)%20Interface.md) of objects, and the method returns an array of objects. The returned array includes nested types. @@ -740,7 +740,7 @@ > [!NOTE] > Writing your own code to parse display names is not recommended. Instead, pass the display name to the constructor, which parses it and populates the appropriate fields of the new . - In the .NET Framework version 2.0, processor architecture is added to assembly identity, and can be specified as part of assembly name strings. However, it is not included in the string returned by the property, for compatibility reasons. See . + In the .NET Framework version 2.0, processor architecture is added to assembly identity, and can be specified as part of assembly name strings. However, it is not included in the string returned by the property, for compatibility reasons. See . @@ -787,7 +787,7 @@ property. However, the property typically offers superior performance. + Calling this method is equivalent to retrieving the value of the property. However, the property typically offers superior performance. In order to call this method, you must have a object, which means that the assembly in which the class is defined must already be loaded. @@ -846,7 +846,7 @@ When `M1` is not inlined, returns `A2`. When `M1` is inlined, returns `A3`. Similarly, when `M2` is not inlined, returns `A2`. When `M2` is inlined, returns `A3`. - This effect also occurs when `M1` executes as a tail call from `M2`, or when `M2` executes as a tail call from `M3`. You can prevent the JIT compiler from inlining the method that calls , by applying the attribute with the flag, but there is no similar mechanism for preventing tail calls. + This effect also occurs when `M1` executes as a tail call from `M2`, or when `M2` executes as a tail call from `M3`. You can prevent the JIT compiler from inlining the method that calls , by applying the attribute with the flag, but there is no similar mechanism for preventing tail calls. @@ -1014,7 +1014,7 @@ and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. + Use this method to examine the custom attributes of code in the reflection-only context, in cases where the custom attributes themselves are defined in code that is loaded into the reflection-only context. Methods like and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. ]]> @@ -1088,7 +1088,7 @@ object that represents the current assembly is to use the property of a type found in the assembly, as the following example illustrates. + For performance reasons, you should call this method only when you do not know at design time what assembly is currently executing. The recommended way to retrieve an object that represents the current assembly is to use the property of a type found in the assembly, as the following example illustrates. [!code-csharp[System.Reflection.Assembly.GetExecutingAssembly#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.reflection.assembly.getexecutingassembly/cs/assembly1.cs#1)] [!code-vb[System.Reflection.Assembly.GetExecutingAssembly#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.assembly.getexecutingassembly/vb/assembly1.vb#1)] @@ -1098,7 +1098,7 @@ ## Examples - The following example uses the property to get the currently executing assembly based on a type contained in that assembly. It also calls the method to show that it returns an object that represents the same assembly. + The following example uses the property to get the currently executing assembly based on a type contained in that assembly. It also calls the method to show that it returns an object that represents the same assembly. [!code-cpp[System.Reflection.Assembly.GetExecutingAssembly#5](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.reflection.assembly.getexecutingassembly/cpp/getexecutingassembly1.cpp#5)] [!code-csharp[System.Reflection.Assembly.GetExecutingAssembly#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.reflection.assembly.getexecutingassembly/cs/getexecutingassembly1.cs#5)] @@ -1468,11 +1468,11 @@ - You can pass the resource name to the method to get additional information about the resource. -- If the name identifies a binary .resources file, you can remove its .resources file extension and pass it to the constructor to instantiate the resource manager. +- If the name identifies a binary .resources file, you can remove its .resources file extension and pass it to the constructor to instantiate the resource manager. -- You can pass the resource name to the method to retrieve a object that you can then pass to the constructor. +- You can pass the resource name to the method to retrieve a object that you can then pass to the constructor. -- You can pass the resource name to the method to retrieve a object that you can then pass to the constructor. +- You can pass the resource name to the method to retrieve a object that you can then pass to the constructor. Resource information is returned only if the resource is visible to the caller, or the caller has . @@ -1524,7 +1524,7 @@ Resource information is returned only if the resource is visible to the caller, or the caller has . > [!NOTE] -> This method returns `null` if a private resource in another assembly is accessed and the caller does not have with the flag. +> This method returns `null` if a private resource in another assembly is accessed and the caller does not have with the flag. If the assembly manifest lists a resource file, returns a object even if the resource file cannot be found on disk at the time. If the resource file is not found, passing the resulting object to the constructor causes an . @@ -1590,7 +1590,7 @@ Resource information is returned only if the resource is visible to the caller, or the caller has . > [!NOTE] -> This method returns `null` if a private resource in another assembly is accessed and the caller does not have with the flag. +> This method returns `null` if a private resource in another assembly is accessed and the caller does not have with the flag. If the assembly manifest lists a resource file, returns a object even if the resource file cannot be found on disk at the time. If the resource file is not found, passing the resulting object to the constructor causes an . @@ -1641,9 +1641,9 @@ ## Remarks This method works on file names. - Classes in the `Reflection.Emit` namespace emit the scope name for a dynamic module. The scope name can be determined by the property. Pass the kind of module you want to `Assembly.GetModule`. For example, if you want the module that contains the assembly manifest, pass the scope name of the module to `GetModule`. Otherwise, pass the file name of the module. Assemblies loaded by one of the `Load` methods that have a byte[] parameter have only one module, and that is the manifest module. Always seek these modules using the scope name. + Classes in the `Reflection.Emit` namespace emit the scope name for a dynamic module. The scope name can be determined by the property. Pass the kind of module you want to `Assembly.GetModule`. For example, if you want the module that contains the assembly manifest, pass the scope name of the module to `GetModule`. Otherwise, pass the file name of the module. Assemblies loaded by one of the `Load` methods that have a byte[] parameter have only one module, and that is the manifest module. Always seek these modules using the scope name. - A type can be retrieved from a specific module using . Calling `Module.GetType` on the module containing the manifest will not initiate a search of the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . + A type can be retrieved from a specific module using . Calling `Module.GetType` on the module containing the manifest will not initiate a search of the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . ]]> @@ -1884,7 +1884,7 @@ ## Remarks > [!IMPORTANT] -> Starting with the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], the property of an object that is returned by this method is if there is no hash algorithm for the referenced assembly, or if the hash algorithm of the referenced assembly is not identified by the enumeration. In previous versions of the .NET Framework, the property returned in this situation. +> Starting with the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], the property of an object that is returned by this method is if there is no hash algorithm for the referenced assembly, or if the hash algorithm of the referenced assembly is not identified by the enumeration. In previous versions of the .NET Framework, the property returned in this situation. @@ -2031,7 +2031,7 @@ method overload, which can optionally include an assembly display name as part of the type name. + This method only searches the current assembly instance. The `name` parameter includes the namespace but not the assembly. To search other assemblies for a type, use the method overload, which can optionally include an assembly display name as part of the type name. > [!NOTE] > If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](~/docs/framework/app-domains/type-forwarding-in-the-common-language-runtime.md). @@ -2039,7 +2039,7 @@ ## Examples - The following example defines an abstract `MeansOfTransportation` class in the `Transportation` namespace. It calls the method to retrieve its object, calls the method to get an array of objects that represent the type's properties, and then displays information on the type's abstract properties. Note that the call to the method uses the type's fully qualified name (that is, its namespace along with its type name). + The following example defines an abstract `MeansOfTransportation` class in the `Transportation` namespace. It calls the method to retrieve its object, calls the method to get an array of objects that represent the type's properties, and then displays information on the type's abstract properties. Note that the call to the method uses the type's fully qualified name (that is, its namespace along with its type name). [!code-csharp[System.Reflection.Assembly.GetType#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.reflection.assembly.gettype/cs/gettype1.cs#1)] [!code-vb[System.Reflection.Assembly.GetType#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.assembly.gettype/vb/gettype1.vb#1)] @@ -2111,7 +2111,7 @@ method overload, which can optionally include an assembly display name as part of the type name. + This method only searches the current assembly instance. The `name` parameter includes the namespace but not the assembly. To search other assemblies for a type, use the method overload, which can optionally include an assembly display name as part of the type name. > [!NOTE] > If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](~/docs/framework/app-domains/type-forwarding-in-the-common-language-runtime.md). @@ -2189,7 +2189,7 @@ method overload, which can optionally include an assembly display name as part of the type name. + This method only searches the current assembly instance. The `name` parameter includes the namespace but not the assembly. To search other assemblies for a type, use the method overload, which can optionally include an assembly display name as part of the type name. > [!NOTE] > If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](~/docs/framework/app-domains/type-forwarding-in-the-common-language-runtime.md). @@ -2264,7 +2264,7 @@ > [!NOTE] > If a type has been forwarded to another assembly, it is not included in the returned array. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](~/docs/framework/app-domains/type-forwarding-in-the-common-language-runtime.md). - To retrieve a collection of objects instead of an array of objects, use the property. + To retrieve a collection of objects instead of an array of objects, use the property. @@ -2595,7 +2595,7 @@ is thrown if `assemblyRef` specifies the full assembly name and the first assembly that matches the simple name has a different version, culture, or public key token. The loader does not continue probing for other assemblies that match the simple name. > [!NOTE] -> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](~/docs/framework/deployment/best-practices-for-assembly-loading.md). +> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](~/docs/framework/deployment/best-practices-for-assembly-loading.md). Whether certain permissions are granted or not granted to an assembly is based on evidence. The rules for assembly and security evidence merging are as follows: @@ -2613,7 +2613,7 @@ Reflecting on C++ executable files might throw a . This is most likely caused by the C++ compiler stripping the relocation addresses or the `.reloc` section from your executable file. To preserve the `.reloc` address for your C++ executable file, specify `/fixed:no` when you are linking. > [!NOTE] -> If both the property and the property are set, the first attempt to load the assembly uses the display name (including version, culture, and so on, as returned by the property). If the file is not found, is used to search for the assembly. If the assembly is found using , the display name is matched against the assembly. If the match fails, a is thrown. +> If both the property and the property are set, the first attempt to load the assembly uses the display name (including version, culture, and so on, as returned by the property). If the file is not found, is used to search for the assembly. If the assembly is found using , the display name is matched against the assembly. If the match fails, a is thrown. @@ -2701,7 +2701,7 @@ Reflecting on C++ executable files might throw a . This is most likely caused by the C++ compiler stripping the relocation addresses or the `.reloc` section from your executable file. To preserve the `.reloc` address for your C++ executable file, specify `/fixed:no` when you are linking. - In the .NET Framework version 2.0, processor architecture is added to assembly identity, and can be specified as part of assembly name strings. For example, "ProcessorArchitecture=msil". However, the recommended way to specify an assembly name is to create an object and pass it to an appropriate overload of the method. See . + In the .NET Framework version 2.0, processor architecture is added to assembly identity, and can be specified as part of assembly name strings. For example, "ProcessorArchitecture=msil". However, the recommended way to specify an assembly name is to create an object and pass it to an appropriate overload of the method. See . @@ -2816,7 +2816,7 @@ is thrown if `assemblyRef` specifies the full assembly name, and the first assembly that matches the simple name has a different version, culture, or public key token. The loader does not continue probing for other assemblies that match the simple name. > [!NOTE] -> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](~/docs/framework/deployment/best-practices-for-assembly-loading.md). +> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](~/docs/framework/deployment/best-practices-for-assembly-loading.md). Whether certain permissions are granted or not granted to an assembly is based on evidence. The rules for assembly and security evidence merging are as follows: @@ -2834,7 +2834,7 @@ Reflecting on C++ executable files might throw a . This is most likely caused by the C++ compiler stripping the relocation addresses or the `.reloc` section from your executable file. To preserve the `.reloc` address for your C++ executable file, specify `/fixed:no` when you are linking. > [!NOTE] -> If both the property and the property are set, the first attempt to load the assembly uses the display name (including version, culture, and so on, as returned by the property). If the file is not found, is used to search for the assembly. If the assembly is found using , the display name is matched against the assembly. If the match fails, a is thrown. +> If both the property and the property are set, the first attempt to load the assembly uses the display name (including version, culture, and so on, as returned by the property). If the file is not found, is used to search for the assembly. If the assembly is found using , the display name is matched against the assembly. If the match fails, a is thrown. If you call the method more than once on the same assembly but with a different evidence specified, the common language runtime does not throw a because the equality and integrity of the different evidence specifications cannot be determined. The evidence that first succeeds is the evidence that is used. @@ -2906,7 +2906,7 @@ If you call this method more than once on the same assembly but with a different evidence specified, the common language runtime does not throw a because the equality and integrity of the different evidence specifications cannot be determined. The evidence that first succeeds is the evidence that is used. - In the .NET Framework version 2.0, processor architecture is added to assembly identity, and can be specified as part of assembly name strings. For example, "ProcessorArchitecture=msil". However, the recommended way to specify an assembly name is to create an object and pass it to an appropriate overload of the method. See . + In the .NET Framework version 2.0, processor architecture is added to assembly identity, and can be specified as part of assembly name strings. For example, "ProcessorArchitecture=msil". However, the recommended way to specify an assembly name is to create an object and pass it to an appropriate overload of the method. See . ]]> @@ -3201,7 +3201,7 @@ - If an assembly is loaded with , and the probing path includes an assembly with the same identity but a different location, an , , or other unexpected behavior can occur. -- demands and , or , on the specified path. +- demands and , or , on the specified path. - If a native image exists for `assemblyFile`, it is not used. The assembly cannot be loaded as domain neutral. @@ -3294,7 +3294,7 @@ - If an assembly is loaded with , and the probing path includes an assembly with the same identity but a different location, an , , or other unexpected behavior can occur. -- demands and , or , on the specified path. +- demands and , or , on the specified path. - If a native image exists for `assemblyFile`, it is not used. The assembly cannot be loaded as domain neutral. @@ -3400,7 +3400,7 @@ - If an assembly is loaded with , and the probing path includes an assembly with the same identity but a different location, an , , or other unexpected behavior can occur. -- demands and , or , on the specified path. +- demands and , or , on the specified path. - If a native image exists for `assemblyFile`, it is not used. The assembly cannot be loaded as domain-neutral. @@ -3489,7 +3489,7 @@ - If an assembly is loaded with , and the probing path includes an assembly with the same identity but a different location, an , , or other unexpected behavior can occur. -- demands and , or , on the specified path. +- demands and , or , on the specified path. - If a native image exists for `assemblyFile`, it is not used. The assembly cannot be loaded as domain neutral. @@ -3630,7 +3630,7 @@ ## Remarks > [!IMPORTANT] -> The overloads of the method are obsolete and have been retained for backward compatibility. The non-obsolete alternative is . +> The overloads of the method are obsolete and have been retained for backward compatibility. The non-obsolete alternative is . ]]> @@ -3675,7 +3675,7 @@ ## Remarks > [!IMPORTANT] -> The method is obsolete and has been retained for backward compatibility. The non-obsolete alternative is . +> The method is obsolete and has been retained for backward compatibility. The non-obsolete alternative is . Applications that load assemblies with this method will be affected by upgrades of those assemblies. Therefore, do not use this method; redesign the application to use the method overload or the method overload. @@ -3725,7 +3725,7 @@ ## Remarks > [!IMPORTANT] -> The method is obsolete and has been retained for backward compatibility. The non-obsolete alternative is . +> The method is obsolete and has been retained for backward compatibility. The non-obsolete alternative is . Evidence is the set of information that constitutes input to security policy decisions, such as what permissions can be granted to code. diff --git a/xml/System.Reflection/AssemblyFlagsAttribute.xml b/xml/System.Reflection/AssemblyFlagsAttribute.xml index 0fccfc934209d..677d4240ddda0 100644 --- a/xml/System.Reflection/AssemblyFlagsAttribute.xml +++ b/xml/System.Reflection/AssemblyFlagsAttribute.xml @@ -39,14 +39,14 @@ ## Remarks The enumeration describes the assembly characteristics that can be set using this attribute. - To access the flags that have been specified for an assembly, use the property to obtain an object, then use the property to obtain an value. + To access the flags that have been specified for an assembly, use the property to obtain an object, then use the property to obtain an value. - To specify flags for a dynamic assembly, set the property of the object that you pass to the method. + To specify flags for a dynamic assembly, set the property of the object that you pass to the method. ## Examples - The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. [!code-cpp[AssemblyFlagsAttribute#1](~/samples/snippets/cpp/VS_Snippets_CLR/AssemblyFlagsAttribute/CPP/source.cpp#1)] [!code-csharp[AssemblyFlagsAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR/AssemblyFlagsAttribute/CS/source.cs#1)] @@ -127,7 +127,7 @@ to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. [!code-cpp[AssemblyFlagsAttribute#1](~/samples/snippets/cpp/VS_Snippets_CLR/AssemblyFlagsAttribute/CPP/source.cpp#1)] [!code-csharp[AssemblyFlagsAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR/AssemblyFlagsAttribute/CS/source.cs#1)] @@ -217,7 +217,7 @@ ## Examples - The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. [!code-cpp[AssemblyFlagsAttribute#1](~/samples/snippets/cpp/VS_Snippets_CLR/AssemblyFlagsAttribute/CPP/source.cpp#1)] [!code-csharp[AssemblyFlagsAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR/AssemblyFlagsAttribute/CS/source.cs#1)] diff --git a/xml/System.Reflection/AssemblyInformationalVersionAttribute.xml b/xml/System.Reflection/AssemblyInformationalVersionAttribute.xml index b257d9ec783be..d27c63d6afe2f 100644 --- a/xml/System.Reflection/AssemblyInformationalVersionAttribute.xml +++ b/xml/System.Reflection/AssemblyInformationalVersionAttribute.xml @@ -37,7 +37,7 @@ property. The string is also used in the path and registry key provided by the property and the property. If the is not applied to an assembly, the version number specified by the attribute is used instead. + The attribute defined by this class attaches additional version information to an assembly. If this attribute is applied to an assembly, the string it specifies can be obtained at run time by using the property. The string is also used in the path and registry key provided by the property and the property. If the is not applied to an assembly, the version number specified by the attribute is used instead. Although you can specify any text, a warning message appears on compilation if the string is not in the format used by the assembly version number, or if it is in that format but contains wildcard characters. This warning is harmless. diff --git a/xml/System.Reflection/AssemblyName.xml b/xml/System.Reflection/AssemblyName.xml index 82ea616f9e01d..ecd195bba5da3 100644 --- a/xml/System.Reflection/AssemblyName.xml +++ b/xml/System.Reflection/AssemblyName.xml @@ -91,11 +91,11 @@ To ensure that the names are constructed correctly, use the following properties: -- +- -- +- -- +- You can also get the name by using the `/l` option with the [Gacutil.exe (Global Assembly Cache Tool)](~/docs/framework/tools/gacutil-exe-gac-tool.md) @@ -308,12 +308,12 @@ ExampleAssembly, Version=1.0.0.0, Culture=en, PublicKeyToken=a5d015c7d5a0b012 property. + When an assembly is loaded, this value can also be obtained using the property. If the assembly was loaded as a byte array, this property returns the location of the caller of the method overload, not the location of the loaded assembly. > [!NOTE] -> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](~/docs/framework/deployment/best-practices-for-assembly-loading.md). +> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](~/docs/framework/deployment/best-practices-for-assembly-loading.md). @@ -550,7 +550,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Writing your own code to parse display names is not recommended. Instead, pass the display name to the constructor, which parses it and populates the appropriate fields of the new . - When an assembly is loaded, this value can also be obtained using the property. + When an assembly is loaded, this value can also be obtained using the property. @@ -779,7 +779,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 ## Remarks > [!IMPORTANT] -> Starting with the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], the property of an object that is returned by the method is if there is no hash algorithm for the referenced assembly, or if the hash algorithm of the referenced assembly is not identified by the enumeration. In previous versions of the .NET Framework, the property returned in this situation. +> Starting with the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], the property of an object that is returned by the method is if there is no hash algorithm for the referenced assembly, or if the hash algorithm of the referenced assembly is not identified by the enumeration. In previous versions of the .NET Framework, the property returned in this situation. @@ -951,7 +951,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 for reference assemblies. + Beginning with the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], this property always returns for reference assemblies. ]]> @@ -1328,7 +1328,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 - 1. If a component exceeds this value, no error is thrown; however, in a dynamic assembly, that component is zero. + All components of the version must be integers greater than or equal to zero. Metadata restricts the major, minor, build, and revision components for an assembly to a maximum value of - 1. If a component exceeds this value, no error is thrown; however, in a dynamic assembly, that component is zero. @@ -1385,7 +1385,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 ## Remarks information indicates, for example, that the assembly cannot execute side-by-side with other versions due to conflicts over a device driver. - Currently, always returns , and is not used by the loader. This property is reserved for a future feature. + Currently, always returns , and is not used by the loader. This property is reserved for a future feature. ]]> diff --git a/xml/System.Reflection/AssemblyVersionAttribute.xml b/xml/System.Reflection/AssemblyVersionAttribute.xml index ff1459ae71e87..97f7a2fe13904 100644 --- a/xml/System.Reflection/AssemblyVersionAttribute.xml +++ b/xml/System.Reflection/AssemblyVersionAttribute.xml @@ -49,7 +49,7 @@ \.\.\.\ > [!IMPORTANT] -> All components of the version must be integers greater than or equal to 0. Metadata restricts the major, minor, build, and revision components for an assembly to a maximum value of - 1. If a component exceeds this value, a compilation error occurs. +> All components of the version must be integers greater than or equal to 0. Metadata restricts the major, minor, build, and revision components for an assembly to a maximum value of - 1. If a component exceeds this value, a compilation error occurs. You can specify all the values or you can accept the default build number, revision number, or both by using an asterisk (*). For example, `[assembly:AssemblyVersion("2.3.25.1")]` indicates 2 as the major version, 3 as the minor version, 25 as the build number, and 1 as the revision number. A version number such as `[assembly:AssemblyVersion("1.2.*")]` specifies 1 as the major version, 2 as the minor version, and accepts the default build and revision numbers. A version number such as `[assembly:AssemblyVersion("1.2.15.*")]` specifies 1 as the major version, 2 as the minor version, 15 as the build number, and accepts the default revision number. The default build number increments daily. The default revision number is the number of seconds since midnight local time (without taking into account time zone adjustments for daylight saving time), divided by 2. @@ -65,7 +65,7 @@ ## Examples - The following example uses the attribute to assign a version number to an assembly. At compile time, this version information is stored with the assembly's metadata. At run time, the example retrieves the value of the property on a type found in the assembly to get a reference to the executing assembly, and it retrieves the assembly's version information from the property of the object returned by the method. + The following example uses the attribute to assign a version number to an assembly. At compile time, this version information is stored with the assembly's metadata. At run time, the example retrieves the value of the property on a type found in the assembly to get a reference to the executing assembly, and it retrieves the assembly's version information from the property of the object returned by the method. [!code-csharp[System.Version.Class#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Version.Class/cs/example1.cs#6)] [!code-vb[System.Version.Class#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Version.Class/vb/example1.vb#6)] diff --git a/xml/System.Reflection/Binder.xml b/xml/System.Reflection/Binder.xml index 9a57206049f43..7288ddd9ed83d 100644 --- a/xml/System.Reflection/Binder.xml +++ b/xml/System.Reflection/Binder.xml @@ -33,9 +33,9 @@ class are used by methods such as , which selects from a set of possible members to execute, based on a set of parameter types and argument values; , which selects a method based on parameter types; and so on. + Implementations of the class are used by methods such as , which selects from a set of possible members to execute, based on a set of parameter types and argument values; , which selects a method based on parameter types; and so on. - A default implementation of the class is provided by the property. + A default implementation of the class is provided by the property. @@ -124,9 +124,9 @@ , the default binder implementation provided by simply returns the first element of `match`. No selection is done. + If `bindingAttr` does not include , the default binder implementation provided by simply returns the first element of `match`. No selection is done. - This method controls the binding provided by . + This method controls the binding provided by . ]]> @@ -189,7 +189,7 @@ The binder enables a client to map the array of arguments back to its original form if the argument array has been manipulated by . Use this remap capability to get back by-reference arguments when such arguments are present. When you pass arguments by name, the binder reorders the argument array. The `state` parameter keeps track of argument reordering, thus enabling the binder's method to reorder the argument array to its original form. - The method is used by the method. + The method is used by the method. ]]> diff --git a/xml/System.Reflection/BindingFlags.xml b/xml/System.Reflection/BindingFlags.xml index 1024e6d2b548a..1938dec2925a3 100644 --- a/xml/System.Reflection/BindingFlags.xml +++ b/xml/System.Reflection/BindingFlags.xml @@ -38,9 +38,9 @@ ## Remarks These `BindingFlags` control binding for a great many classes in the `System`, `System.Reflection`, and `System.Runtime` namespaces that invoke, create, get, set, and find members and types. - `BindingFlags` are used in the following methods and other places such as : + `BindingFlags` are used in the following methods and other places such as : -- +- - @@ -48,7 +48,7 @@ - -- +- - @@ -83,7 +83,7 @@ > [!NOTE] > You must specify `Instance` or `Static` along with `Public` or `NonPublic` or no members will be returned. - The following table lists the coercions performed by the default . This table applies especially to the `ExactBinding` binding flag. + The following table lists the coercions performed by the default . This table applies especially to the `ExactBinding` binding flag. |Source Type|Target Type| |-----------------|-----------------| diff --git a/xml/System.Reflection/ConstructorInfo.xml b/xml/System.Reflection/ConstructorInfo.xml index 0bc9b32ce3b4f..a7c0cad0832a2 100644 --- a/xml/System.Reflection/ConstructorInfo.xml +++ b/xml/System.Reflection/ConstructorInfo.xml @@ -256,7 +256,7 @@ This method is a convenience method for the following overloaded version, using default values. This method cannot be overridden. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -332,7 +332,7 @@ > To create an instance of a value type that has no instance constructors, use the method. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. diff --git a/xml/System.Reflection/CustomAttributeData.xml b/xml/System.Reflection/CustomAttributeData.xml index f106244e0d3b1..eb8db82bd0b2f 100644 --- a/xml/System.Reflection/CustomAttributeData.xml +++ b/xml/System.Reflection/CustomAttributeData.xml @@ -36,19 +36,19 @@ , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. + Code that is being examined in the reflection-only context cannot be executed, so it is not always possible to examine custom attributes by creating instances of them and then examining their properties, using methods like , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. The class allows examination of custom attributes in the reflection-only context by providing an abstraction for attributes. The members of this class can be used to obtain the positional arguments and named arguments of the attribute. Use the property to get a list of structures that represent the positional arguments, and use the property to get a list of structures that represent the named arguments. > [!NOTE] -> The structure only provides information about the attribute property used to get and set the argument value. To obtain the type and value of the argument, use the property to obtain a structure. +> The structure only provides information about the attribute property used to get and set the argument value. To obtain the type and value of the argument, use the property to obtain a structure. - When you have a structure for an argument, whether named or positional, use the property to get the type and the property to get the value. + When you have a structure for an argument, whether named or positional, use the property to get the type and the property to get the value. > [!NOTE] -> For an array argument, the property returns a generic of objects. Each object in the collection represents the corresponding element of the array. +> For an array argument, the property returns a generic of objects. Each object in the collection represents the corresponding element of the array. - can be used in the execution context as well as in the reflection-only context. For example, you might want to avoid loading the assembly that contains the code for a custom attribute. Using the class is different from using methods like : + can be used in the execution context as well as in the reflection-only context. For example, you might want to avoid loading the assembly that contains the code for a custom attribute. Using the class is different from using methods like : - The properties and methods of only provide you with the values that were specified for the attribute instance, not the semantics of the constructor. For example, a string argument of an attribute might be converted internally to some other representation, and returned in a canonical form; or a property might have side effects when the actual attribute code is executed. diff --git a/xml/System.Reflection/CustomAttributeNamedArgument.xml b/xml/System.Reflection/CustomAttributeNamedArgument.xml index 05ec46ff39509..cd45f044906e8 100644 --- a/xml/System.Reflection/CustomAttributeNamedArgument.xml +++ b/xml/System.Reflection/CustomAttributeNamedArgument.xml @@ -36,7 +36,7 @@ , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. + Code that is being examined in the reflection-only context cannot be executed, so it is not always possible to examine custom attributes by creating instances of them and then examining their properties, using methods like , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. The structure is used by the class to provide access to a named argument specified for a custom attribute instance, without executing the code of the corresponding property of the custom attribute type. The property returns a structure that contains the type and value of the named argument. @@ -345,7 +345,7 @@ if the two structures are equal; otherwise, . - .]]> + .]]> @@ -385,7 +385,7 @@ if the two structures are different; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection/CustomAttributeTypedArgument.xml b/xml/System.Reflection/CustomAttributeTypedArgument.xml index 60e805e019a97..60562706656a4 100644 --- a/xml/System.Reflection/CustomAttributeTypedArgument.xml +++ b/xml/System.Reflection/CustomAttributeTypedArgument.xml @@ -36,11 +36,11 @@ , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. + Code that is being examined in the reflection-only context cannot be executed, so it is not always possible to examine custom attributes by creating instances of them and then examining their properties, using methods like , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. The structure is used by the class to provide access to the type and value of a positional argument specified for a custom attribute instance, without executing the attribute constructor. It also provides access to the type and value of a named argument without executing the code of the corresponding property of the custom attribute type. - The types and values of all the positional and named arguments of an attribute instance are provided by structures. The positional attributes returned by the property are directly represented by structures, but the named arguments returned by the property are represented by structures; to get the structure for a named argument, use the property. + The types and values of all the positional and named arguments of an attribute instance are provided by structures. The positional attributes returned by the property are directly represented by structures, but the named arguments returned by the property are represented by structures; to get the structure for a named argument, use the property. If an argument is an array of values, the property of the that represents the argument returns a generic of objects. Each object in the collection represents the corresponding element of the array. @@ -298,7 +298,7 @@ if the two structures are equal; otherwise, . - .]]> + .]]> @@ -338,7 +338,7 @@ if the two structures are different; otherwise, . - .]]> + .]]> diff --git a/xml/System.Reflection/EventInfo.xml b/xml/System.Reflection/EventInfo.xml index 3e72d8d46530a..7661a9cf7e389 100644 --- a/xml/System.Reflection/EventInfo.xml +++ b/xml/System.Reflection/EventInfo.xml @@ -57,7 +57,7 @@ The event model works equally well for single-cast and multicast delegates. When the delegate's invoke method is called, only a single object will have a method called on it. A multicast modifier can be applied to a delegate declaration, which allows multiple methods to be called when the invoke method of the delegate is called. - Calling on `EventInfo` when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. + Calling on `EventInfo` when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. @@ -155,7 +155,7 @@ ## Examples The following code example shows how to load an assembly, create an instance of a type from the assembly, create an event handler using a dynamic assembly, and hook up the dynamic event handler. All actions are performed using late binding. - The code example loads System.dll and creates an instance of the class. The example uses the method to get the event, and the property to get the delegate type for the event. + The code example loads System.dll and creates an instance of the class. The example uses the method to get the event, and the property to get the delegate type for the event. The code example gets a for the `Invoke` method of the delegate type, and from the obtains the signature of the delegate. The code example then creates a dynamic assembly with one module containing a single type named `Handler`, and gives the type a `static` method (`Shared` method in Visual Basic) named `DynamicHandler` that will be used to handle the event. @@ -878,7 +878,7 @@ remove_( handler) . Therefore, when you examine a set of objects — for example, the array returned by — the property returns only when a given member is an event. + This property overrides . Therefore, when you examine a set of objects — for example, the array returned by — the property returns only when a given member is an event. ]]> diff --git a/xml/System.Reflection/ExceptionHandlingClause.xml b/xml/System.Reflection/ExceptionHandlingClause.xml index d5a4ef9db350f..1a956160c8786 100644 --- a/xml/System.Reflection/ExceptionHandlingClause.xml +++ b/xml/System.Reflection/ExceptionHandlingClause.xml @@ -38,12 +38,12 @@ ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. You can use Ildasm.exe to examine the MSIL for the compiled code example, to see how the offsets and lengths are calculated. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. This code is part of a larger example located in the class topic. @@ -130,10 +130,10 @@ ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. This code is part of a larger example located in the class topic. @@ -183,7 +183,7 @@ clause. + A filter clause contains user-suppliedMicrosoft intermediate language (MSIL) that determines whether an exception is handled by this clause. For example, any clause containing the Visual Basic `When` keyword is a clause. > [!NOTE] > Working with exception-handling clauses requires a thorough understanding of metadata and MSIL instruction formats. Information can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics" and "Partition III: CIL Instruction Set". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the Ecma International Web site. @@ -228,10 +228,10 @@ ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. This code is part of a larger example located in the class topic. @@ -287,10 +287,10 @@ ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. This code is part of a larger example located in the class topic. @@ -346,10 +346,10 @@ ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. This code is part of a larger example located in the class topic. @@ -434,10 +434,10 @@ ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. This code is part of a larger example located in the class topic. @@ -493,10 +493,10 @@ ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. This code is part of a larger example located in the class topic. diff --git a/xml/System.Reflection/ExceptionHandlingClauseOptions.xml b/xml/System.Reflection/ExceptionHandlingClauseOptions.xml index ba60c674e4579..346d3939c5963 100644 --- a/xml/System.Reflection/ExceptionHandlingClauseOptions.xml +++ b/xml/System.Reflection/ExceptionHandlingClauseOptions.xml @@ -40,7 +40,7 @@ ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. > [!NOTE] > Not all computer languages can generate Filter clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. diff --git a/xml/System.Reflection/FieldInfo.xml b/xml/System.Reflection/FieldInfo.xml index 6db8733b5a4b8..1189a1370d0fc 100644 --- a/xml/System.Reflection/FieldInfo.xml +++ b/xml/System.Reflection/FieldInfo.xml @@ -53,7 +53,7 @@ ## Examples - The following example uses the method to get the field-related information from the class, and then displays field attributes. + The following example uses the method to get the field-related information from the class, and then displays field attributes. [!code-cpp[FieldInfo#1](~/samples/snippets/cpp/VS_Snippets_CLR/FieldInfo/CPP/fieldinfo.cpp#1)] [!code-csharp[FieldInfo#1](~/samples/snippets/csharp/VS_Snippets_CLR/FieldInfo/CS/fieldinfo.cs#1)] @@ -319,7 +319,7 @@ ## Examples - The following code example uses the method to get objects for the fields of a type, gets a structure for each field, and then retrieves the objects from the handles using this overload of the method. + The following code example uses the method to get objects for the fields of a type, gets a structure for each field, and then retrieves the objects from the handles using this overload of the method. [!code-cpp[FieldInfo_GetFieldFromHandle#1](~/samples/snippets/cpp/VS_Snippets_CLR/FieldInfo_GetFieldFromHandle/CPP/fieldinfo_getfieldfromhandle.cpp#1)] [!code-csharp[FieldInfo_GetFieldFromHandle#1](~/samples/snippets/csharp/VS_Snippets_CLR/FieldInfo_GetFieldFromHandle/CS/fieldinfo_getfieldfromhandle.cs#1)] @@ -383,7 +383,7 @@ Implementations are compatible in some cases. For example, a single implementation is shared by all types that are constructed from a particular generic type definition by using reference types for the generic type arguments. For example, `MyType`, `MyType`, and `MyType` all share the same implementation. In this situation, the object that is returned represents a field on the type that `declaringType` specifies, regardless of the original source of `handle`. This practice is not recommended, because it works only if the generic type arguments of the constructed type are reference types. - If a generic argument is a value type, the runtime type handle of the constructed type is not compatible with runtime field handles from constructions that have a reference type in the same generic parameter position, or that have a different value type in that position. In that case, the only way to use the overload is to ensure that `declaringType` is the runtime type handle for the constructed type that `handle` belongs to. + If a generic argument is a value type, the runtime type handle of the constructed type is not compatible with runtime field handles from constructions that have a reference type in the same generic parameter position, or that have a different value type in that position. In that case, the only way to use the overload is to ensure that `declaringType` is the runtime type handle for the constructed type that `handle` belongs to. @@ -617,7 +617,7 @@ > Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked through reflection whenever the code is fully trusted. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -737,7 +737,7 @@ ## Remarks The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. - The visibility of a field is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. + The visibility of a field is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. @@ -745,7 +745,7 @@ The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. > [!NOTE] -> The Visual Basic and C# languages cannot define fields with visibility; that access level appears only in the C++ example. +> The Visual Basic and C# languages cannot define fields with visibility; that access level appears only in the C++ example. [!code-cpp[Classic FieldInfo.IsAssembly Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp#1)] [!code-csharp[Classic FieldInfo.IsAssembly Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CS/source.cs#1)] @@ -790,7 +790,7 @@ if the only visibility modifier is `protected`. This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. + The visibility of a field is exactly described by if the only visibility modifier is `protected`. This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such fields. @@ -798,7 +798,7 @@ The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. > [!NOTE] -> The Visual Basic and C# languages cannot define fields with visibility; that access level appears only in the C++ example. +> The Visual Basic and C# languages cannot define fields with visibility; that access level appears only in the C++ example. [!code-cpp[Classic FieldInfo.IsAssembly Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp#1)] [!code-csharp[Classic FieldInfo.IsAssembly Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CS/source.cs#1)] @@ -845,7 +845,7 @@ ## Remarks If a field has level visibility, it can be called from any member in a derived class that is also in the same assembly, but not from any other type. - The visibility of a field is exactly described by if the visibility modifier is `protected private` in C++. Fields with this visibility cannot be defined in Visual Basic or C#. + The visibility of a field is exactly described by if the visibility modifier is `protected private` in C++. Fields with this visibility cannot be defined in Visual Basic or C#. @@ -853,7 +853,7 @@ The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. > [!NOTE] -> The Visual Basic and C# languages cannot define fields with visibility; that access level appears only in the C++ example. +> The Visual Basic and C# languages cannot define fields with visibility; that access level appears only in the C++ example. [!code-cpp[Classic FieldInfo.IsAssembly Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp#1)] [!code-csharp[Classic FieldInfo.IsAssembly Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CS/source.cs#1)] @@ -902,7 +902,7 @@ The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. - The visibility of a field is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). + The visibility of a field is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). @@ -910,7 +910,7 @@ The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. > [!NOTE] -> The Visual Basic and C# languages cannot define fields with visibility; that access level appears only in the C++ example. +> The Visual Basic and C# languages cannot define fields with visibility; that access level appears only in the C++ example. [!code-cpp[Classic FieldInfo.IsAssembly Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CPP/source.cpp#1)] [!code-csharp[Classic FieldInfo.IsAssembly Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic FieldInfo.IsAssembly Example/CS/source.cs#1)] @@ -957,9 +957,9 @@ ## Remarks If the returned value is `true`, the field can only be initialized, and is read-only thereafter. - To get the `IsInitOnly` property, first get the class `Type`. From the `Type`, get the `FieldInfo`. From the `FieldInfo`, get the `IsInitOnly` property. To access a non-public field, combine with either or both of and in the `GetField` method. + To get the `IsInitOnly` property, first get the class `Type`. From the `Type`, get the `FieldInfo`. From the `FieldInfo`, get the `IsInitOnly` property. To access a non-public field, combine with either or both of and in the `GetField` method. - The `IsInitOnly` property is set when the attribute is set. + The `IsInitOnly` property is set when the attribute is set. @@ -1254,7 +1254,7 @@ Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. For more information about reflection and transparency, see [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md). For information about transparency, see [Security Changes](~/docs/framework/security/security-changes.md). @@ -1302,7 +1302,7 @@ Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. For more information about reflection and transparency, see [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md). For information about transparency, see [Security Changes](~/docs/framework/security/security-changes.md). @@ -1350,7 +1350,7 @@ Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), then the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. For more information about reflection and transparency, see [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md). For information about transparency, see [Security Changes](~/docs/framework/security/security-changes.md). @@ -1502,7 +1502,7 @@ . Therefore, when you examine a set of objects — for example, the array returned by — the property returns only when a given member is a field. + This property overrides . Therefore, when you examine a set of objects — for example, the array returned by — the property returns only when a given member is a field. @@ -1641,7 +1641,7 @@ > Fully trusted code has the permissions that are needed to access and invoke private constructors, methods, fields, and properties using reflection. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1728,7 +1728,7 @@ > Fully trusted code has the permissions that are needed to access and invoke private constructors, methods, fields, and properties using reflection. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1785,7 +1785,7 @@ ## Remarks > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. diff --git a/xml/System.Reflection/GenericParameterAttributes.xml b/xml/System.Reflection/GenericParameterAttributes.xml index 70699dfef1fd2..0141cc26c7c70 100644 --- a/xml/System.Reflection/GenericParameterAttributes.xml +++ b/xml/System.Reflection/GenericParameterAttributes.xml @@ -38,7 +38,7 @@ ## Examples - The following code example defines a generic type `Test` with two type parameters. The second type parameter has a base class constraint and a reference type constraint. When the program executes, the constraints are examined using the property and the method. + The following code example defines a generic type `Test` with two type parameters. The second type parameter has a base class constraint and a reference type constraint. When the program executes, the constraints are examined using the property and the method. [!code-cpp[System.Type.GetGenericParameterConstraints#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Type.GetGenericParameterConstraints/CPP/source.cpp#1)] [!code-csharp[System.Type.GetGenericParameterConstraints#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Type.GetGenericParameterConstraints/CS/source.cs#1)] diff --git a/xml/System.Reflection/ICustomAttributeProvider.xml b/xml/System.Reflection/ICustomAttributeProvider.xml index d5586b177b678..846ee3d68c802 100644 --- a/xml/System.Reflection/ICustomAttributeProvider.xml +++ b/xml/System.Reflection/ICustomAttributeProvider.xml @@ -73,7 +73,7 @@ on or when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. + Calling on or when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. This method returns custom attributes defined directly on a non-inherited member only. @@ -125,7 +125,7 @@ This method returns custom attributes defined directly on a non-inherited member only. - Calling on or when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. + Calling on or when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. ]]> diff --git a/xml/System.Reflection/IReflect.xml b/xml/System.Reflection/IReflect.xml index a53b206865283..7c9ed7e8a341f 100644 --- a/xml/System.Reflection/IReflect.xml +++ b/xml/System.Reflection/IReflect.xml @@ -102,7 +102,7 @@ flag specifies that non-public methods are included in the search. The flag specifies that public methods are included in the search. + The match is based upon a name. Each field must have a unique name. The flag specifies that non-public methods are included in the search. The flag specifies that public methods are included in the search. ]]> @@ -142,7 +142,7 @@ method retrieves an array of objects by using the name and binding attribute that correspond to all public members or to all members that match a specified name. The case of the specified name is observed or ignored, as specified by . + The method retrieves an array of objects by using the name and binding attribute that correspond to all public members or to all members that match a specified name. The case of the specified name is observed or ignored, as specified by . ]]> @@ -471,7 +471,7 @@ > [!NOTE] > The array of parameter modifiers passed to the method must contain a single parameter modifier. Only the first parameter modifier is considered when determining which argument needs to be passed by reference when exposed to COM. - The binder finds all matching methods, in accordance with the type of binding requested (, , and so on). The set of methods is filtered by the name, number of arguments, and a set of search modifiers defined in the binder. After the method is selected, it is invoked, and accessibility is checked at that point. The search may control which set of methods is searched based upon the accessibility attribute associated with the method. selects the method to be invoked. The default binder selects the most specific match. + The binder finds all matching methods, in accordance with the type of binding requested (, , and so on). The set of methods is filtered by the name, number of arguments, and a set of search modifiers defined in the binder. After the method is selected, it is invoked, and accessibility is checked at that point. The search may control which set of methods is searched based upon the accessibility attribute associated with the method. selects the method to be invoked. The default binder selects the most specific match. Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked through reflection whenever the code is fully trusted. diff --git a/xml/System.Reflection/ImageFileMachine.xml b/xml/System.Reflection/ImageFileMachine.xml index 8bc8bb13d3eaf..64a18f6dceba3 100644 --- a/xml/System.Reflection/ImageFileMachine.xml +++ b/xml/System.Reflection/ImageFileMachine.xml @@ -29,7 +29,7 @@ method. + To obtain this value for a module, use the method. > [!NOTE] > The values in this enumeration correspond to the constants IMAGE_FILE_MACHINE_I386, IMAGE_FILE_MACHINE_IA64, and IMAGE_FILE_MACHINE_AMD64 in the unmanaged Win32 API, which are accessed by the unmanaged `GetPEKind` function. diff --git a/xml/System.Reflection/InterfaceMapping.xml b/xml/System.Reflection/InterfaceMapping.xml index 9d7afc46fb3ce..ff2c78f4bc7ef 100644 --- a/xml/System.Reflection/InterfaceMapping.xml +++ b/xml/System.Reflection/InterfaceMapping.xml @@ -36,7 +36,7 @@ ## Remarks Use the structure when a type implements interface methods that use method names other than those specified by the interface, or when a type implements multiple interfaces which have a method with the same name. - To obtain an structure, use the method. + To obtain an structure, use the method. ]]> diff --git a/xml/System.Reflection/LocalVariableInfo.xml b/xml/System.Reflection/LocalVariableInfo.xml index c166321be6170..fa0fd1aca126c 100644 --- a/xml/System.Reflection/LocalVariableInfo.xml +++ b/xml/System.Reflection/LocalVariableInfo.xml @@ -36,7 +36,7 @@ property. Use the method to obtain the for a object. + To get a list of local variables in a method, use the property. Use the method to obtain the for a object. > [!NOTE] > Local variable names are not persisted in metadata. In Microsoft intermediate language (MSIL), local variables are accessed by their position in the local variable signature. diff --git a/xml/System.Reflection/MemberInfo.xml b/xml/System.Reflection/MemberInfo.xml index 434aefdcc3bf8..0c09777487946 100644 --- a/xml/System.Reflection/MemberInfo.xml +++ b/xml/System.Reflection/MemberInfo.xml @@ -173,7 +173,7 @@ - If the `Type` object from which this `MemberInfo` object was obtained did not declare this member, the property will represent one of its base types. -- If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. +- If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. @@ -263,7 +263,7 @@ method. + This method ignores the `inherit` parameter for properties and events. To search the inheritance chain for attributes on properties and events, use the appropriate overloads of the method. > [!NOTE] > In the .NET Framework version 2.0, this method returns security attributes on methods, constructors, and types if they are stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](http://msdn.microsoft.com/en-us/9eeddee8-ca89-4440-b84b-fd613f590cd5). @@ -318,7 +318,7 @@ method. + This method ignores the `inherit` parameter for properties and events. To search the inheritance chain for attributes on properties and events, use the appropriate overloads of the method. > [!NOTE] > In the .NET Framework version 2.0, this method returns security attributes on methods, constructors, and types if the attributes are stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](http://msdn.microsoft.com/en-us/9eeddee8-ca89-4440-b84b-fd613f590cd5). @@ -367,7 +367,7 @@ and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. + Use this method to examine the custom attributes of code in the reflection-only context, in cases where the custom attributes themselves are defined in code that is loaded into the reflection-only context. Methods like and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and for example code, see the class. This method gets custom attribute data for types, nested types, and type members, because the class and the classes in the namespace that represent type members all derive from . @@ -445,7 +445,7 @@ method. + This method ignores the `inherit` parameter for properties and events. To search the inheritance chain for attributes on properties and events, use the appropriate overloads of the method. > [!NOTE] > In the .NET Framework version 2.0, this method returns `true` if a type, method, or constructor has security attributes stored in the new metadata format. Assemblies compiled with version 2.0 use this format. Dynamic assemblies and assemblies compiled with earlier versions of the .NET Framework use the old XML format. See [Emitting Declarative Security Attributes](http://msdn.microsoft.com/en-us/9eeddee8-ca89-4440-b84b-fd613f590cd5). @@ -593,7 +593,7 @@ ## Examples - The following code example declares a class that inherits and overrides . The example obtains objects for the class's `ToString` method and for the inherited method, and displays the names of the modules in which the two methods are declared. + The following code example declares a class that inherits and overrides . The example obtains objects for the class's `ToString` method and for the inherited method, and displays the names of the modules in which the two methods are declared. [!code-cpp[System.Reflection.MemberInfo.Module#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Reflection.MemberInfo.Module/cpp/source.cpp#1)] [!code-csharp[System.Reflection.MemberInfo.Module#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Reflection.MemberInfo.Module/CS/source.cs#1)] @@ -753,12 +753,12 @@ ## Remarks The `ReflectedType` property retrieves the object that was used to obtain this instance of `MemberInfo`. This may differ from the value of the property if this object represents a member that is inherited from a base class. - If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. + If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. ## Examples - The following code example shows how the changes when the member is viewed from a obtained from type and from a obtained from the class itself, which inherits but does not override . + The following code example shows how the changes when the member is viewed from a obtained from type and from a obtained from the class itself, which inherits but does not override . [!code-cpp[Classic MemberInfo.ReflectedType Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic MemberInfo.ReflectedType Example/CPP/source.cpp#1)] [!code-csharp[Classic MemberInfo.ReflectedType Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic MemberInfo.ReflectedType Example/CS/source.cs#1)] diff --git a/xml/System.Reflection/MemberTypes.xml b/xml/System.Reflection/MemberTypes.xml index 15b82b206ac3e..58e5254b68c40 100644 --- a/xml/System.Reflection/MemberTypes.xml +++ b/xml/System.Reflection/MemberTypes.xml @@ -38,33 +38,33 @@ ## Remarks These enumeration values are returned by the following properties: -- . +- . -- . +- . -- . +- . -- . +- . -- . +- . -- . +- . -- . +- . To obtain the value for a type: 1. Get a object that represents that type. -2. Retrieve the value of the property. +2. Retrieve the value of the property. To get the values for the members of a type.: 1. Get a object that represents that type. -2. Retrieve the array that represents the members of that type by calling the method. +2. Retrieve the array that represents the members of that type by calling the method. -3. Retrieve the value of the From the property for each member in the array. A `switch` statement in C# or `Select Case` statement in Visual Basic is typically used to process member types. +3. Retrieve the value of the From the property for each member in the array. A `switch` statement in C# or `Select Case` statement in Visual Basic is typically used to process member types. matches CorTypeAttr as defined in the corhdr.h file. diff --git a/xml/System.Reflection/MethodBase.xml b/xml/System.Reflection/MethodBase.xml index f4fd67bd765e5..367579b587fc8 100644 --- a/xml/System.Reflection/MethodBase.xml +++ b/xml/System.Reflection/MethodBase.xml @@ -228,7 +228,7 @@ Similarly, the property parameter returns `true` for any constructor in an open type, even though constructors cannot have type parameters of their own. - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ]]> @@ -304,7 +304,7 @@ that is returned by is obtained from the generic type definition (that is, returns `true`). Therefore, it does not reflect the type arguments that were used when the method was called. For example, if a method `M()` is defined on a generic type `C` (`C(Of T)` in Visual Basic), and is called from `C.M()`, then returns `C.M()` (`C(Of T).M()` in Visual Basic). + If the currently executing method is defined on a generic type, the that is returned by is obtained from the generic type definition (that is, returns `true`). Therefore, it does not reflect the type arguments that were used when the method was called. For example, if a method `M()` is defined on a generic type `C` (`C(Of T)` in Visual Basic), and is called from `C.M()`, then returns `C.M()` (`C(Of T).M()` in Visual Basic). If the currently executing method is a generic method, returns the generic method definition. If the generic method is defined on a generic type, the is obtained from the generic type definition. @@ -372,7 +372,7 @@ Generic constructors are not supported in the .NET Framework version 2.0. This property throws if not overridden in a derived class, so an exception is thrown if the current instance is of type . - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ]]> @@ -452,12 +452,12 @@ ## Examples - The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. + The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their types and index order. The property is used to obtain a list of exception-handling clauses. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. [!code-cpp[MethodBody#1](~/samples/snippets/cpp/VS_Snippets_CLR/MethodBody/cpp/source.cpp#1)] [!code-csharp[MethodBody#1](~/samples/snippets/csharp/VS_Snippets_CLR/MethodBody/CS/source.cs#1)] @@ -713,7 +713,7 @@ ## Remarks This is a convenience method that calls the method overload, passing for `invokeAttr` and `null` for `binder` and `culture`. - If the invoked method throws an exception, the method returns the exception. + If the invoked method throws an exception, the method returns the exception. To invoke a static method using its object, pass `null` for `obj`. @@ -721,7 +721,7 @@ > If this method overload is used to invoke an instance constructor, the object supplied for `obj` is reinitialized; that is, all instance initializers are executed. The return value is `null`. If a class constructor is invoked, the class is reinitialized; that is, all class initializers are executed. The return value is `null`. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -840,14 +840,14 @@ If the invoked method throws an exception, `TargetInvocationException.GetException` returns the exception. This implementation throws a `NotSupportedException`. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ## Examples - The following example demonstrates all members of the class using an overload of . The private method `CanConvertFrom` finds compatible types for a given type. For another example of invoking members in a custom binding scenario, see [Dynamically Loading and Using Types](~/docs/framework/reflection-and-codedom/dynamically-loading-and-using-types.md). + The following example demonstrates all members of the class using an overload of . The private method `CanConvertFrom` finds compatible types for a given type. For another example of invoking members in a custom binding scenario, see [Dynamically Loading and Using Types](~/docs/framework/reflection-and-codedom/dynamically-loading-and-using-types.md). [!code-cpp[Binder_1#1](~/samples/snippets/cpp/VS_Snippets_CLR/Binder_1/CPP/binder.cpp#1)] [!code-csharp[Binder_1#1](~/samples/snippets/csharp/VS_Snippets_CLR/Binder_1/CS/binder.cs#1)] @@ -961,7 +961,7 @@ ## Remarks The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. - The visibility of a method or constructor is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. + The visibility of a method or constructor is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. @@ -969,7 +969,7 @@ The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. > [!NOTE] -> The Visual Basic and C# languages cannot define methods with visibility; that access level appears only in the C++ example. +> The Visual Basic and C# languages cannot define methods with visibility; that access level appears only in the C++ example. [!code-cpp[Classic MethodBase.IsAssembly Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CPP/source.cpp#1)] [!code-csharp[Classic MethodBase.IsAssembly Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CS/source.cs#1)] @@ -1021,7 +1021,7 @@ ## Remarks > [!NOTE] -> The property returns `false` for a object in a dynamic type, unless the flag was included in the `attributes` parameter when the constructor was defined. Omitting the flag does not affect the correctness of the emitted constructor. +> The property returns `false` for a object in a dynamic type, unless the flag was included in the `attributes` parameter when the constructor was defined. Omitting the flag does not affect the correctness of the emitted constructor. ]]> @@ -1062,7 +1062,7 @@ if the only visibility modifier is `protected`. This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. + The visibility of a method or constructor is exactly described by if the only visibility modifier is `protected`. This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++); use the property to identify such methods. @@ -1070,7 +1070,7 @@ The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. > [!NOTE] -> The Visual Basic and C# languages cannot define methods with visibility; that access level appears only in the C++ example. +> The Visual Basic and C# languages cannot define methods with visibility; that access level appears only in the C++ example. [!code-cpp[Classic MethodBase.IsAssembly Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CPP/source.cpp#1)] [!code-csharp[Classic MethodBase.IsAssembly Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CS/source.cs#1)] @@ -1115,7 +1115,7 @@ if the visibility modifier is `protected private` in C++. Methods with this visibility cannot be defined in Visual Basic or C#. + The visibility of a method or constructor is exactly described by if the visibility modifier is `protected private` in C++. Methods with this visibility cannot be defined in Visual Basic or C#. @@ -1123,7 +1123,7 @@ The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. > [!NOTE] -> The Visual Basic and C# languages cannot define methods with visibility; that access level appears only in the C++ example. +> The Visual Basic and C# languages cannot define methods with visibility; that access level appears only in the C++ example. [!code-cpp[Classic MethodBase.IsAssembly Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CPP/source.cpp#1)] [!code-csharp[Classic MethodBase.IsAssembly Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CS/source.cs#1)] @@ -1168,11 +1168,11 @@ visibility, it can be called from any member in a derived class or any member in the same assembly, but not from any other type. + If a type member has visibility, it can be called from any member in a derived class or any member in the same assembly, but not from any other type. The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. - The visibility of a method or constructor is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). + The visibility of a method or constructor is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic, `protected public` in C++). @@ -1180,7 +1180,7 @@ The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. > [!NOTE] -> The Visual Basic and C# languages cannot define methods with visibility; that access level appears only in the C++ example. +> The Visual Basic and C# languages cannot define methods with visibility; that access level appears only in the C++ example. [!code-cpp[Classic MethodBase.IsAssembly Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CPP/source.cpp#1)] [!code-csharp[Classic MethodBase.IsAssembly Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic MethodBase.IsAssembly Example/CS/source.cs#1)] @@ -1286,7 +1286,7 @@ > [!NOTE] > Generics are not supported by default; this property returns `false` if not overridden in a derived class. Generic constructors are not supported in the .NET Framework version 2.0, so this property returns `false` if the current instance is of type . - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ]]> @@ -1333,16 +1333,16 @@ - For each object in the array returned by the method: - - The property is `true`. + - The property is `true`. - - The property returns the current instance. + - The property returns the current instance. - - The property is the same as the position of the object in the array. + - The property is the same as the position of the object in the array. > [!NOTE] > Generics are not supported by default; this property returns `false` if not overridden in a derived class. Generic constructors are not supported in the .NET Framework version 2.0, so this property returns `false` if the current instance is of type . - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ]]> @@ -1532,7 +1532,7 @@ Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. For more information about reflection and transparency, see [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md). For information about transparency, see [Security Changes](~/docs/framework/security/security-changes.md). @@ -1580,7 +1580,7 @@ Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. For more information about reflection and transparency, see [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md). For information about transparency, see [Security Changes](~/docs/framework/security/security-changes.md). @@ -1622,7 +1622,7 @@ The , , and properties report the transparency level of the method or constructor at its current trust level, as determined by the common language runtime (CLR). Using these properties is much simpler than examining the security annotations of an assembly and its types and members, checking the current trust level, and attempting to duplicate the runtime's rules. > [!IMPORTANT] -> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. +> For partial-trust assemblies, the value of this property depends on the current trust level of the assembly. If the assembly is loaded into a partially trusted application domain (for example, into a sandboxed application domain), the runtime ignores the security annotations of the assembly. The assembly and all its types are treated as transparent. The runtime pays attention to the security annotations of a partial-trust assembly only when that assembly is loaded into a fully trusted application domain (for example, into the default application domain of a desktop application). By contrast, a trusted assembly (that is, a strong-named assembly that is installed in the global assembly cache) is always loaded with full trust regardless of the trust level of the application domain, so its current trust level is always fully trusted. You can determine the current trust levels of assemblies and application domains by using the and properties. For more information about reflection and transparency, see [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md). For information about transparency, see [Security Changes](~/docs/framework/security/security-changes.md). @@ -1772,7 +1772,7 @@ If MethodInfo.IsVirtual AndAlso Not MethodInfo.IsFinal Then If `IsVirtual` is `false` or `IsFinal` is `true`, then the method cannot be overridden. - You can determine whether the current method overrides a method in a base class by calling the method. The following example implements an `IsOverride` method that does this. + You can determine whether the current method overrides a method in a base class by calling the method. The following example implements an `IsOverride` method that does this. [!code-csharp[system.reflection.methodinfo.getbasedefinition#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.reflection.methodinfo.getbasedefinition/cs/IsOverride1.cs#2)] [!code-vb[system.reflection.methodinfo.getbasedefinition#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.methodinfo.getbasedefinition/vb/IsOverride1.vb#2)] diff --git a/xml/System.Reflection/MethodBody.xml b/xml/System.Reflection/MethodBody.xml index 1c5fda0f70552..815111021d965 100644 --- a/xml/System.Reflection/MethodBody.xml +++ b/xml/System.Reflection/MethodBody.xml @@ -42,12 +42,12 @@ ## Examples - The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. + The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The example uses the property to obtain a list of objects and then displays their types and index order. The property is used to obtain a list of exception-handling clauses. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. [!code-cpp[MethodBody#1](~/samples/snippets/cpp/VS_Snippets_CLR/MethodBody/cpp/source.cpp#1)] [!code-csharp[MethodBody#1](~/samples/snippets/csharp/VS_Snippets_CLR/MethodBody/CS/source.cs#1)] @@ -124,10 +124,10 @@ ## Examples - The following code example defines a test method named `MethodBodyExample` and displays information about its exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects. + The following code example defines a test method named `MethodBodyExample` and displays information about its exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects. > [!NOTE] -> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. +> Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. This code example is part of a larger example provided for the class. @@ -222,7 +222,7 @@ ## Examples - The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The and properties are displayed. + The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The and properties are displayed. This code example is part of a larger example provided for the class. @@ -307,7 +307,7 @@ ## Examples - The following code example defines a test method named `MethodBodyExample` and displays its local variable information. The method is used to obtain a object for the test method. The property is used to obtain a list of objects. + The following code example defines a test method named `MethodBodyExample` and displays its local variable information. The method is used to obtain a object for the test method. The property is used to obtain a list of objects. This code example is part of a larger example provided for the class. @@ -361,7 +361,7 @@ ## Examples - The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The and properties are displayed. + The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The and properties are displayed. This code example is part of a larger example provided for the class. diff --git a/xml/System.Reflection/MethodInfo.xml b/xml/System.Reflection/MethodInfo.xml index 03e557f3563be..b7e5650a1b01d 100644 --- a/xml/System.Reflection/MethodInfo.xml +++ b/xml/System.Reflection/MethodInfo.xml @@ -60,7 +60,7 @@ - You can instantiate a object that represents a constructed generic method from one that represents a generic method definition by calling the method. - You can instantiate a instances by calling the or method, or by calling the method of a object that represents a generic method definition. + You can instantiate a instances by calling the or method, or by calling the method of a object that represents a generic method definition. For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. @@ -267,7 +267,7 @@ 1. Get a object that represents the type (the class or structure) that contains the property. If you are working with an object (an instance of a type), you can call its method. Otherwise, you can use the C# operator or the Visual Basic operator, as the example illustrates. -2. Get a object that represents the method in which you're interested. You can do this by getting an array of all methods from the method and then iterating the elements in the array, or you can retrieve the object that represents the method directly by calling the method and specifying the method name. +2. Get a object that represents the method in which you're interested. You can do this by getting an array of all methods from the method and then iterating the elements in the array, or you can retrieve the object that represents the method directly by calling the method and specifying the method name. 3. Call the method to get the value of the object that represents the base method definition. @@ -331,7 +331,7 @@ - If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example for the property. - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. @@ -631,7 +631,7 @@ public: . Therefore, when you examine a set of objects — for example, the array returned by — the property returns only when a given member is a method. + This property overrides . Therefore, when you examine a set of objects — for example, the array returned by — the property returns only when a given member is a method. To get the `MemberType` property, first get the class `Type`. From the `Type`, get the `MethodInfo`. From the `MethodInfo`, get the `MemberType`. diff --git a/xml/System.Reflection/Module.xml b/xml/System.Reflection/Module.xml index c7ab8b52a7841..52e21041a4783 100644 --- a/xml/System.Reflection/Module.xml +++ b/xml/System.Reflection/Module.xml @@ -542,7 +542,7 @@ and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and example code, see the class. + Use this method to examine the custom attributes of code in the reflection-only context, in cases where the custom attributes themselves are defined in code that is loaded into the reflection-only context. Methods such as and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and example code, see the class. ]]> @@ -1098,7 +1098,7 @@ > [!NOTE] > If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](~/docs/framework/app-domains/type-forwarding-in-the-common-language-runtime.md). - A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . + A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . @@ -1180,7 +1180,7 @@ > [!NOTE] > If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](~/docs/framework/app-domains/type-forwarding-in-the-common-language-runtime.md). - A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . + A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . @@ -1267,7 +1267,7 @@ > [!NOTE] > If the type has been forwarded to another assembly, it is still returned by this method. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](~/docs/framework/app-domains/type-forwarding-in-the-common-language-runtime.md). - A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . + A type can be retrieved from a specific module using . Calling on the module that contains the manifest will not search the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . @@ -1788,7 +1788,7 @@ method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + Use the method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the ECMA Web site. @@ -1898,7 +1898,7 @@ method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + Use the method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the ECMA Web site. @@ -1977,7 +1977,7 @@ - Case 5: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. The context for this method has no enclosing generic type or generic method. - For each case, the example first constructs a that represents the called method, and then resolves the token using the method overload, using the and methods to get the values for the `genericTypeArguments` and `genericMethodArguments` parameters. This technique works in all cases, because the methods return for non-generic contexts. The example compares the resolved with the constructed . + For each case, the example first constructs a that represents the called method, and then resolves the token using the method overload, using the and methods to get the values for the `genericTypeArguments` and `genericMethodArguments` parameters. This technique works in all cases, because the methods return for non-generic contexts. The example compares the resolved with the constructed . The example then attempts to use the method overload to resolve the token. This works in cases 3, 4, and 5, because the method calls do not depend on the generic context. In cases 1 and 2, an exception is thrown because there is insufficient information to resolve the token. @@ -2034,7 +2034,7 @@ method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericMethodArguments`. It is always safe to provide these arguments, even when they are not needed. + Use the method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericMethodArguments`. It is always safe to provide these arguments, even when they are not needed. > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the ECMA Web site. @@ -2058,7 +2058,7 @@ - Case 5: The generic method `GM1` is called, specifying and for the type arguments of the generic type and the generic method, respectively. The context for this method has no enclosing generic type or generic method. - For each case, the example first constructs a that represents the called method, and then resolves the token using the method overload, using the and methods to get the values for the `genericTypeArguments` and `genericMethodArguments` parameters. This technique works in all cases, because the methods return for non-generic contexts. The example compares the resolved with the constructed . + For each case, the example first constructs a that represents the called method, and then resolves the token using the method overload, using the and methods to get the values for the `genericTypeArguments` and `genericMethodArguments` parameters. This technique works in all cases, because the methods return for non-generic contexts. The example compares the resolved with the constructed . The example then attempts to use the method overload to resolve the token. This works in cases 3, 4, and 5, because the method calls do not depend on the generic context. In cases 1 and 2, an exception is thrown because there is insufficient information to resolve the token. @@ -2252,7 +2252,7 @@ method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. + Use the method on the type where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. Use the method on the method where `metadataToken` is in scope to obtain an array of generic type arguments for `genericTypeArguments`. It is always safe to provide these arguments, even when they are not needed. > [!NOTE] > Information about metadata tokens can be found in the Common Language Infrastructure (CLI) documentation, especially "Partition II: Metadata Definition and Semantics". The documentation is available online; see [ECMA C# and Common Language Infrastructure Standards](http://go.microsoft.com/fwlink/?LinkID=99212) on MSDN and [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://go.microsoft.com/fwlink/?LinkID=65552) on the ECMA Web site. diff --git a/xml/System.Reflection/ParameterInfo.xml b/xml/System.Reflection/ParameterInfo.xml index 634928291320f..a71eab4f4bbcc 100644 --- a/xml/System.Reflection/ParameterInfo.xml +++ b/xml/System.Reflection/ParameterInfo.xml @@ -130,7 +130,7 @@ ## Remarks This method utilizes the method. - To get the array, first get the method or the constructor and then call . + To get the array, first get the method or the constructor and then call . @@ -288,7 +288,7 @@ This method utilizes the method. - To get the array, first get the method or the constructor and then call . + To get the array, first get the method or the constructor and then call . ]]> @@ -361,7 +361,7 @@ method. + This method ignores the `inherit` parameter. To search the inheritance chain for attributes on parameters, use the appropriate overloads of the method. @@ -413,7 +413,7 @@ method. + This method ignores the `inherit` parameter. To search the inheritance chain for attributes on parameters, use the appropriate overloads of the method. ]]> @@ -452,7 +452,7 @@ and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and example code, see the class. + Use this method to examine the custom attributes of code in the reflection-only context, in cases where the custom attributes themselves are defined in code that is loaded into the reflection-only context. Methods such as and cannot be used in such cases, because they create instances of the attributes. Code in the reflection-only context cannot be executed. For more information and example code, see the class. ]]> @@ -529,7 +529,7 @@ method. + This method implements the method. ]]> @@ -645,7 +645,7 @@ method. + This method ignores the `inherit` parameter. To search the inheritance chain for attributes on parameters, use the appropriate overloads of the method. @@ -705,20 +705,20 @@ This method utilizes the `In` flag of the `ParameterAttributes` enumerator. - To get the array, first get the method or the constructor and then call . + To get the array, first get the method or the constructor and then call . ## Examples - The following example shows how to test method parameters for the , , and attributes. + The following example shows how to test method parameters for the , , and attributes. The example contains a `DefineMethod` method that does the following: - Creates a dynamic assembly containing a `MyType` type. -- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . +- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . -- Calls to complete the type. +- Calls to complete the type. After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. @@ -763,7 +763,7 @@ This method utilizes the `Lcid` flag of the `ParameterAttributes` enumerator. - To get the array, first get the method or the constructor and then call . + To get the array, first get the method or the constructor and then call . ]]> @@ -808,20 +808,20 @@ This method utilizes the `Optional` flag of the `ParameterAttributes` enumerator. - To get the array, first get the method and then call . + To get the array, first get the method and then call . ## Examples - The following example shows how to test method parameters for the , , and attributes. + The following example shows how to test method parameters for the , , and attributes. The example contains a `DefineMethod` method that does the following: - Creates a dynamic assembly containing a `MyType` type. -- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . +- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . -- Calls to complete the type. +- Calls to complete the type. After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. @@ -872,20 +872,20 @@ This method utilizes the `Out` flag of the `ParameterAttributes` enumerator. - To get the array, first get the method or the constructor and then call . + To get the array, first get the method or the constructor and then call . ## Examples - The following example shows how to test method parameters for the , , and attributes. + The following example shows how to test method parameters for the , , and attributes. The example contains a `DefineMethod` method that does the following: - Creates a dynamic assembly containing a `MyType` type. -- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . +- Adds a `MyMethod` method to `MyType`. `MyMethod` has three parameters. The first parameter is defined with , the second with , and the third with . -- Calls to complete the type. +- Calls to complete the type. After executing `DefineMethod`, the example searches the assemblies that are currently loaded until it finds the dynamic assembly. It loads `MyType` from the assembly, gets a object for the `MyMethod` method, and examines the parameters. The example uses the , , and properties to display information about the parameters. @@ -936,7 +936,7 @@ This method utilizes the `Retval` flag of the `ParameterAttributes` enumerator. - To get the array, first get the method or the constructor and then call . + To get the array, first get the method or the constructor and then call . ]]> @@ -1082,10 +1082,10 @@ ## Remarks This property utilizes the protected field, and depends on an optional metadata flag that might not be available in all compilers. - To get the array, first get the method or the constructor and then call the method. + To get the array, first get the method or the constructor and then call the method. > [!WARNING] -> If this represents a return value (that is, if it was obtained by using the property), this property will be `null`. +> If this represents a return value (that is, if it was obtained by using the property), this property will be `null`. @@ -1171,7 +1171,7 @@ ## Remarks This method depends on an optional metadata and might not be available in all compilers. - To get the array, first get the method or the constructor and then call . + To get the array, first get the method or the constructor and then call . @@ -1224,7 +1224,7 @@ This method utilizes the method. - To get the array, first get the method or the constructor and then call . + To get the array, first get the method or the constructor and then call . ]]> @@ -1301,7 +1301,7 @@ The default value is used when an actual value is not specified in the method call. A parameter can have a default value that is `null`. This is distinct from the case where a default value is not defined. - To get the array, first get the method or the constructor and then call the method. + To get the array, first get the method or the constructor and then call the method. ]]> diff --git a/xml/System.Reflection/ParameterModifier.xml b/xml/System.Reflection/ParameterModifier.xml index 70a6dda1a73c4..f88795614009b 100644 --- a/xml/System.Reflection/ParameterModifier.xml +++ b/xml/System.Reflection/ParameterModifier.xml @@ -34,7 +34,7 @@ structure is used with the method overload when passing parameters by reference to a COM component that is accessed late bound. The parameters that are to be passed by reference are specified by a single structure, which must be passed in an array containing a single element. The single structure in this array must be initialized with the number of parameters in the member that is to be invoked. To indicate which of these parameters are passed by reference, set the value of the property (the indexer in C#) to `true` for the index number corresponding to the zero-based position of the parameter. + The structure is used with the method overload when passing parameters by reference to a COM component that is accessed late bound. The parameters that are to be passed by reference are specified by a single structure, which must be passed in an array containing a single element. The single structure in this array must be initialized with the number of parameters in the member that is to be invoked. To indicate which of these parameters are passed by reference, set the value of the property (the indexer in C#) to `true` for the index number corresponding to the zero-based position of the parameter. diff --git a/xml/System.Reflection/PortableExecutableKinds.xml b/xml/System.Reflection/PortableExecutableKinds.xml index d69c80257d8e5..9ee09672cac51 100644 --- a/xml/System.Reflection/PortableExecutableKinds.xml +++ b/xml/System.Reflection/PortableExecutableKinds.xml @@ -32,7 +32,7 @@ method. + To obtain this value for a module, use the method. > [!NOTE] > This enumeration corresponds to the `CorPEKind` enumeration in the unmanaged reflection API, which is accessed by the unmanaged `GetPEKind` function. diff --git a/xml/System.Reflection/PropertyInfo.xml b/xml/System.Reflection/PropertyInfo.xml index 8878b2739155f..91cb1ba72f92d 100644 --- a/xml/System.Reflection/PropertyInfo.xml +++ b/xml/System.Reflection/PropertyInfo.xml @@ -59,7 +59,7 @@ If this format is not followed, the behavior of the `GetValue` and `SetValue` methods is undefined. - Calling on `PropertyInfo` when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. + Calling on `PropertyInfo` when the `inherit` parameter of `GetCustomAttributes` is `true` does not walk the type hierarchy. Use to inherit custom attributes. @@ -141,7 +141,7 @@ property returns the attributes associated with the property represented by this object. The attributes are primarily modifiers applied by a compiler when creating a property; they indicate whether a property is the default property, a `SpecialName` property, and so on. Note that, for almost all properties found in types in the .NET Framework class library, the value of the property is . + The property returns the attributes associated with the property represented by this object. The attributes are primarily modifiers applied by a compiler when creating a property; they indicate whether a property is the default property, a `SpecialName` property, and so on. Note that, for almost all properties found in types in the .NET Framework class library, the value of the property is . > [!TIP] > In most cases, you probably want to retrieve the custom attributes associated with a property. To do this, retrieve the value of the property, or call one of the overloads of the method. @@ -150,7 +150,7 @@ 1. Get a object that represents the type to which the property belongs. -2. Get the object by calling an overload of the method. +2. Get the object by calling an overload of the method. 3. Retrieve the property's attributes from the property. @@ -253,7 +253,7 @@ 1. Get the object of the type that includes the property. -2. Call the to get the object that represents the property. +2. Call the to get the object that represents the property. 3. Retrieve the value of the property. @@ -977,7 +977,7 @@ ## Remarks You call the overload to retrieve the value of a non-indexed property; if you try to retrieve the value of an indexed property, the method throws a exception. You can determine whether a property is indexed or not by calling the method. If the length of the returned array is zero, the property is not indexed. - This is a convenience method that provides an implementation for the abstract method with the parameter set to , the set to `null`, the object array of index values set to `null`, and the set to `null`. + This is a convenience method that provides an implementation for the abstract method with the parameter set to , the set to `null`, the object array of index values set to `null`, and the set to `null`. @@ -1052,14 +1052,14 @@ Console.WriteLine("CurrCult: " + To use the `GetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `GetValue` method. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. ## Examples - The following example shows how to get the value of an indexed property. The property is the default property (the indexer in C#) of the class. + The following example shows how to get the value of an indexed property. The property is the default property (the indexer in C#) of the class. [!code-csharp[System.Reflection.PropertyInfo.GetValue Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.reflection.PropertyInfo.GetValue Example/CS/source.cs#1)] [!code-vb[System.Reflection.PropertyInfo.GetValue Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.reflection.PropertyInfo.GetValue Example/VB/source.vb#1)] @@ -1148,7 +1148,7 @@ Console.WriteLine("CurrCult: " + To use the `GetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `GetValue` method. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1366,7 +1366,7 @@ Console.WriteLine("CurrCult: " + 1. Get a object that represents the type (the class or structure) that contains the property. If you are working with an object (an instance of a type), you can call its method. Otherwise, you can use the C# operator or the Visual Basic operator, as the example illustrates. -2. Get a object that represents the property in which you're interested. You can do this by getting an array of all properties from the method and then iterating the elements in the array, or you can retrieve the object that represents the property directly by calling the method and specifying the property name. +2. Get a object that represents the property in which you're interested. You can do this by getting an array of all properties from the method and then iterating the elements in the array, or you can retrieve the object that represents the property directly by calling the method and specifying the property name. 3. Retrieve the value of the property from the object. @@ -1470,12 +1470,12 @@ Console.WriteLine("CurrCult: " + If the property type of this object is a value type and `value` is `null`, the property will be set to the default value for that type. - This is a convenience method that calls the runtime implementation of the abstract method, specifying for the `BindingFlags` parameter, `null` for `Binder`, `null` for `Object[]`, and `null` for `CultureInfo`. + This is a convenience method that calls the runtime implementation of the abstract method, specifying for the `BindingFlags` parameter, `null` for `Binder`, `null` for `Object[]`, and `null` for `CultureInfo`. To use the method, first get a object that represents the class. From the , get the object. From the object, call the method. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1567,12 +1567,12 @@ Console.WriteLine("CurrCult: " + To determine whether a property is indexed, use the method. If the resulting array has 0 (zero) elements, the property is not indexed. - This is a convenience method that calls the runtime implementation of the abstract method, specifying for the `BindingFlags` parameter, `null` for `Binder`, and `null` for `CultureInfo`. + This is a convenience method that calls the runtime implementation of the abstract method, specifying for the `BindingFlags` parameter, `null` for `Binder`, and `null` for `CultureInfo`. To use the method, first get a object that represents the class. From the , get the . From the , use the method. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. @@ -1685,7 +1685,7 @@ Console.WriteLine("CurrCult: " + To use the `SetValue` method, first get the class `Type`. From the `Type`, get the `PropertyInfo`. From the `PropertyInfo`, use the `SetValue` method. > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], this method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller’s grant set, or a subset thereof. (See [Security Considerations for Reflection](~/docs/framework/reflection-and-codedom/security-considerations-for-reflection.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. diff --git a/xml/System.Reflection/TypeAttributes.xml b/xml/System.Reflection/TypeAttributes.xml index cec7baeb4b04e..6d64eaf8ebaad 100644 --- a/xml/System.Reflection/TypeAttributes.xml +++ b/xml/System.Reflection/TypeAttributes.xml @@ -36,7 +36,7 @@ enumeration are masks that represent a set of mutually exclusive attributes. For example, the VisibilityMask member includes the NotPublic, Public, NestedPublic, NestedPrivate, NestedFamily, NestedAssembly, NestedFamANDAssem, and NestedFamORAssem members, Because each attribute set includes a member whose underlying value is zero, you should first `And` the value of the mask with the specific value retrieved from a property such as . The following table lists the masks and the individual members that they include: + Some of the members of the enumeration are masks that represent a set of mutually exclusive attributes. For example, the VisibilityMask member includes the NotPublic, Public, NestedPublic, NestedPrivate, NestedFamily, NestedAssembly, NestedFamANDAssem, and NestedFamORAssem members, Because each attribute set includes a member whose underlying value is zero, you should first `And` the value of the mask with the specific value retrieved from a property such as . The following table lists the masks and the individual members that they include: |Mask|Includes| |----------|--------------| diff --git a/xml/System.Reflection/TypeDelegator.xml b/xml/System.Reflection/TypeDelegator.xml index 38979407a5b10..426e9ac358390 100644 --- a/xml/System.Reflection/TypeDelegator.xml +++ b/xml/System.Reflection/TypeDelegator.xml @@ -32,14 +32,14 @@ ## Remarks Derive from this type and override only those members you have to provide customization in, plus any members that are required by your program and not already implemented by . - derives from and implements most of the properties and methods of . For each member it implements, automatically delegates to the corresponding member of an internal object, which is supplied as an argument to the constructor. This internal object is exposed to deriving classes by the `protected` field. + derives from and implements most of the properties and methods of . For each member it implements, automatically delegates to the corresponding member of an internal object, which is supplied as an argument to the constructor. This internal object is exposed to deriving classes by the `protected` field. > [!NOTE] > Some members of have implementations even though the members themselves are simply inherited from . In these cases, the implementation is provided by an overridden `protected` method that has a name that ends in "Impl". For example, the implementation for all overloads of the method is supplied by the overridden method. The implementation for inherited properties such as and is provided by the overridden method. Deriving classes can provide a public constructor that takes a object as its parameter and simply passes that object to the constructor, or can set the internal object in some other way. - If a deriving class uses a member that is not implemented by , it must override that member and provide an implementation. The simplest implementation is to call the corresponding member on the internal object exposed by the field, but you can provide any implementation your application requires. It is not necessary to override these members if they are not used by your application or by library functions your application calls (for example, by the constructor). + If a deriving class uses a member that is not implemented by , it must override that member and provide an implementation. The simplest implementation is to call the corresponding member on the internal object exposed by the field, but you can provide any implementation your application requires. It is not necessary to override these members if they are not used by your application or by library functions your application calls (for example, by the constructor). The following virtual methods (`Overridable` methods in Visual Basic) of are not implemented by : , , , , , , , , , , , , . @@ -1159,7 +1159,7 @@ The binder will find all the matching methods. These methods are found based upon the type of binding requested (`BindingFlags.MethodInvoke`, `BindingFlags.GetProperties`, and so on). The set of methods is filtered by the name, number of arguments, and a set of search modifiers defined in the binder. - After the method is selected, it will be invoked. Accessibility is checked at that point. The search may control which set of methods are searched based upon the accessibility attribute associated with the method. The method is responsible for selecting the method to be invoked. The default binder selects the most specific match. + After the method is selected, it will be invoked. Accessibility is checked at that point. The search may control which set of methods are searched based upon the accessibility attribute associated with the method. The method is responsible for selecting the method to be invoked. The default binder selects the most specific match. > [!NOTE] > Access restrictions are ignored for fully trusted code. That is, private constructors, methods, fields, and properties can be accessed and invoked using reflection whenever the code is fully trusted. diff --git a/xml/System.Reflection/TypeFilter.xml b/xml/System.Reflection/TypeFilter.xml index 776d3c18f1055..80ef4111aed52 100644 --- a/xml/System.Reflection/TypeFilter.xml +++ b/xml/System.Reflection/TypeFilter.xml @@ -44,7 +44,7 @@ objects. The method uses this delegate to filter the list of interfaces that it returns. Every derived class of and has a constructor and a `DynamicInvoke` method. See the Visual C++ code example given in the description for `Delegate`. + The `TypeFilter` delegate is used to filter a list of classes. Specifically, you use it to filter the classes represented in an array of objects. The method uses this delegate to filter the list of interfaces that it returns. Every derived class of and has a constructor and a `DynamicInvoke` method. See the Visual C++ code example given in the description for `Delegate`. diff --git a/xml/System.Reflection/TypeInfo.xml b/xml/System.Reflection/TypeInfo.xml index 0a891da27902d..7d401cf7cf188 100644 --- a/xml/System.Reflection/TypeInfo.xml +++ b/xml/System.Reflection/TypeInfo.xml @@ -43,7 +43,7 @@ ## Remarks Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the class is included in the [!INCLUDE[net_win8_profile](~/includes/net-win8-profile-md.md)] subset for use in creating Windows Store apps. is available in the full .NET Framework as well. For more information about reflection for Windows Store apps, see [System.Reflection namespaces](http://msdn.microsoft.com/library/windows/apps/hh441595\(v=vs.110\).aspx) in the Windows Dev Center and [Reflection in the .NET Framework for Windows Store Apps](~/docs/framework/reflection-and-codedom/reflection-for-windows-store-apps.md) in the MSDN Library. - contains many of the members available in the class, and many of the reflection properties in the [!INCLUDE[net_win8_profile](~/includes/net-win8-profile-md.md)] return collections of objects. To get a object from a object, use the extension method. + contains many of the members available in the class, and many of the reflection properties in the [!INCLUDE[net_win8_profile](~/includes/net-win8-profile-md.md)] return collections of objects. To get a object from a object, use the extension method. A object represents the type definition itself, whereas a object represents a reference to the type definition. Getting a object forces the assembly that contains that type to load. In comparison, you can manipulate objects without necessarily requiring the runtime to load the assembly they reference. diff --git a/xml/System.Resources.Tools/StronglyTypedResourceBuilder.xml b/xml/System.Resources.Tools/StronglyTypedResourceBuilder.xml index a067cdaaf3e33..b77fee3f269fc 100644 --- a/xml/System.Resources.Tools/StronglyTypedResourceBuilder.xml +++ b/xml/System.Resources.Tools/StronglyTypedResourceBuilder.xml @@ -18,7 +18,7 @@ ## Remarks Typically, resources separate code from content within an application. Creating and consuming these resources makes it easier to develop localizable applications. In the .NET Framework, resources are usually consumed by using the class, which contains methods that provide access to culture-specific resources at run time. For more information about creating and consuming resources, see [Resources in Desktop Apps](http://msdn.microsoft.com/library/8ad495d4-2941-40cf-bf64-e82e85825890). - Strongly typed resource support is a compile-time feature that encapsulates access to resources by creating classes that contain a set of static, read-only (`get`) properties. This provides an alternative way to consume resources instead of calling the and methods. + Strongly typed resource support is a compile-time feature that encapsulates access to resources by creating classes that contain a set of static, read-only (`get`) properties. This provides an alternative way to consume resources instead of calling the and methods. The basic functionality for strongly typed resource support is provided by the class (as well as the `/str` command-line option in the [Resgen.exe (Resource File Generator)](~/docs/framework/tools/resgen-exe-resource-file-generator.md)). The output of the method is a class that contains strongly typed properties that match the resources that are referenced in the input parameter. This class provides read-only access to the resources that are available in the file processed. diff --git a/xml/System.Resources/IResourceReader.xml b/xml/System.Resources/IResourceReader.xml index 7d5e0fcf653dd..19468533fb5a9 100644 --- a/xml/System.Resources/IResourceReader.xml +++ b/xml/System.Resources/IResourceReader.xml @@ -103,7 +103,7 @@ inherits the interface, it must also provide an implementation of the method, which returns an object that can be used to enumerate a collection. Typically, is implemented as an explicit interface implementation. + Because inherits the interface, it must also provide an implementation of the method, which returns an object that can be used to enumerate a collection. Typically, is implemented as an explicit interface implementation. ]]> diff --git a/xml/System.Resources/MissingManifestResourceException.xml b/xml/System.Resources/MissingManifestResourceException.xml index 62c1befce45b5..106f30b9a1aee 100644 --- a/xml/System.Resources/MissingManifestResourceException.xml +++ b/xml/System.Resources/MissingManifestResourceException.xml @@ -41,14 +41,14 @@ The main causes of the exception include the following: -- The resource set is not identified by its fully qualified name. For example, if the `baseName` parameter in the call to the method specifies the root name of the resource set without a namespace, but the resource set is assigned a namespace when it is stored in its assembly, the call to the method throws this exception. +- The resource set is not identified by its fully qualified name. For example, if the `baseName` parameter in the call to the method specifies the root name of the resource set without a namespace, but the resource set is assigned a namespace when it is stored in its assembly, the call to the method throws this exception. If you have embedded the .resources file that contains the default culture's resources in your executable and your app is throwing a , you can use a reflection tool such as to determine the fully qualified name of the resource. In ILDasm, double click the executable's **MANIFEST** label to open the **MANIFEST** window. Resources appear as `.mresource` items and are listed after external assembly references and custom assembly-level attributes. You can also compile the following simple utility, which lists the fully qualified names of embedded resources in the assembly whose name is passed to it as a command-line parameter. [!code-csharp[System.Resources.ResourceManager.Class#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resourcemanager.class/cs/resourcenames.cs#4)] [!code-vb[System.Resources.ResourceManager.Class#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/resourcenames.vb#4)] -- You identify the resource set by its resource file name (along with its optional namespace) and its file extension rather than by its namespace and root file name alone. For example, this exception is thrown if the neutral culture's resource set is named `GlobalResources` and you supply a value of `GlobalResources.resources` (instead of `GlobalResources`) to the `baseName` parameter of the constructor. +- You identify the resource set by its resource file name (along with its optional namespace) and its file extension rather than by its namespace and root file name alone. For example, this exception is thrown if the neutral culture's resource set is named `GlobalResources` and you supply a value of `GlobalResources.resources` (instead of `GlobalResources`) to the `baseName` parameter of the constructor. - The culture-specific resource set that is identified in a method call cannot be found, and the fallback resource set cannot be loaded. For example, if you create satellite assemblies for the English (United States) and Russia (Russian) cultures but you fail to provide a resource set for the neutral culture, this exception is thrown if your app's current culture is English (Great Britain). diff --git a/xml/System.Resources/MissingSatelliteAssemblyException.xml b/xml/System.Resources/MissingSatelliteAssemblyException.xml index 90ff2dfe09c18..a89e95d5d0a7b 100644 --- a/xml/System.Resources/MissingSatelliteAssemblyException.xml +++ b/xml/System.Resources/MissingSatelliteAssemblyException.xml @@ -30,7 +30,7 @@ is thrown if the resource manager tries to retrieve but cannot find a resource for the default culture. However, the .NET Framework will load the resources for an app's default culture from a satellite assembly if the attribute specifies a value of for the location parameter. When this is the case, the exception is thrown when the resource manager tries to retrieve a resource of the default culture and the satellite assembly for the culture specified in the attribute is missing. Note that the exception is thrown by a resource retrieval method such as or , and not when the object is instantiated. + The default culture is the culture whose resources are loaded if the appropriate culture-specific resources cannot be found. By default, resources for the default culture are located in the main assembly, and a is thrown if the resource manager tries to retrieve but cannot find a resource for the default culture. However, the .NET Framework will load the resources for an app's default culture from a satellite assembly if the attribute specifies a value of for the location parameter. When this is the case, the exception is thrown when the resource manager tries to retrieve a resource of the default culture and the satellite assembly for the culture specified in the attribute is missing. Note that the exception is thrown by a resource retrieval method such as or , and not when the object is instantiated. uses the HRESULT COR_E_MISSINGSATELLITEASSEMBLY, which has the value 0x80131536. diff --git a/xml/System.Resources/ResXDataNode.xml b/xml/System.Resources/ResXDataNode.xml index d8ff69ca6ad56..d70bf1b23b718 100644 --- a/xml/System.Resources/ResXDataNode.xml +++ b/xml/System.Resources/ResXDataNode.xml @@ -22,19 +22,19 @@ ## Remarks The class supports the representation of rich data types within a resource file. It can support the storage of any object in a resource file, so long as the object supports serialization and type editors. - You can create a object by calling one of its overloaded class constructors. You can then add the resource item or element to a resource file by calling the method. + You can create a object by calling one of its overloaded class constructors. You can then add the resource item or element to a resource file by calling the method. - To retrieve an existing object, you must enumerate the objects in an XML resource file by instantiating a object, setting the property to `true`, and calling the method to get an enumerator. The example provides an illustration. + To retrieve an existing object, you must enumerate the objects in an XML resource file by instantiating a object, setting the property to `true`, and calling the method to get an enumerator. The example provides an illustration. ## Examples - The following example uses the method to obtain an object that is used to enumerate the objects in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary XML resource file. + The following example uses the method to obtain an object that is used to enumerate the objects in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary XML resource file. [!code-csharp[System.Resources.ResXDataNode.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resxdatanode.class/cs/resxresourcereader2.cs#1)] [!code-vb[System.Resources.ResXDataNode.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxdatanode.class/vb/resxresourcereader2.vb#1)] - Because the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. + Because the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. ]]> @@ -166,9 +166,9 @@ property is . + If a comment has not been assigned to the resource item, the value of the property is . - You access the property of an data node in an existing XML resource file by instantiating a object, setting the property to `true`, and calling the method to retrieve an object that you use to enumerate the items in the XML resource file. The property returns the object. + You access the property of an data node in an existing XML resource file by instantiating a object, setting the property to `true`, and calling the method to retrieve an object that you use to enumerate the items in the XML resource file. The property returns the object. diff --git a/xml/System.Resources/ResXFileRef.xml b/xml/System.Resources/ResXFileRef.xml index 5e1084d868dc0..96837d6be644f 100644 --- a/xml/System.Resources/ResXFileRef.xml +++ b/xml/System.Resources/ResXFileRef.xml @@ -21,7 +21,7 @@ class is used to include references to files in an XML resource (.resx) file. A object represents a link to an external resource in an XML resource (.resx) file. You add the object to a .resx file by calling the method. + The class is used to include references to files in an XML resource (.resx) file. A object represents a link to an external resource in an XML resource (.resx) file. You add the object to a .resx file by calling the method. In a data entry in a .resx file, the type is , and the value is the path location on disk. When the resource manager deserializes the object, the performs the I/O to get the file. The following is an example of a .resx file. @@ -37,7 +37,7 @@ ``` - To add a object to a .resx file programmatically, you call the constructor to instantiate a object. You then pass this object to the method. + To add a object to a .resx file programmatically, you call the constructor to instantiate a object. You then pass this object to the method. When you compile a .resx file with [Resgen.exe (Resource File Generator)](~/docs/framework/tools/resgen-exe-resource-file-generator.md), the resources specified in the .resx file are embedded in the resulting document resource file. diff --git a/xml/System.Resources/ResXResourceReader.xml b/xml/System.Resources/ResXResourceReader.xml index 7779f926584ed..288dbf173d0a9 100644 --- a/xml/System.Resources/ResXResourceReader.xml +++ b/xml/System.Resources/ResXResourceReader.xml @@ -25,23 +25,23 @@ You use the class to enumerate resources in .resx files by traversing the dictionary enumerator () that is returned by the method. You call the methods provided by to advance to the next resource and to read the name and value of each resource in the .resx file. > [!NOTE] -> The class provides two enumerators. The method returns an object; we recommend that you use this method to enumerate resources. The method is an explicit interface implementation that returns an object; we do not recommend its use. +> The class provides two enumerators. The method returns an object; we recommend that you use this method to enumerate resources. The method is an explicit interface implementation that returns an object; we do not recommend its use. The following example uses the method to obtain an object that is used to enumerate the resources in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary resource file. [!code-csharp[System.Resources.ResXResourceReader.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/cs/resxresourcereader1.cs#1)] [!code-vb[System.Resources.ResXResourceReader.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/vb/resxresourcereader1.vb#1)] - If the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. The following example sets the property to `true` and enumerates the resources in a .resx file, + If the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. The following example sets the property to `true` and enumerates the resources in a .resx file, [!code-csharp[System.Resources.ResXResourceReader.Class#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/cs/resxresourcereader2.cs#2)] [!code-vb[System.Resources.ResXResourceReader.Class#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourcereader.class/vb/resxresourcereader2.vb#2)] If is `true`, the items in the enumeration can be either: -- Named resources along with their data. In this case, the property is `null`. +- Named resources along with their data. In this case, the property is `null`. -- Named resources along with the name of the file that contains the resource data. In this case, the property returns a object that provides information about the resource, including its filename. If relative file names are used, you should always set the property to provide a reference point for the relative file path. +- Named resources along with the name of the file that contains the resource data. In this case, the property returns a object that provides information about the resource, including its filename. If relative file names are used, you should always set the property to provide a reference point for the relative file path. If you want to retrieve named resources from a .resx file rather than enumerating its resources, you can instantiate a object and call its `GetString` and `GetObject` methods. @@ -294,7 +294,7 @@ property is used to resolve relative file path references that are assigned to the property of objects. By default, its value is , and relative file path references are resolved in relationship to the current directory returned by the property. You should set this property before you begin enumerating resources. + The property is used to resolve relative file path references that are assigned to the property of objects. By default, its value is , and relative file path references are resolved in relationship to the current directory returned by the property. You should set this property before you begin enumerating resources. @@ -368,7 +368,7 @@ method or the method. invokes this method with the `disposing` parameter set to `true`. invokes this method with `disposing` set to `false`. + This method can be called by either the method or the method. invokes this method with the `disposing` parameter set to `true`. invokes this method with `disposing` set to `false`. When the `disposing` parameter is `true`, this method releases all resources held by any managed objects that this references. This method invokes the `Dispose` method of each referenced object. @@ -565,7 +565,7 @@ instance is cast to an interface. To enumerate the resources in a .resx file, we recommend that you call the method, and then call the `MoveNext` method on the returned object. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. To enumerate the resources in a .resx file, we recommend that you call the method, and then call the `MoveNext` method on the returned object. ]]> diff --git a/xml/System.Resources/ResXResourceSet.xml b/xml/System.Resources/ResXResourceSet.xml index 84de471c74ef6..dc89d946e5abf 100644 --- a/xml/System.Resources/ResXResourceSet.xml +++ b/xml/System.Resources/ResXResourceSet.xml @@ -19,14 +19,14 @@ The class enumerates over an , loads every name and value, and stores them in a hash table. You can then enumerate the resources in the object or retrieve individual resources by name. > [!NOTE] -> This class contains a and an at the class level that applies to all members. A exception is thrown when the immediate caller or a derived class does not have full-trust permission. +> This class contains a and an at the class level that applies to all members. A exception is thrown when the immediate caller or a derived class does not have full-trust permission. A object provides a convenient way to read all the resources in a .resx file into memory. You can use the method to retrieve a particular resource when the .resx file has been read into a instance. ## Examples - The following example instantiates a object and illustrates how to enumerate its resources and retrieve individual resources by name. For each resource that it enumerates, the example uses the property in a call to the `GetString` or `GetObject` method, depending on whether the value of the resource is a string or an object. + The following example instantiates a object and illustrates how to enumerate its resources and retrieve individual resources by name. For each resource that it enumerates, the example uses the property in a call to the `GetString` or `GetObject` method, depending on whether the value of the resource is a string or an object. [!code-csharp[System.Resources.ResXResourceSet.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resxresourceset.class/cs/example1.cs#1)] [!code-vb[System.Resources.ResXResourceSet.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resxresourceset.class/vb/example1.vb#1)] diff --git a/xml/System.Resources/ResourceManager.xml b/xml/System.Resources/ResourceManager.xml index 9d4837630f03f..ab47ec99d1b53 100644 --- a/xml/System.Resources/ResourceManager.xml +++ b/xml/System.Resources/ResourceManager.xml @@ -68,7 +68,7 @@ ### Creating Resources When you develop a resource-based app, you store resource information in text files (files that have a .txt or .restext extension) or XML files (files that have a .resx extension). You then compile the text or XML files with the [Resource File Generator (Resgen.exe)](~/docs/framework/tools/resgen-exe-resource-file-generator.md) to create a binary .resources file. You can then embed the resulting .resources file in an executable or library by using a compiler option such as `/resources` for the C# and Visual Basic compilers, or you can embed it in a satellite assembly by using the . If you include a .resx file in your Visual Studio project, Visual Studio handles the compilation and embedding of default and localized resources automatically as part of the build process. - Ideally, you should create resources for every language your app supports, or at least for a meaningful subset of each language. The binary .resources file names follow the naming convention *basename*.*cultureName*.resources, where *basename* is the name of the app or the name of a class, depending on the level of detail you want. The property is used to determine *cultureName*. A resource for the app's default culture should be named *basename*.resources. + Ideally, you should create resources for every language your app supports, or at least for a meaningful subset of each language. The binary .resources file names follow the naming convention *basename*.*cultureName*.resources, where *basename* is the name of the app or the name of a class, depending on the level of detail you want. The property is used to determine *cultureName*. A resource for the app's default culture should be named *basename*.resources. For example, suppose that an assembly has several resources in a resource file that has the base name MyResources. These resource files should have names such as MyResources.ja-JP.resources for the Japan (Japanese) culture, MyResources.de.resources for the German culture, MyResources.zh-CHS.resources for the simplified Chinese culture, and MyResources.fr-BE.resources for the French (Belgium) culture. The default resource file should be named MyResources.resources. The culture-specific resource files are commonly packaged in satellite assemblies for each culture. The default resource file should be embedded in the app's main assembly. @@ -123,19 +123,19 @@ vbc ShowTime.vb /resource:strings.resources ### ResourceManager and Culture-Specific Resources - A localized app requires resources to be deployed, as discussed in the article [Packaging and Deploying Resources](~/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md). If the assemblies are properly configured, the resource manager determines which resources to retrieve based on the current thread's property. (That property also returns the current thread's UI culture.) For example, if an app is compiled with default English language resources in the main assembly and with French and Russian language resources in two satellite assemblies, and the property is set to fr-FR, the resource manager retrieves the French resources. + A localized app requires resources to be deployed, as discussed in the article [Packaging and Deploying Resources](~/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md). If the assemblies are properly configured, the resource manager determines which resources to retrieve based on the current thread's property. (That property also returns the current thread's UI culture.) For example, if an app is compiled with default English language resources in the main assembly and with French and Russian language resources in two satellite assemblies, and the property is set to fr-FR, the resource manager retrieves the French resources. You can set the property explicitly or implicitly. The way you set it determines how the object retrieves resources based on culture: -- If you explicitly set the property to a specific culture, the resource manager always retrieves the resources for that culture, regardless of the user's browser or operating system language. Consider an app that is compiled with default English language resources and three satellite assemblies that contain resources for English (United States), French (France), and Russian (Russia). If the property is set to fr-FR, the object always retrieves the French (France) resources, even if the user's operating system language is not French. Make sure that this is the desired behavior before you set the property explicitly. +- If you explicitly set the property to a specific culture, the resource manager always retrieves the resources for that culture, regardless of the user's browser or operating system language. Consider an app that is compiled with default English language resources and three satellite assemblies that contain resources for English (United States), French (France), and Russian (Russia). If the property is set to fr-FR, the object always retrieves the French (France) resources, even if the user's operating system language is not French. Make sure that this is the desired behavior before you set the property explicitly. - In ASP.NET apps, you must set the property explicitly, because it is unlikely that the setting on the server will match incoming client requests. An ASP.NET app can set the property explicitly to the user's browser accept language. + In ASP.NET apps, you must set the property explicitly, because it is unlikely that the setting on the server will match incoming client requests. An ASP.NET app can set the property explicitly to the user's browser accept language. - Explicitly setting the property defines the current UI culture for that thread. It does not affect the current UI culture of any other threads in an app. + Explicitly setting the property defines the current UI culture for that thread. It does not affect the current UI culture of any other threads in an app. -- You can set the UI culture of all threads in an app domain by assigning a object that represents that culture to the static property. +- You can set the UI culture of all threads in an app domain by assigning a object that represents that culture to the static property. -- If you do not explicitly set the current UI culture and you do not define a default culture for the current app domain, the property is set implicitly by the Windows `GetUserDefaultUILanguage` function. This function is provided by the Multilingual User Interface (MUI), which enables the user to set the default language. If the UI language is not set by the user, it defaults to the system-installed language, which is the language of operating system resources. +- If you do not explicitly set the current UI culture and you do not define a default culture for the current app domain, the property is set implicitly by the Windows `GetUserDefaultUILanguage` function. This function is provided by the Multilingual User Interface (MUI), which enables the user to set the default language. If the UI language is not set by the user, it defaults to the system-installed language, which is the language of operating system resources. The following simple "Hello world" example sets the current UI culture explicitly. It contains resources for three cultures: English (United States) or en-US, French (France) or fr-FR, and Russian (Russia) or ru-RU. The en-US resources are contained in a text file named Greetings.txt: @@ -235,7 +235,7 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res [!code-csharp[System.Resources.ResourceManager.Class#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resourcemanager.class/cs/resourcenames.cs#4)] [!code-vb[System.Resources.ResourceManager.Class#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcemanager.class/vb/resourcenames.vb#4)] - If you are changing the current culture of your application explicitly, you should also remember that the resource manager retrieves a resource set based on the value of the property, and not the property. Typically, if you change one value, you should also change the other. + If you are changing the current culture of your application explicitly, you should also remember that the resource manager retrieves a resource set based on the value of the property, and not the property. Typically, if you change one value, you should also change the other. ### Resource Versioning @@ -576,7 +576,7 @@ vbc Example.vb /resource:ExampleResources.resources csc Example.cs /resource:ExampleResources.resources ``` - Note that the example retrieves a reference to the assembly that contains the resource file by passing a type defined in that assembly to the `typeof` function (in C#) or the `GetType` function (in Visual Basic) and retrieving the value of its property. + Note that the example retrieves a reference to the assembly that contains the resource file by passing a type defined in that assembly to the `typeof` function (in C#) or the `GetType` function (in Visual Basic) and retrieving the value of its property. ]]> @@ -864,9 +864,9 @@ csc Example.cs /resource:ExampleResources.resources method is used to retrieve non-string resources. These include values that belong to primitive data types such as or , bitmaps (such as a object), or custom serialized objects. Typically, the returned object must be cast (in C#) or converted (in Visual Basic) to an object of the appropriate type. + The method is used to retrieve non-string resources. These include values that belong to primitive data types such as or , bitmaps (such as a object), or custom serialized objects. Typically, the returned object must be cast (in C#) or converted (in Visual Basic) to an object of the appropriate type. - The returned resource is localized for the UI culture of the current thread, which is defined by the property. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. + The returned resource is localized for the UI culture of the current thread, which is defined by the property. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. @@ -953,9 +953,9 @@ GetObject.exe method is used to retrieve non-string resources. These include values that belong to primitive data types such as or , bitmaps (such as a object), or custom serialized objects. Typically, the returned object must be cast (in C#) or converted (in Visual Basic) to an object of the appropriate type. + The method is used to retrieve non-string resources. These include values that belong to primitive data types such as or , bitmaps (such as a object), or custom serialized objects. Typically, the returned object must be cast (in C#) or converted (in Visual Basic) to an object of the appropriate type. - The returned resource is localized for the culture that is specified by `culture`, or for the culture that is specified by the property if `culture` is `null`. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the resource manager falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. + The returned resource is localized for the culture that is specified by `culture`, or for the culture that is specified by the property if `culture` is `null`. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the resource manager falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. @@ -1053,7 +1053,7 @@ ShowNumbers.exe ## Remarks The method is useful only if you write your own class that derives from the class. - This method uses the property as part of the file name for all cultures other than the invariant culture. This method does not look in an assembly's manifest or touch the disk, and is used only to construct a resource file name (suitable for passing to the constructor) or a manifest resource blob name. + This method uses the property as part of the file name for all cultures other than the invariant culture. This method does not look in an assembly's manifest or touch the disk, and is used only to construct a resource file name (suitable for passing to the constructor) or a manifest resource blob name. A derived class can override this method to look for a different extension, such as ".ResX", or a completely different scheme for naming resource files. Note that the method can be used to customize the name of a resource file within a satellite assembly, and not to customize the name of the satellite assembly itself. @@ -1257,7 +1257,7 @@ al /out:fr-FR\ShowNumbers.resources.dll /culture:fr-FR /embed:NumberResources.fr ## Remarks The method takes the name of a resource that is stored as a object, gets the value of the resource, and returns an object. It requires that you work directly with a stream of bytes, which you then convert to an object. This method is useful primarily for performance reasons: Retrieving a resource as a byte stream instead of an explicit object can improve performance. - The returned resource is localized for the UI culture of the current thread, which is defined by the property. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. + The returned resource is localized for the UI culture of the current thread, which is defined by the property. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. @@ -1269,7 +1269,7 @@ al /out:fr-FR\ShowNumbers.resources.dll /culture:fr-FR /embed:NumberResources.fr [!code-csharp[Conceptual.Resources.Retrieving#4](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.resources.retrieving/cs/createresources.cs#4)] [!code-vb[Conceptual.Resources.Retrieving#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/createresources.vb#4)] - The following code from a file named GetStream.cs (for C#) or GetStream.vb (for Visual Basic) then retrieves the resource and displays the image in a control. + The following code from a file named GetStream.cs (for C#) or GetStream.vb (for Visual Basic) then retrieves the resource and displays the image in a control. [!code-csharp[Conceptual.Resources.Retrieving#5](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.resources.retrieving/cs/getstream.cs#5)] [!code-vb[Conceptual.Resources.Retrieving#5](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.resources.retrieving/vb/getstream.vb#5)] @@ -1338,7 +1338,7 @@ csc GetStream.cs /resource:AppResources.resources ## Remarks The method takes the name of a resource that is stored as a object, gets the value of the resource, and returns an object. It requires that you work directly with a stream of bytes, which you then convert to an object. This method is useful primarily for performance reasons: Retrieving a resource as a byte stream instead of an explicit object can improve performance. - The returned resource is localized for the culture that is specified by `culture`, or for the culture that is specified by the property if `culture` is `null`. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. + The returned resource is localized for the culture that is specified by `culture`, or for the culture that is specified by the property if `culture` is `null`. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. @@ -1387,7 +1387,7 @@ csc GetStream.cs /resource:AppResources.resources ## Remarks ## Desktop Apps - In desktop apps, the resource that is returned is localized for the UI culture of the current thread, as defined by the property. If the resource has not been localized for that culture, the resource manager probes for a resource by following the steps outlined in the "Resource Fallback Process" section of the [Packaging and Deploying Resources](~/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md) article. If no usable set of localized resources is found, the resource manager falls back on the default culture's resources. If the resource manager cannot load the default culture's resource set, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. + In desktop apps, the resource that is returned is localized for the UI culture of the current thread, as defined by the property. If the resource has not been localized for that culture, the resource manager probes for a resource by following the steps outlined in the "Resource Fallback Process" section of the [Packaging and Deploying Resources](~/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md) article. If no usable set of localized resources is found, the resource manager falls back on the default culture's resources. If the resource manager cannot load the default culture's resource set, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. @@ -1479,7 +1479,7 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res ## Remarks ## Desktop Apps - In desktop apps, if `culture` is `null`, the method uses the current UI culture obtained from the property. + In desktop apps, if `culture` is `null`, the method uses the current UI culture obtained from the property. The resource that is returned is localized for the culture specified by the `culture` parameter. If the resource has not been localized for `culture`, the resource manager probes for a resource by following the steps outlined in the "Resource Fallback Process" section of the [Packaging and Deploying Resources](~/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md) topic. If no usable set of resources is found, the resource manager falls back on the default culture's resources. If the resource manager cannot load the default culture's resource set, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. @@ -1498,7 +1498,7 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res ## Examples - The following example uses the method to retrieve culture-specific resources. The example's default culture is English (en), and it includes satellite assemblies for the French (France) (fr-FR) and Russian (Russia) (ru-RU) cultures. The example changes the current culture and current UI culture to Russian (Russia) before calling . It then calls the method and the method and passes objects that represent the French (France) and Swedish (Sweden) cultures to each method. In the output, the month and day of the month as well as the string that precedes them appear in French, because the method is able to retrieve the French language resource. However, when the Swedish (Sweden) culture is used, the month and day of the month appear in Swedish, although the string that precedes them is in English. This is because the resource manager cannot find localized Swedish language resources, so it returns a resource for the default English culture instead. + The following example uses the method to retrieve culture-specific resources. The example's default culture is English (en), and it includes satellite assemblies for the French (France) (fr-FR) and Russian (Russia) (ru-RU) cultures. The example changes the current culture and current UI culture to Russian (Russia) before calling . It then calls the method and the method and passes objects that represent the French (France) and Swedish (Sweden) cultures to each method. In the output, the month and day of the month as well as the string that precedes them appear in French, because the method is able to retrieve the French language resource. However, when the Swedish (Sweden) culture is used, the month and day of the month appear in Swedish, although the string that precedes them is in English. This is because the resource manager cannot find localized Swedish language resources, so it returns a resource for the default English culture instead. The example requires the text-based resource files listed in following table. Each has a single string resource named `DateStart`. @@ -1593,7 +1593,7 @@ al /out:ru-RU\Showdate.resources.dll /culture:ru-RU /embed:DateStrings.ru-RU.res property is `false`, a resource with the name "Resource" is not equivalent to the resource with the name "resource". If is `true`, a resource with the name "Resource" is equivalent to the resource with the name "resource". Note, however, that when is `true`, the and methods perform case-insensitive string comparisons by using the invariant culture. The advantage is that results of case-insensitive string comparisons performed by these methods are the same on all computers regardless of culture. The disadvantage is that the results are not consistent with the casing rules of all cultures. + If the value of the property is `false`, a resource with the name "Resource" is not equivalent to the resource with the name "resource". If is `true`, a resource with the name "Resource" is equivalent to the resource with the name "resource". Note, however, that when is `true`, the and methods perform case-insensitive string comparisons by using the invariant culture. The advantage is that results of case-insensitive string comparisons performed by these methods are the same on all computers regardless of culture. The disadvantage is that the results are not consistent with the casing rules of all cultures. For example, the Turkish alphabet has two versions of the character I: one with a dot and one without a dot. In Turkish, the character I (Unicode 0049) is considered the uppercase version of a different character ı (Unicode 0131). The character i (Unicode 0069) is considered the lowercase version of yet another character İ (Unicode 0130). According to these casing rules, a case-insensitive string comparison of the characters i (Unicode 0069) and I (Unicode 0049) should fail for the culture "tr-TR" (Turkish in Turkey). However, because the comparison is conducted by using the casing rules of the invariant culture if is `true`, this comparison succeeds. diff --git a/xml/System.Resources/ResourceReader.xml b/xml/System.Resources/ResourceReader.xml index 16e7f7183df76..6a3133accd85e 100644 --- a/xml/System.Resources/ResourceReader.xml +++ b/xml/System.Resources/ResourceReader.xml @@ -65,29 +65,29 @@ [!code-csharp[System.Resources.ResourceReader.Class#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resourcereader.class/cs/ctor1.cs#2)] [!code-vb[System.Resources.ResourceReader.Class#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.class/vb/ctor1.vb#2)] - To create a object that represents an embedded .resources file, instantiate an object from the assembly in which the .resources file is embedded. Its method returns a object that can be passed to the constructor. The following example instantiates a object that represents an embedded .resources file. + To create a object that represents an embedded .resources file, instantiate an object from the assembly in which the .resources file is embedded. Its method returns a object that can be passed to the constructor. The following example instantiates a object that represents an embedded .resources file. [!code-csharp[System.Resources.ResourceReader.Class#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resourcereader.class/cs/ctor1.cs#3)] [!code-vb[System.Resources.ResourceReader.Class#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.class/vb/ctor1.vb#3)] ## Enumerating a ResourceReader Object's Resources - To enumerate the resources in a .resources file, you call the method, which returns an object. You call the `IDictionaryEnumerator.MoveNext` method to move from one resource to the next. The method returns `false` when all the resources in the .resources file have been enumerated. + To enumerate the resources in a .resources file, you call the method, which returns an object. You call the `IDictionaryEnumerator.MoveNext` method to move from one resource to the next. The method returns `false` when all the resources in the .resources file have been enumerated. > [!NOTE] -> Although the class implements the interface and the method, the method does not provide the implementation. Instead, the method returns an interface object that provides access to each resource's name/value pair. +> Although the class implements the interface and the method, the method does not provide the implementation. Instead, the method returns an interface object that provides access to each resource's name/value pair. You can retrieve the individual resources in the collection in two ways: -- You can iterate each resource in the collection and use properties to retrieve the resource name and value. We recommend this technique when all the resources are of the same type, or you know the data type of each resource. +- You can iterate each resource in the collection and use properties to retrieve the resource name and value. We recommend this technique when all the resources are of the same type, or you know the data type of each resource. -- You can retrieve the name of each resource when you iterate the collection and call the method to retrieve the resource's data. We recommend this approach when you do not know the data type of each resource or if the previous approach throws exceptions. +- You can retrieve the name of each resource when you iterate the collection and call the method to retrieve the resource's data. We recommend this approach when you do not know the data type of each resource or if the previous approach throws exceptions. ### Retrieving Resources by Using IDictionaryEnumerator Properties - The first method of enumerating the resources in a .resources file involves directly retrieving each resource's name/value pair. After you call the `IDictionaryEnumerator.MoveNext` method to move to each resource in the collection, you can retrieve the resource name from the property and the resource data from the property. + The first method of enumerating the resources in a .resources file involves directly retrieving each resource's name/value pair. After you call the `IDictionaryEnumerator.MoveNext` method to move to each resource in the collection, you can retrieve the resource name from the property and the resource data from the property. - The following example shows how to retrieve the name and value of each resource in a .resources file by using the and properties. To run the example, create the following text file named ApplicationResources.txt to define string resources. + The following example shows how to retrieve the name and value of each resource in a .resources file by using the and properties. To run the example, create the following text file named ApplicationResources.txt to define string resources. ``` Title="Contact Information" @@ -117,7 +117,7 @@ Label15="Alternate Email Address:" [!code-csharp[System.Resources.ResourceReader.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.resources.resourcereader.class/cs/class1.cs#1)] [!code-vb[System.Resources.ResourceReader.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.resources.resourcereader.class/vb/class1.vb#1)] - The attempt to retrieve resource data from the property can throw the following exceptions: + The attempt to retrieve resource data from the property can throw the following exceptions: - A if the data is not in the expected format. @@ -125,13 +125,13 @@ Label15="Alternate Email Address:" - A if the type to which the data belongs cannot be cannot be found. - Typically, these exceptions are thrown if the .resources file has been modified manually, if the assembly in which a type is defined has either not been included with an application or has been inadvertently deleted, or if the assembly is an older version that predates a type. If one of these exceptions is thrown, you can retrieve resources by enumerating each resource and calling the method, as the following section shows. This approach provides you with some information about the data type that the property attempted to return. + Typically, these exceptions are thrown if the .resources file has been modified manually, if the assembly in which a type is defined has either not been included with an application or has been inadvertently deleted, or if the assembly is an older version that predates a type. If one of these exceptions is thrown, you can retrieve resources by enumerating each resource and calling the method, as the following section shows. This approach provides you with some information about the data type that the property attempted to return. ### Retrieving Resources by Name with GetResourceData - The second approach to enumerating resources in a .resources file also involves navigating through the resources in the file by calling the `IDictionaryEnumerator.MoveNext` method. For each resource, you retrieve the resource's name from the property, which is then passed to the method to retrieve the resource's data. This is returned as a byte array in the `resourceData` argument. + The second approach to enumerating resources in a .resources file also involves navigating through the resources in the file by calling the `IDictionaryEnumerator.MoveNext` method. For each resource, you retrieve the resource's name from the property, which is then passed to the method to retrieve the resource's data. This is returned as a byte array in the `resourceData` argument. - This approach is more awkward than retrieving the resource name and value from the and properties, because it returns the actual bytes that form the resource value. However, if the attempt to retrieve the resource throws an exception, the method can help identify the source of the exception by supplying information about the resource's data type. For more information about the string that indicates the resource's data type, see . + This approach is more awkward than retrieving the resource name and value from the and properties, because it returns the actual bytes that form the resource value. However, if the attempt to retrieve the resource throws an exception, the method can help identify the source of the exception by supplying information about the resource's data type. For more information about the string that indicates the resource's data type, see . The following example illustrates how to use this approach to retrieve resources and to handle any exceptions that are thrown. It programmatically creates a binary .resources file that contains four strings, one Boolean, one integer, one bitmap, and one custom `DateTimeTZI` object. To run the example, do the following: @@ -238,7 +238,7 @@ Label15="Alternate Email Address:" constructor instantiates a object that retrieves resources either from a standalone .resources file or from a .resources file that is embedded in an assembly. To read from a standalone .resources file, instantiate a object and pass it to the constructor. To read from an embedded .resources file, call the method with the case-sensitive name of the .resources file, and pass the returned object to the constructor. + The constructor instantiates a object that retrieves resources either from a standalone .resources file or from a .resources file that is embedded in an assembly. To read from a standalone .resources file, instantiate a object and pass it to the constructor. To read from an embedded .resources file, call the method with the case-sensitive name of the .resources file, and pass the returned object to the constructor. > [!IMPORTANT] > Using an instance of this object with untrusted data is a security risk. Use this object only with trusted data. For more information, see [Untrusted Data Security Risks](http://go.microsoft.com/fwlink/?LinkId=330378). @@ -486,9 +486,9 @@ Label11="Mobile Phone:" method and then repeatedly calling the method on the returned object until the method returns `false`. The resource name is available from the property; its value from the property. The example illustrates how to enumerate resources in this way. + Typically, you enumerate resources by calling the method and then repeatedly calling the method on the returned object until the method returns `false`. The resource name is available from the property; its value from the property. The example illustrates how to enumerate resources in this way. - The implementation of the property by the class can throw the following exceptions: + The implementation of the property by the class can throw the following exceptions: - @@ -586,9 +586,9 @@ Label11="Mobile Phone:" |ResourceTypeCode value|Description| |----------------------------|-----------------| - |`ResourceTypeCode.ByteArray`|The data is a byte array. This data type commonly results from the call to the method.| - |`ResourceTypeCode.Null`|The data is a null reference. This data type commonly results from the call to the method with an object whose value is `null`.| - |`ResourceTypeCode.Stream`|The data is stored in a stream. This data type commonly results from the call to the or method.| + |`ResourceTypeCode.ByteArray`|The data is a byte array. This data type commonly results from the call to the method.| + |`ResourceTypeCode.Null`|The data is a null reference. This data type commonly results from the call to the method with an object whose value is `null`.| + |`ResourceTypeCode.Stream`|The data is stored in a stream. This data type commonly results from the call to the or method.| Assuming that `resourceData` has not been corrupted, it can usually be converted from a byte array back to its original value by calling a or method. @@ -596,9 +596,9 @@ Label11="Mobile Phone:" `Extensions.Person, Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null` - Assuming that `resourceData` has not been corrupted and that the source type is available, `resourceData` can be converted from a byte array back to its original value by converting the byte array to a object and passing the stream to the method. + Assuming that `resourceData` has not been corrupted and that the source type is available, `resourceData` can be converted from a byte array back to its original value by converting the byte array to a object and passing the stream to the method. -- The string used to describe the data type in the method call. +- The string used to describe the data type in the method call. ]]> @@ -641,7 +641,7 @@ Label11="Mobile Phone:" is an explicit interface implementation. It can be used only when the instance is cast to an interface. The recommended approach to enumerating the resources in a .resources file is to call the method of the object returned by the method. + is an explicit interface implementation. It can be used only when the instance is cast to an interface. The recommended approach to enumerating the resources in a .resources file is to call the method of the object returned by the method. ]]> diff --git a/xml/System.Resources/ResourceSet.xml b/xml/System.Resources/ResourceSet.xml index 403e19697cb1a..6fa3dac6c2ace 100644 --- a/xml/System.Resources/ResourceSet.xml +++ b/xml/System.Resources/ResourceSet.xml @@ -41,7 +41,7 @@ ## Remarks The class enumerates over an , loading every name and value, and storing them in a . A custom can be used. - You can instantiate a object that represents the resources of a specific culture by calling the method. + You can instantiate a object that represents the resources of a specific culture by calling the method. > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. @@ -266,7 +266,7 @@ Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the memory it was occupying can be reclaimed by garbage collection. > [!NOTE] -> The current method is the implementation of . This implementation calls (`true`). +> The current method is the implementation of . This implementation calls (`true`). ]]> @@ -415,7 +415,7 @@ An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . If the collection is modified between and , will return the element that it is set to, even if the enumerator is already invalidated. - You can use the property to access the value stored in the current element. Use the property to access the key of the current element. Use the property to access the value of the current element. + You can use the property to access the value stored in the current element. Use the property to access the key of the current element. Use the property to access the value of the current element. The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -507,7 +507,7 @@ . The advantage is that results of case-insensitive string comparisons performed by this method are the same on all computers regardless of culture. The disadvantage is that the results are not consistent with the casing rules of all cultures. + If the value of the `ignoreCase` parameter is `true`, a resource with the name "Resource" is equivalent to the resource with the name "resource". Note, however, that this method always performs case-insensitive string comparisons using . The advantage is that results of case-insensitive string comparisons performed by this method are the same on all computers regardless of culture. The disadvantage is that the results are not consistent with the casing rules of all cultures. For example, the Turkish alphabet has two versions of the character I: one with a dot and one without a dot. In Turkish, the character I (Unicode 0049) is considered the uppercase version of a different character ı (Unicode 0131). The character i (Unicode 0069) is considered the lowercase version of yet another character İ (Unicode 0130). According to these casing rules, a case-insensitive string comparison of the characters i (Unicode 0069) and I (Unicode 0049) should fail for the culture "tr-TR" (Turkish in Turkey). Using the `GetObject` method with `ignoreCase` set to `true`, this comparison succeeds. @@ -585,7 +585,7 @@ . The advantage is that results of case-insensitive string comparisons performed by this method are the same on all computers regardless of culture. The disadvantage is that the results are not consistent with the casing rules of all cultures. + If the value of the `ignoreCase` parameter is `true`, a resource with the name "Resource" is equivalent to the resource with the name "resource". Note, however, that this method always performs case-insensitive string comparisons using . The advantage is that results of case-insensitive string comparisons performed by this method are the same on all computers regardless of culture. The disadvantage is that the results are not consistent with the casing rules of all cultures. For example, the Turkish alphabet has two versions of the character I: one with a dot and one without a dot. In Turkish, the character I (Unicode 0049) is considered the uppercase version of a different character ı (Unicode 0131). The character i (Unicode 0069) is considered the lowercase version of yet another character İ (Unicode 0130). According to these casing rules, a case-insensitive string comparison of the characters i (Unicode 0069) and I (Unicode 0049) should fail for the culture "tr-TR" (Turkish in Turkey). Using the `GetString` method with `ignoreCase` set to `true`, this comparison succeeds. diff --git a/xml/System.Resources/ResourceWriter.xml b/xml/System.Resources/ResourceWriter.xml index 4717ad1a51489..7312865524450 100644 --- a/xml/System.Resources/ResourceWriter.xml +++ b/xml/System.Resources/ResourceWriter.xml @@ -178,7 +178,7 @@ ## Remarks The resource is not written until is called. - You can retrieve the resources written by the method by calling the method. + You can retrieve the resources written by the method by calling the method. @@ -229,9 +229,9 @@ property for `value`. + You can specify any stream that supports the property for `value`. - You can retrieve the resources written by the method by calling the method. + You can retrieve the resources written by the method by calling the method. @@ -291,7 +291,7 @@ The resource is not written until the method is called. - You can retrieve the resources written by the method by calling the method. + You can retrieve the resources written by the method by calling the method. @@ -347,7 +347,7 @@ ## Remarks The resource is not written until is called. - You can retrieve the resources written by the method by calling the method. + You can retrieve the resources written by the method by calling the method. @@ -402,9 +402,9 @@ property for `value`. + You can specify any stream that supports the property for `value`. - You can retrieve the resources written by the method by calling the method. + You can retrieve the resources written by the method by calling the method. @@ -478,7 +478,7 @@ `Extensions.Person, Utility, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null` - A parallel method for reading resource data written with the method is . + A parallel method for reading resource data written with the method is . diff --git a/xml/System.Resources/UltimateResourceFallbackLocation.xml b/xml/System.Resources/UltimateResourceFallbackLocation.xml index 2db0c7e43e322..e35e8f30b4798 100644 --- a/xml/System.Resources/UltimateResourceFallbackLocation.xml +++ b/xml/System.Resources/UltimateResourceFallbackLocation.xml @@ -29,7 +29,7 @@ enumeration is used with the constructor to specify whether a object retrieves the resources of the app's default culture from the main app assembly (the default), or from a satellite assembly. In a localized application, the resources of the default culture are used if no culture-specific resources are found after using the resource fallback process. For more information, see the "Resource Fallback Process" section in [Packaging and Deploying Resources](~/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md). + The enumeration is used with the constructor to specify whether a object retrieves the resources of the app's default culture from the main app assembly (the default), or from a satellite assembly. In a localized application, the resources of the default culture are used if no culture-specific resources are found after using the resource fallback process. For more information, see the "Resource Fallback Process" section in [Packaging and Deploying Resources](~/docs/framework/resources/packaging-and-deploying-resources-in-desktop-apps.md). If you specify a value of MainAssembly or no value to the attribute and resource manager cannot load a resource set that belongs to the default culture, it throws a exception. If you specify a value of Satellite to the and resource manager cannot load a resource set that belongs to the default culture, it throws a exception. diff --git a/xml/System.Runtime.Caching/MemoryCache.xml b/xml/System.Runtime.Caching/MemoryCache.xml index 09b2c4f3daf98..165e0022d0b02 100644 --- a/xml/System.Runtime.Caching/MemoryCache.xml +++ b/xml/System.Runtime.Caching/MemoryCache.xml @@ -27,7 +27,7 @@ The class does not allow `null` as a value in the cache. Any attempt to add or change a cache entry with a value of `null` will fail. - The type does not implement *cache regions*. Therefore, when you call methods that implement base methods that contain a parameter for regions, do not pass a value for the parameter. The methods that use the region parameter all supply a default `null` value. For example, the method overload has a `regionName` parameter whose default value is `null`. + The type does not implement *cache regions*. Therefore, when you call methods that implement base methods that contain a parameter for regions, do not pass a value for the parameter. The methods that use the region parameter all supply a default `null` value. For example, the method overload has a `regionName` parameter whose default value is `null`. @@ -289,7 +289,7 @@ private void btnGet_Click(object sender, EventArgs e) method overload returns `null`. If a matching cache entry exists, the existing entry is returned. + If the cache does not have a cache entry whose key matches the `key` parameter, a new cache entry is created, and the method overload returns `null`. If a matching cache entry exists, the existing entry is returned. > [!WARNING] > The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. @@ -796,7 +796,7 @@ private void btnGet_Click(object sender, EventArgs e) property returns the name of the current instance of the class. In an application that uses multiple cache instances, you can use the property to help distinguish instances. For more information, see the method. The default memory-based cache returns the default name. + The property returns the name of the current instance of the class. In an application that uses multiple cache instances, you can use the property to help distinguish instances. For more information, see the method. The default memory-based cache returns the default name. ]]> @@ -823,7 +823,7 @@ private void btnGet_Click(object sender, EventArgs e) ## Remarks The property returns the percentage of total physical computer memory that can be used by a single instance of the class. If the cache instance exceeds the specified limit, cache entries are removed. - The settings for the property can be specified in the application configuration file. Alternatively, they can be passed by a caller when the class is initialized. For more information about how to configure this property, see [<namedCaches> Element (Cache Settings)](~/docs/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings.md). For more information about how to configure the property when the class is being initialized, see the method. + The settings for the property can be specified in the application configuration file. Alternatively, they can be passed by a caller when the class is initialized. For more information about how to configure this property, see [<namedCaches> Element (Cache Settings)](~/docs/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings.md). For more information about how to configure the property when the class is being initialized, see the method. ]]> @@ -848,7 +848,7 @@ private void btnGet_Click(object sender, EventArgs e) property can be specified in the application configuration file. Alternatively they can be passed when the class is initialized. For more information about how to configure this property, see [<namedCaches> Element (Cache Settings)](~/docs/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings.md). For more information about how to configure the property when the class is being initialized, see the method. + The settings for the property can be specified in the application configuration file. Alternatively they can be passed when the class is initialized. For more information about how to configure this property, see [<namedCaches> Element (Cache Settings)](~/docs/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings.md). For more information about how to configure the property when the class is being initialized, see the method. ]]> diff --git a/xml/System.Runtime.Caching/ObjectCache.xml b/xml/System.Runtime.Caching/ObjectCache.xml index 1425b9f155a41..408186dfeac0a 100644 --- a/xml/System.Runtime.Caching/ObjectCache.xml +++ b/xml/System.Runtime.Caching/ObjectCache.xml @@ -545,7 +545,7 @@ method overload is like the method overload, but lets you pass the named region by using optional parameter syntax that is supported by managed languages such as C#. + The method overload is like the method overload, but lets you pass the named region by using optional parameter syntax that is supported by managed languages such as C#. This method is a virtual method because the class provides a default implementation that passes the `params` array to the method overload. diff --git a/xml/System.Runtime.CompilerServices/AsyncStateMachineAttribute.xml b/xml/System.Runtime.CompilerServices/AsyncStateMachineAttribute.xml index 5eff0010426fc..63991e8477b48 100644 --- a/xml/System.Runtime.CompilerServices/AsyncStateMachineAttribute.xml +++ b/xml/System.Runtime.CompilerServices/AsyncStateMachineAttribute.xml @@ -45,7 +45,7 @@ ## Examples As the following example shows, you can determine whether a method is marked with [Async](~/docs/visual-basic/language-reference/modifiers/async.md) or [async](~/docs/csharp/language-reference/keywords/async.md) modifier. In the example, `IsAsyncMethod` performs the following steps: -- Obtains a object for the method name by using . +- Obtains a object for the method name by using . - Obtains a object for the attribute by using [GetType Operator](~/docs/visual-basic/language-reference/operators/gettype-operator.md) or [typeof](~/docs/csharp/language-reference/keywords/typeof.md). diff --git a/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2+CreateValueCallback.xml b/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2+CreateValueCallback.xml index 9310c6819b25f..47fe9614d3657 100644 --- a/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2+CreateValueCallback.xml +++ b/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2+CreateValueCallback.xml @@ -46,9 +46,9 @@ delegate encapsulates a callback method that is invoked by the method when the key passed to the method is not found in the object. The method passes the callback method the key that represents a managed object to which a property value is to be dynamically attached. The method is responsible for returning the property value to its caller, which, in turn, adds the key/value pair to the table. + The delegate encapsulates a callback method that is invoked by the method when the key passed to the method is not found in the object. The method passes the callback method the key that represents a managed object to which a property value is to be dynamically attached. The method is responsible for returning the property value to its caller, which, in turn, adds the key/value pair to the table. - The method is used to return an instance of a reference type that can be attached to the specified key. It enables that instance to be initialized using non-default values. If the key is not found in the table, the method adds a key/value pair in which the value is initialized using default values. + The method is used to return an instance of a reference type that can be attached to the specified key. It enables that instance to be initialized using non-default values. If the key is not found in the table, the method adds a key/value pair in which the value is initialized using default values. diff --git a/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2.xml b/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2.xml index 7e85712ac5437..a1202782bbc2c 100644 --- a/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2.xml +++ b/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2.xml @@ -44,10 +44,10 @@ ## Remarks The class enables language compilers to attach arbitrary properties to managed objects at run time. A object is a dictionary that binds a managed object, which is represented by a key, to its attached property, which is represented by a value. The object's keys are the individual instances of the `TKey` class to which the property is attached, and its values are the property values that are assigned to the corresponding objects. - Keys must be unique; in other words, the class supports one attached value per managed object. Two keys are equal if passing them to the method returns `true`. + Keys must be unique; in other words, the class supports one attached value per managed object. Two keys are equal if passing them to the method returns `true`. > [!NOTE] -> You cannot control equality comparisons by overriding to explicitly set the hash code for a key. The class does not use the method to compute hash codes, and therefore does not invoke overrides. +> You cannot control equality comparisons by overriding to explicitly set the hash code for a key. The class does not use the method to compute hash codes, and therefore does not invoke overrides. Although the class holds a collection of key/value pairs, it is best thought of as a table rather than a dictionary object. The class differs from a dictionary in several ways: @@ -101,7 +101,7 @@ ## Remarks The constructor instantiates an empty table; that is, the table contains no key/value pairs. You can add key/value pairs by calling the , , or method. - Every key in a object must be unique. Keys are not unique if they refer to the same object (that is, if passing them as arguments to the method returns `true`). + Every key in a object must be unique. Keys are not unique if they refer to the same object (that is, if passing them as arguments to the method returns `true`). ]]> @@ -142,7 +142,7 @@ object must be unique. Keys are not unique if they refer to the same object (that is, if passing them as arguments to the method returns `true`). + Every key in a object must be unique. Keys are not unique if they refer to the same object (that is, if passing them as arguments to the method returns `true`). If the key is garbage-collected during the addition operation, the existing key/value pair is removed and the new key/value pair is added without an exception being thrown. diff --git a/xml/System.Runtime.CompilerServices/DisablePrivateReflectionAttribute.xml b/xml/System.Runtime.CompilerServices/DisablePrivateReflectionAttribute.xml index 83255dd331fc8..439e129ba539b 100644 --- a/xml/System.Runtime.CompilerServices/DisablePrivateReflectionAttribute.xml +++ b/xml/System.Runtime.CompilerServices/DisablePrivateReflectionAttribute.xml @@ -32,7 +32,7 @@ or , can be used to get information about private members at runtime. When applies to an assembly, the attribute makes information about private members in that assembly's types unavailable to runtime reflection. + Ordinarily, reflection methods, such a or , can be used to get information about private members at runtime. When applies to an assembly, the attribute makes information about private members in that assembly's types unavailable to runtime reflection. ]]> diff --git a/xml/System.Runtime.CompilerServices/IteratorStateMachineAttribute.xml b/xml/System.Runtime.CompilerServices/IteratorStateMachineAttribute.xml index 429bdf3e6c331..fb8c220de536d 100644 --- a/xml/System.Runtime.CompilerServices/IteratorStateMachineAttribute.xml +++ b/xml/System.Runtime.CompilerServices/IteratorStateMachineAttribute.xml @@ -48,7 +48,7 @@ ## Examples The following example shows how to determine whether a method is an iterator method. In the example, `IsIteratorMethod` performs the following steps: -- Obtains a object for the method name by using . +- Obtains a object for the method name by using . - Obtains a object for the attribute by using [GetType Operator](~/docs/visual-basic/language-reference/operators/gettype-operator.md). diff --git a/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml b/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml index 265fa2c968a83..47a29ef70a418 100644 --- a/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml +++ b/xml/System.Runtime.CompilerServices/MethodImplAttribute.xml @@ -39,7 +39,7 @@ ## Remarks You can apply this attribute to methods or constructors. - This attribute lets you customize the configuration of the method or constructor to which it applies by supplying a value to its class constructor. The members of the enumeration correspond to bit fields in the `CorMethodImpl` metadata table. This means that information on the attribute cannot be retrieved at run time by calling the method; instead, it is retrieved by calling either the `MethodInfo.GetMethodImplementationFlags` or the `ConstructorInfo.GetMethodImplementationFlags` method. + This attribute lets you customize the configuration of the method or constructor to which it applies by supplying a value to its class constructor. The members of the enumeration correspond to bit fields in the `CorMethodImpl` metadata table. This means that information on the attribute cannot be retrieved at run time by calling the method; instead, it is retrieved by calling either the `MethodInfo.GetMethodImplementationFlags` or the `ConstructorInfo.GetMethodImplementationFlags` method. @@ -49,7 +49,7 @@ [!code-csharp[System.Runtime.CompilerServices.MethodImplAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.compilerservices.methodimplattribute/cs/methodimplattribute1.cs#1)] [!code-vb[System.Runtime.CompilerServices.MethodImplAttribute#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.methodimplattribute/vb/methodimplattribute1.vb#1)] - The following example then calls the `MethodInfo.GetMethodImplementationFlags` method to determine which flags are set for the `GetCalendarName` method. It also demonstrates that this information is not retrieved by the method. + The following example then calls the `MethodInfo.GetMethodImplementationFlags` method to determine which flags are set for the `GetCalendarName` method. It also demonstrates that this information is not retrieved by the method. [!code-csharp[System.Runtime.CompilerServices.MethodImplAttribute#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.compilerservices.methodimplattribute/cs/getmethodimplattribute1.cs#2)] [!code-vb[System.Runtime.CompilerServices.MethodImplAttribute#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.methodimplattribute/vb/getmethodimplattribute1.vb#2)] diff --git a/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml b/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml index 18f328c84df18..56248590f3a95 100644 --- a/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml +++ b/xml/System.Runtime.CompilerServices/RuntimeHelpers.xml @@ -80,7 +80,7 @@ If the stack space is sufficient, the exception is not thrown, and most .NET Framework types and members can still be called. > [!NOTE] -> This method is not part of the constrained execution region (CER) support, and should not be confused with the method. +> This method is not part of the constrained execution region (CER) support, and should not be confused with the method. ]]> @@ -214,16 +214,16 @@ method always calls the method non-virtually, even if the object's type has overridden the method. Therefore, using might differ from calling `GetHashCode` directly on the object with the method. + The method always calls the method non-virtually, even if the object's type has overridden the method. Therefore, using might differ from calling `GetHashCode` directly on the object with the method. > [!WARNING] -> Although the method returns identical hash codes for identical object references, you should not use this method to test for object identity, because this hash code does not uniquely identify an object reference. To test for object identify (that is, to test that two objects reference the same object in memory), call the method. Nor should you use to test whether two strings represent equal object references, because the string is interned. To test for string interning, call the method. +> Although the method returns identical hash codes for identical object references, you should not use this method to test for object identity, because this hash code does not uniquely identify an object reference. To test for object identify (that is, to test that two objects reference the same object in memory), call the method. Nor should you use to test whether two strings represent equal object references, because the string is interned. To test for string interning, call the method. - The and methods differ as follows: + The and methods differ as follows: -- returns a hash code that is based on the object's definition of equality. For example, two strings with identical contents will return the same value for . +- returns a hash code that is based on the object's definition of equality. For example, two strings with identical contents will return the same value for . -- returns a hash code that indicates object identity. That is, two string variables whose contents are identical and that represent a string that is interned (see the [String Interning](#interning) section) or that represent a single string in memory return identical hash codes. +- returns a hash code that indicates object identity. That is, two string variables whose contents are identical and that represent a string that is interned (see the [String Interning](#interning) section) or that represent a single string in memory return identical hash codes. > [!IMPORTANT] > Note that always returns identical hash codes for equal object references. However, the reverse is not true: equal hash codes do not indicate equal object references. A particular hash code value is not unique to a particular object reference; different object references can generate identical hash codes. @@ -232,24 +232,24 @@ ## String Interning - The common language runtime (CLR) maintains an internal pool of strings and stores literals in the pool. If two strings (for example, `str1` and `str2`) are formed from an identical string literal, the CLR will set `str1` and `str2` to point to the same location on the managed heap to conserve memory. Calling on these two string objects will produce the same hash code, contrary to the second bulleted item in the previous section. + The common language runtime (CLR) maintains an internal pool of strings and stores literals in the pool. If two strings (for example, `str1` and `str2`) are formed from an identical string literal, the CLR will set `str1` and `str2` to point to the same location on the managed heap to conserve memory. Calling on these two string objects will produce the same hash code, contrary to the second bulleted item in the previous section. - The CLR adds only literals to the pool. Results of string operations such as concatenation are not added to the pool, unless the compiler resolves the string concatenation as a single string literal. Therefore, if `str2` was created as the result of a concatenation operation, and `str2` is identical to `str1`, using on these two string objects will not produce the same hash code. + The CLR adds only literals to the pool. Results of string operations such as concatenation are not added to the pool, unless the compiler resolves the string concatenation as a single string literal. Therefore, if `str2` was created as the result of a concatenation operation, and `str2` is identical to `str1`, using on these two string objects will not produce the same hash code. - If you want to add a concatenated string to the pool explicitly, use the method. + If you want to add a concatenated string to the pool explicitly, use the method. - You can also use the method to check whether a string has an interned reference. + You can also use the method to check whether a string has an interned reference. ## Examples - The following example demonstrates the difference between the and methods. The output from the example illustrates the following: + The following example demonstrates the difference between the and methods. The output from the example illustrates the following: - Both sets of hash codes for the first set of strings passed to the `ShowHashCodes` method are different, because the strings are completely different. -- generates the same hash code for the second set of strings passed to the `ShowHashCodes` method, because the strings are equal. However, the method does not. The first string is defined by using a string literal and so is interned. Although the value of the second string is the same, it is not interned, because it is returned by a call to the method. +- generates the same hash code for the second set of strings passed to the `ShowHashCodes` method, because the strings are equal. However, the method does not. The first string is defined by using a string literal and so is interned. Although the value of the second string is the same, it is not interned, because it is returned by a call to the method. -- In the case of the third string, the hash codes produced by for both strings are identical, as are the hash codes produced by . This is because the compiler has treated the value assigned to both strings as a single string literal, and so the string variables refer to the same interned string. +- In the case of the third string, the hash codes produced by for both strings are identical, as are the hash codes produced by . This is because the compiler has treated the value assigned to both strings as a single string literal, and so the string variables refer to the same interned string. [!code-csharp[System.Runtime.CompilerServices.RuntimeHelpers.GetHashCode#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.compilerservices.runtimehelpers.gethashcode/cs/gethashcodeex1.cs#1)] [!code-vb[System.Runtime.CompilerServices.RuntimeHelpers.GetHashCode#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.compilerservices.runtimehelpers.gethashcode/vb/gethashcodeex1.vb#1)] @@ -533,7 +533,7 @@ method. + Compilers should not call this method directly. Instead, define a CER by calling the method. ]]> @@ -751,7 +751,7 @@ This method is also used by compilers. - Instead of using the method, you should use a standard CER. That is, if you are planning to use a moderate amount of stack space, call the method immediately before your `try`/`finally` or `try`/`catch` block. If you are calling a recursive method or plan to use a lot of stack space, you must use the method. + Instead of using the method, you should use a standard CER. That is, if you are planning to use a moderate amount of stack space, call the method immediately before your `try`/`finally` or `try`/`catch` block. If you are calling a recursive method or plan to use a lot of stack space, you must use the method. ]]> diff --git a/xml/System.Runtime.ExceptionServices/ExceptionDispatchInfo.xml b/xml/System.Runtime.ExceptionServices/ExceptionDispatchInfo.xml index 278d8ec66f26a..897b0f763af54 100644 --- a/xml/System.Runtime.ExceptionServices/ExceptionDispatchInfo.xml +++ b/xml/System.Runtime.ExceptionServices/ExceptionDispatchInfo.xml @@ -29,7 +29,7 @@ object stores the stack trace information and Watson information that the exception contains at the point where it is captured. The exception can be thrown at another time and possibly on another thread by calling the method. The exception is thrown as if it had flowed from the point where it was captured to the point where the method is called. + The object stores the stack trace information and Watson information that the exception contains at the point where it is captured. The exception can be thrown at another time and possibly on another thread by calling the method. The exception is thrown as if it had flowed from the point where it was captured to the point where the method is called. cannot be serialized and is not intended to cross application domain boundaries. diff --git a/xml/System.Runtime.ExceptionServices/FirstChanceExceptionEventArgs.xml b/xml/System.Runtime.ExceptionServices/FirstChanceExceptionEventArgs.xml index 3acb9f510e85f..c81564629fde5 100644 --- a/xml/System.Runtime.ExceptionServices/FirstChanceExceptionEventArgs.xml +++ b/xml/System.Runtime.ExceptionServices/FirstChanceExceptionEventArgs.xml @@ -25,7 +25,7 @@ event with access to the exception. + This class provides the exception handler for the event with access to the exception. @@ -115,7 +115,7 @@ event can examine the exception and perform appropriate logging or other notification services. + The method that handles the event can examine the exception and perform appropriate logging or other notification services. For example code, see . diff --git a/xml/System.Runtime.Hosting/ApplicationActivator.xml b/xml/System.Runtime.Hosting/ApplicationActivator.xml index 2892751479c4f..3f1910747a9e6 100644 --- a/xml/System.Runtime.Hosting/ApplicationActivator.xml +++ b/xml/System.Runtime.Hosting/ApplicationActivator.xml @@ -34,7 +34,7 @@ 2. Calls the method to create a new domain using the object. - 3. The method calls the method to acquire an object for the add-in. If the property returns `true`, the add-in is executed. If not, throws a indicating that execution permission could not be acquired. + 3. The method calls the method to acquire an object for the add-in. If the property returns `true`, the add-in is executed. If not, throws a indicating that execution permission could not be acquired. 4. If the add-in is trusted to run, then a new is created and configured for the of the add-in, and the add-in is loaded and executed. diff --git a/xml/System.Runtime.InteropServices.ComTypes/CONNECTDATA.xml b/xml/System.Runtime.InteropServices.ComTypes/CONNECTDATA.xml index 896466fb9fe88..4bc05b7457f17 100644 --- a/xml/System.Runtime.InteropServices.ComTypes/CONNECTDATA.xml +++ b/xml/System.Runtime.InteropServices.ComTypes/CONNECTDATA.xml @@ -30,7 +30,7 @@ method. + The `CONNECTDATA` structure is the type enumerated through the method. For more information about `CONNECTDATA`, see the MSDN Library. diff --git a/xml/System.Runtime.InteropServices/ArrayWithOffset.xml b/xml/System.Runtime.InteropServices/ArrayWithOffset.xml index a429ebd7253be..499fc87038b35 100644 --- a/xml/System.Runtime.InteropServices/ArrayWithOffset.xml +++ b/xml/System.Runtime.InteropServices/ArrayWithOffset.xml @@ -291,7 +291,7 @@ if the value of is the same as the value of ; otherwise, . - .]]> + .]]> @@ -332,7 +332,7 @@ if the value of is not the same as the value of ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Runtime.InteropServices/BestFitMappingAttribute.xml b/xml/System.Runtime.InteropServices/BestFitMappingAttribute.xml index 3f8544d073826..2bb7bc52ce2b7 100644 --- a/xml/System.Runtime.InteropServices/BestFitMappingAttribute.xml +++ b/xml/System.Runtime.InteropServices/BestFitMappingAttribute.xml @@ -45,7 +45,7 @@ > [!CAUTION] > Some characters lack a best-fit representation; these characters are called unmappable. Unmappable characters are usually converted to the default '?' ANSI character. Certain Unicode characters are converted to dangerous characters, such as the backslash '\\' character, which can inadvertently change a path. - provides two parameters to control aspects of best-fit mapping. You use the first parameter to toggle best-fit mapping on and off. The default value is `true`, which enables best-fit mapping on the assembly, interface, and class levels. An attribute applied to an interface or class overrides an assembly-level attribute. You can likewise enable or disable best-fit mapping for platform invoke calls by using the field. A value set by the platform invoke field overrides all levels of . + provides two parameters to control aspects of best-fit mapping. You use the first parameter to toggle best-fit mapping on and off. The default value is `true`, which enables best-fit mapping on the assembly, interface, and class levels. An attribute applied to an interface or class overrides an assembly-level attribute. You can likewise enable or disable best-fit mapping for platform invoke calls by using the field. A value set by the platform invoke field overrides all levels of . You can use the second parameter to control throwing an exception on unmappable characters. The default value for the field is `false`, which disables throwing an exception each time the runtime encounters a Unicode character that has to be converted to the '?' ANSI character. Even if best-fit mapping is `true`, unmappable characters generate an exception when the field is `true`. To tighten security, you can toggle the first parameter to `false` and the second parameter to `true`. This combination of parameter settings turns best-fit mapping off, but enables the exception-throwing mechanism as a safety precaution. diff --git a/xml/System.Runtime.InteropServices/CONNECTDATA.xml b/xml/System.Runtime.InteropServices/CONNECTDATA.xml index 40c552d52b203..812f1907cd594 100644 --- a/xml/System.Runtime.InteropServices/CONNECTDATA.xml +++ b/xml/System.Runtime.InteropServices/CONNECTDATA.xml @@ -22,7 +22,7 @@ method. + The `CONNECTDATA` structure is the type enumerated through the method. For more information about `CONNECTDATA`, see the MSDN Library. diff --git a/xml/System.Runtime.InteropServices/ClassInterfaceAttribute.xml b/xml/System.Runtime.InteropServices/ClassInterfaceAttribute.xml index bc262052768eb..a9c0faf0af28e 100644 --- a/xml/System.Runtime.InteropServices/ClassInterfaceAttribute.xml +++ b/xml/System.Runtime.InteropServices/ClassInterfaceAttribute.xml @@ -42,11 +42,11 @@ This attribute controls whether the Type Library Exporter (Tlbexp.exe) automatically generates a class interface for the attributed class. A class interface carries the same name as the class itself, but the name is prefixed with an underscore. When exposed, the class interface contains all the `public`, non- `static` members of the managed class, including members inherited from its base class. Managed classes cannot access a class interface and have no need to as they can access the class members directly. Tlbexp.exe generates a unique interface identifier (IID) for the class interface. - Class interfaces can be dual or dispatch-only interfaces. Optionally, you can suppress the generation of the class interface and provide a custom interface instead. You expose or suppress a class interface by specifying a enumeration member. When you apply to an assembly, the attribute pertains to all classes in the assembly unless the individual classes override the setting with their own attribute. + Class interfaces can be dual or dispatch-only interfaces. Optionally, you can suppress the generation of the class interface and provide a custom interface instead. You expose or suppress a class interface by specifying a enumeration member. When you apply to an assembly, the attribute pertains to all classes in the assembly unless the individual classes override the setting with their own attribute. Although class interfaces eliminate the task of explicitly defining interfaces for each class, their use in production applications is strongly discouraged. Dual class interfaces allow clients to bind to a specific interface layout that is subject to change as the class evolves. For example, consider a managed class that exposes a class interface to COM clients. The first version of the class contains methods `North` and `South`. An unmanaged client can bind to the class interface, which provides `North` as the first method in the class interface and method `South` as the second method. Now consider the next version of the class, which has a new method, `East`, inserted between methods `North` and `South`. Unmanaged clients that try to bind to the new class through the old class interface end up calling method `East` when they intend to call method `South`, because the positioning of methods within the interface has changed. Moreover, any change to the layout of a base class also affects the layout of the class interface for all derived classes. Managed clients, which bind directly to classes, do not exhibit the same versioning problems. For specific guidelines on using a class interface, see [COM Callable Wrapper](~/docs/framework/interop/com-callable-wrapper.md). - The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) always applies to imported classes the enumeration member to indicate that existing COM classes never expose managed interfaces. + The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) always applies to imported classes the enumeration member to indicate that existing COM classes never expose managed interfaces. diff --git a/xml/System.Runtime.InteropServices/CoClassAttribute.xml b/xml/System.Runtime.InteropServices/CoClassAttribute.xml index 612fb2a8cca0a..9219f4d9f2642 100644 --- a/xml/System.Runtime.InteropServices/CoClassAttribute.xml +++ b/xml/System.Runtime.InteropServices/CoClassAttribute.xml @@ -42,7 +42,7 @@ When Tlbimp.exe imports a coclass, it produces a managed class and an interface to represent the coclass. The coclass interface has the same interface identifier (IID) as the default interface of the original coclass. The imported coclass interface also retains the name of the coclass. Tlbimp.exe appends the original coclass name with "class" to identify the imported class. - You rarely apply this attribute. However, if plan to write source code that produces metadata that closely simulates metadata produced by Tlbimp.exe, you should create a coclass interface for each coclass. Use the name of the original coclass to name the coclass interface and derive it from the default interface. In addition to the , you must also apply the and to the coclass interface. For additional information about how Tlbimp.exe imports interfaces and coclasses from a type library, see [Imported Type Conversion](http://msdn.microsoft.com/en-us/cb1ee67d-8ef0-4e40-b2a5-13714b9f33c3). + You rarely apply this attribute. However, if plan to write source code that produces metadata that closely simulates metadata produced by Tlbimp.exe, you should create a coclass interface for each coclass. Use the name of the original coclass to name the coclass interface and derive it from the default interface. In addition to the , you must also apply the and to the coclass interface. For additional information about how Tlbimp.exe imports interfaces and coclasses from a type library, see [Imported Type Conversion](http://msdn.microsoft.com/en-us/cb1ee67d-8ef0-4e40-b2a5-13714b9f33c3). ]]> diff --git a/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml b/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml index f9546ec53cdc8..9078c6d2afc87 100644 --- a/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml +++ b/xml/System.Runtime.InteropServices/ComAwareEventInfo.xml @@ -30,11 +30,11 @@ and methods instead of using regular add handler and remove handler methods for events. This occurs if the interface that the corresponding event is defined on needs to be embedded. + Normally, compilers will automatically embed calls to the and methods instead of using regular add handler and remove handler methods for events. This occurs if the interface that the corresponding event is defined on needs to be embedded. You can specify this by embedding the entire assembly that contains the interface by using the **/link** option on the compilers or by setting the **Embed Interop Types** property to `True` in Visual Studio. - The type derives from the class and overrides the and methods. + The type derives from the class and overrides the and methods. ]]> @@ -112,9 +112,9 @@ method except that it allows you to attach events to COM objects. + This method is similar to the method except that it allows you to attach events to COM objects. - If `target` is a COM object, this method adds a delegate to an event by using the method. + If `target` is a COM object, this method adds a delegate to an event by using the method. facilitates registering COM event sinks that forward calls to corresponding managed delegates. It requires the following information: @@ -126,7 +126,7 @@ - The delegate that would be invoked when the COM object triggers the corresponding event (`handler`). - looks up the corresponding COM source interface (specified as the first parameter of the constructor). It then looks up a method on the source interface whose name is identical to the event name. The value of `GuidAttribute` on the source interface is the GUID that is passed to ; the value of `DispIDAttribute` on the method is the DispID value that is passed to . + looks up the corresponding COM source interface (specified as the first parameter of the constructor). It then looks up a method on the source interface whose name is identical to the event name. The value of `GuidAttribute` on the source interface is the GUID that is passed to ; the value of `DispIDAttribute` on the method is the DispID value that is passed to . ]]> @@ -237,7 +237,7 @@ method. + This method calls the method. ]]> @@ -534,9 +534,9 @@ method, except that it allows you to detach events from COM objects. + This method is similar to the method, except that it allows you to detach events from COM objects. - If `target` is a COM object, this method releases a delegate to an event by using the method. + If `target` is a COM object, this method releases a delegate to an event by using the method. facilitates unregistering COM event sinks that forward calls to corresponding managed delegates. It requires the following information: @@ -548,7 +548,7 @@ - The delegate that would be invoked when the COM object triggers the corresponding event (`handler`). - looks up the corresponding COM source interface (specified as the first parameter of the constructor). It then it looks up a method on the source interface whose name is identical to the event name. The value of `GuidAttribute` on the source interface is the GUID that is passed to ; the value of `DispIDAttribute` on the method is the DispID value that is passed to . + looks up the corresponding COM source interface (specified as the first parameter of the constructor). It then it looks up a method on the source interface whose name is identical to the event name. The value of `GuidAttribute` on the source interface is the GUID that is passed to ; the value of `DispIDAttribute` on the method is the DispID value that is passed to . ]]> diff --git a/xml/System.Runtime.InteropServices/ComCompatibleVersionAttribute.xml b/xml/System.Runtime.InteropServices/ComCompatibleVersionAttribute.xml index e936edf6a98ea..da213eceb7622 100644 --- a/xml/System.Runtime.InteropServices/ComCompatibleVersionAttribute.xml +++ b/xml/System.Runtime.InteropServices/ComCompatibleVersionAttribute.xml @@ -37,7 +37,7 @@ By default, the [Tlbexp.exe (Type Library Exporter)](~/docs/framework/tools/tlbexp-exe-type-library-exporter.md) uses an assembly's version number to calculate class identifiers (CLSIDs). All public, COM-visible classes receive new CLSIDs each time you export a new assembly version. - You can apply the `ComCompatibleVersionAttribute` attribute to force all CLSIDs for classes in the current version of an assembly to be the same as CLSIDs for classes in an earlier version of the assembly. As long as the CLSIDs remain the same, a legacy COM application can use the later version of a compatible assembly after you uninstall the original assembly. If you apply the to a class to explicitly set its CLSID, the `ComCompatibleVersionAttribute` has no effect. + You can apply the `ComCompatibleVersionAttribute` attribute to force all CLSIDs for classes in the current version of an assembly to be the same as CLSIDs for classes in an earlier version of the assembly. As long as the CLSIDs remain the same, a legacy COM application can use the later version of a compatible assembly after you uninstall the original assembly. If you apply the to a class to explicitly set its CLSID, the `ComCompatibleVersionAttribute` has no effect. The properties of this attribute combine to form the four parts of an assembly version. Always specify the lowest version that the current assembly is backward compatible with so that version is used to calculate all CLSIDs in the assembly. diff --git a/xml/System.Runtime.InteropServices/ComRegisterFunctionAttribute.xml b/xml/System.Runtime.InteropServices/ComRegisterFunctionAttribute.xml index 21f41a62bb9a8..b12ecde9bed16 100644 --- a/xml/System.Runtime.InteropServices/ComRegisterFunctionAttribute.xml +++ b/xml/System.Runtime.InteropServices/ComRegisterFunctionAttribute.xml @@ -35,9 +35,9 @@ ## Remarks You can apply this attribute to methods. - enables you to add arbitrary registration code to accommodate the requirements of COM clients. For example, you can update the registry using registration functions from the namespace. If you provide a registration method, you must also apply to an unregistration method, which reverses the operations done in the registration method. + enables you to add arbitrary registration code to accommodate the requirements of COM clients. For example, you can update the registry using registration functions from the namespace. If you provide a registration method, you must also apply to an unregistration method, which reverses the operations done in the registration method. - The common language runtime calls the method with this attribute when its containing assembly is registered (directly or indirectly) with the [Regasm.exe (Assembly Registration Tool)](~/docs/framework/tools/regasm-exe-assembly-registration-tool.md)or through the method. + The common language runtime calls the method with this attribute when its containing assembly is registered (directly or indirectly) with the [Regasm.exe (Assembly Registration Tool)](~/docs/framework/tools/regasm-exe-assembly-registration-tool.md)or through the method. This attribute can be applied only to methods that have the following characteristics: diff --git a/xml/System.Runtime.InteropServices/ComUnregisterFunctionAttribute.xml b/xml/System.Runtime.InteropServices/ComUnregisterFunctionAttribute.xml index fe136c87b938c..21133b5a40424 100644 --- a/xml/System.Runtime.InteropServices/ComUnregisterFunctionAttribute.xml +++ b/xml/System.Runtime.InteropServices/ComUnregisterFunctionAttribute.xml @@ -37,7 +37,7 @@ enables you to add code that reverses the operations performed by a registration method. If you apply the to provide a registration method, you must also provide an unregistration method to reverse the operations done in the registration method. You can have only one unregistration method for a class. - The common language runtime calls the method with this attribute when its containing assembly is unregistered (directly or indirectly) with the [Regasm.exe (Assembly Registration Tool)](~/docs/framework/tools/regasm-exe-assembly-registration-tool.md) or through the API method. Methods with this attribute can have any visibility (public, private, and so on), but must be `static` and must take a single parameter for the to unregister. + The common language runtime calls the method with this attribute when its containing assembly is unregistered (directly or indirectly) with the [Regasm.exe (Assembly Registration Tool)](~/docs/framework/tools/regasm-exe-assembly-registration-tool.md) or through the API method. Methods with this attribute can have any visibility (public, private, and so on), but must be `static` and must take a single parameter for the to unregister. diff --git a/xml/System.Runtime.InteropServices/CriticalHandle.xml b/xml/System.Runtime.InteropServices/CriticalHandle.xml index b7b6a63cd6531..b8639dc3d6858 100644 --- a/xml/System.Runtime.InteropServices/CriticalHandle.xml +++ b/xml/System.Runtime.InteropServices/CriticalHandle.xml @@ -46,7 +46,7 @@ ## Remarks The class is similar to the class, except that implements reference counting. You can use instead of to address performance considerations when you can provide the necessary synchronization more efficiently yourself. - Because the class does not perform reference counting, it does not provide protection from handle recycling security attacks. Because the reference counting algorithm implicitly serializes operations, a certain amount of thread safety is also lost. If you call the or method while an operation that is using the handle is outstanding on another thread, or if you call or from two threads at the same time, the results are non-deterministic. The class still provides the guaranteed critical finalization provided by the class. + Because the class does not perform reference counting, it does not provide protection from handle recycling security attacks. Because the reference counting algorithm implicitly serializes operations, a certain amount of thread safety is also lost. If you call the or method while an operation that is using the handle is outstanding on another thread, or if you call or from two threads at the same time, the results are non-deterministic. The class still provides the guaranteed critical finalization provided by the class. ]]> diff --git a/xml/System.Runtime.InteropServices/DllImportAttribute.xml b/xml/System.Runtime.InteropServices/DllImportAttribute.xml index 0fc5315716037..769b72599c869 100644 --- a/xml/System.Runtime.InteropServices/DllImportAttribute.xml +++ b/xml/System.Runtime.InteropServices/DllImportAttribute.xml @@ -146,7 +146,7 @@ field is `true` by default. Settings for this field override the any level settings for the attribute. + If `true`, best-fit mapping behavior is enabled; otherwise, best-fit mapping is disabled. The field is `true` by default. Settings for this field override the any level settings for the attribute. The common language runtime converts to ANSI characters any managed Unicode characters passed to an unmanaged method executing on Windows 98 or Windows Me. Best-fit mapping enables the interop marshaler to provide a close-matching character when no exact match exists. For example, the marshaler converts the Unicode copyright character to 'c' for unmanaged methods that accept ANSI characters. Some characters lack a best-fit representation; these characters are called unmappable. Unmappable characters are usually converted to the default '?' ANSI character. @@ -344,7 +344,7 @@ field is set to `CharSet.Ansi`, and the entry-point name appended with the letter W is invoked when the field is set to the `CharSet.Unicode`. Typically, managed compilers set this field. + If `false`, the entry point name appended with the letter A is invoked when the field is set to `CharSet.Ansi`, and the entry-point name appended with the letter W is invoked when the field is set to the `CharSet.Unicode`. Typically, managed compilers set this field. The following table shows the relationship between the and fields, based on default values imposed by the programming language. You can override the default setting, but do so with caution. diff --git a/xml/System.Runtime.InteropServices/FieldOffsetAttribute.xml b/xml/System.Runtime.InteropServices/FieldOffsetAttribute.xml index 9bd76e8bcc9ff..61bfda2a73e51 100644 --- a/xml/System.Runtime.InteropServices/FieldOffsetAttribute.xml +++ b/xml/System.Runtime.InteropServices/FieldOffsetAttribute.xml @@ -39,7 +39,7 @@ ## Remarks You can apply this attribute to fields. - This attribute is used when , with passed to its constructor, is applied to a class or structure to specify the offset of each non- `static` or constant member within the unmanaged representation of that class or structure. + This attribute is used when , with passed to its constructor, is applied to a class or structure to specify the offset of each non- `static` or constant member within the unmanaged representation of that class or structure. @@ -50,7 +50,7 @@ [!code-csharp[Classic FieldOffsetAttribute Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic FieldOffsetAttribute Example/CS/source.cs#1)] [!code-vb[Classic FieldOffsetAttribute Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_Classic/classic FieldOffsetAttribute Example/VB/source.vb#1)] - For a larger example, see the class. + For a larger example, see the class. ]]> diff --git a/xml/System.Runtime.InteropServices/GCHandle.xml b/xml/System.Runtime.InteropServices/GCHandle.xml index 63ca9a7e7360a..9ce83c36cce7f 100644 --- a/xml/System.Runtime.InteropServices/GCHandle.xml +++ b/xml/System.Runtime.InteropServices/GCHandle.xml @@ -446,7 +446,7 @@ if the and parameters are equal; otherwise, . - .]]> + .]]> @@ -559,7 +559,7 @@ if the and parameters are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Runtime.InteropServices/HandleRef.xml b/xml/System.Runtime.InteropServices/HandleRef.xml index 3b136c1c8cf64..f10f69fe5a8a9 100644 --- a/xml/System.Runtime.InteropServices/HandleRef.xml +++ b/xml/System.Runtime.InteropServices/HandleRef.xml @@ -36,7 +36,7 @@ If you use platform invoke to call a managed object, and the object is not referenced elsewhere after the platform invoke call, it is possible for the garbage collector to finalize the managed object. This action releases the resource and invalidates the handle, causing the platform invoke call to fail. Wrapping a handle with guarantees that the managed object is not garbage collected until the platform invoke call completes. For a description of platform invoke services, see [Consuming Unmanaged DLL Functions](~/docs/framework/interop/consuming-unmanaged-dll-functions.md). - The value type, like , is a special type recognized by the interop marshaler. A normal, nonpinned also prevents untimely garbage collection, yet provides better performance. Although using to keep an object alive for the duration of a platform invoke call is preferred, you can also use the method for the same purpose. + The value type, like , is a special type recognized by the interop marshaler. A normal, nonpinned also prevents untimely garbage collection, yet provides better performance. Although using to keep an object alive for the duration of a platform invoke call is preferred, you can also use the method for the same purpose. The constructor takes two parameters: an representing the wrapper, and an representing the unmanaged handle. The interop marshaler passes only the handle to unmanaged code, and guarantees that the wrapper (passed as the first parameter to the constructor of the `HandleRef`) remains alive for the duration of the call. diff --git a/xml/System.Runtime.InteropServices/ICustomMarshaler.xml b/xml/System.Runtime.InteropServices/ICustomMarshaler.xml index 18cc6151b0256..34f88d20b3e1c 100644 --- a/xml/System.Runtime.InteropServices/ICustomMarshaler.xml +++ b/xml/System.Runtime.InteropServices/ICustomMarshaler.xml @@ -88,25 +88,25 @@ const IID IID_IOld = {0x9B2BAADD,0x0705,0x11D3,{0xA0,0xCD,0x00,0xC0,0x4F,0xA3,0x |Information (about native code)||Returns the size of the unmanaged data to be marshaled.| ### Conversion - + Marshals a pointer to native data into a managed object. This method returns a custom runtime callable wrapper (RCW) that can marshal the unmanaged interface that is passed as an argument. The marshaler should return an instance of the custom RCW for that type. - + Marshals a managed object into a pointer to native data. This method returns a custom COM callable wrapper (CCW) that can marshal the managed interface that is passed as an argument. The marshaler should return an instance of the custom CCW for that type. ### Cleanup - + Enables the marshaler to clean up the native data (the CCW) that is returned by the method. - + Enables the marshaler to clean up the managed data (the RCW) that is returned by the method. ### Size Information - + Returns the size of the unmanaged data to be marshaled. @@ -120,7 +120,7 @@ static ICustomMarshaler *GetInstance(String *pstrCookie); ## Applying MarshalAsAttribute To use a custom marshaler, you must apply the attribute to the parameter or field that is being marshaled. - You must also pass the enumeration value to the constructor. In addition, you must specify the field with one of the following named parameters: + You must also pass the enumeration value to the constructor. In addition, you must specify the field with one of the following named parameters: - (required): The assembly-qualified name of the custom marshaler. The name should include the namespace and class of the custom marshaler. If the custom marshaler is not defined in the assembly it is used in, you must specify the name of the assembly in which it is defined. @@ -161,7 +161,7 @@ library UserLib { [!code-csharp[System.Runtime.InteropServices.ICustomMarshaler#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/cs/source.cs#5)] [!code-vb[System.Runtime.InteropServices.ICustomMarshaler#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.interopservices.icustommarshaler/vb/source.vb#5)] - In the previous examples, the first parameter provided to the attribute is the enumeration value `UnmanagedType.CustomMarshaler`. + In the previous examples, the first parameter provided to the attribute is the enumeration value `UnmanagedType.CustomMarshaler`. The second parameter is the field, which provides the assembly-qualified name of the custom marshaler. This name consists of the namespace and class of the custom marshaler (`MarshalType="MyCompany.NewOldMarshaler"`). diff --git a/xml/System.Runtime.InteropServices/IRegistrationServices.xml b/xml/System.Runtime.InteropServices/IRegistrationServices.xml index 2a0f9642db353..5247885fc905f 100644 --- a/xml/System.Runtime.InteropServices/IRegistrationServices.xml +++ b/xml/System.Runtime.InteropServices/IRegistrationServices.xml @@ -140,7 +140,7 @@ ## Remarks `RegisterAssembly` adds the appropriate registry entries for the types in the specified assembly. This method also calls any registration functions found in the assembly. - Use to get an assembly. + Use to get an assembly. ]]> diff --git a/xml/System.Runtime.InteropServices/LayoutKind.xml b/xml/System.Runtime.InteropServices/LayoutKind.xml index effe1793d2012..e5476bed88457 100644 --- a/xml/System.Runtime.InteropServices/LayoutKind.xml +++ b/xml/System.Runtime.InteropServices/LayoutKind.xml @@ -36,7 +36,7 @@ This enumeration is used with . The common language runtime uses the `Auto` layout value by default. To reduce layout-related problems associated with the `Auto` value, C#, Visual Basic, and C++ compilers specify `Sequential` layout for value types. > [!IMPORTANT] -> The field controls the alignment of data fields, and thus affects the layout regardless of the value you specify. By default, the value of is 0, which indicates the default packing size for the current platform. For example, when you use the `Explicit` layout value and specify field alignments on byte boundaries, you must set to 1 to get the desired result. +> The field controls the alignment of data fields, and thus affects the layout regardless of the value you specify. By default, the value of is 0, which indicates the default packing size for the current platform. For example, when you use the `Explicit` layout value and specify field alignments on byte boundaries, you must set to 1 to get the desired result. diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml index 6d61ed18b4184..4bc0e31913a20 100644 --- a/xml/System.Runtime.InteropServices/Marshal.xml +++ b/xml/System.Runtime.InteropServices/Marshal.xml @@ -86,9 +86,9 @@ , you must decrement the reference count by using a method such as . Do not rely on the return value of , as it can sometimes be unstable. + The common language runtime manages the reference count of a COM object for you, making it unnecessary to use this method directly. In rare cases, such as testing a custom marshaler, you might find it necessary to manipulate an object's lifetime manually. After calling , you must decrement the reference count by using a method such as . Do not rely on the return value of , as it can sometimes be unstable. - You can call , , or to obtain an value that represents an [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) interface pointer. You can also use these methods and the method on managed objects to obtain the COM interfaces represented by the managed object's COM callable wrapper. If you are not familiar with the details of this wrapper type, see [COM Callable Wrapper](~/docs/framework/interop/com-callable-wrapper.md). + You can call , , or to obtain an value that represents an [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) interface pointer. You can also use these methods and the method on managed objects to obtain the COM interfaces represented by the managed object's COM callable wrapper. If you are not familiar with the details of this wrapper type, see [COM Callable Wrapper](~/docs/framework/interop/com-callable-wrapper.md). ]]> @@ -132,7 +132,7 @@ is one of two memory allocation API methods in the class. ( is the other.) The initial memory content returned is undefined, and the allocated memory can be larger than the requested number of bytes. This method exposes the COM [CoTaskMemAlloc](http://go.microsoft.com/fwlink/?LinkId=148626) function, which is referred to as the COM task memory allocator. + is one of two memory allocation API methods in the class. ( is the other.) The initial memory content returned is undefined, and the allocated memory can be larger than the requested number of bytes. This method exposes the COM [CoTaskMemAlloc](http://go.microsoft.com/fwlink/?LinkId=148626) function, which is referred to as the COM task memory allocator. ]]> @@ -182,7 +182,7 @@ is one of two memory allocation methods in the class. ( is the other.) This method exposes the Win32 [LocalAlloc](http://go.microsoft.com/fwlink/?LinkId=148628) function from Kernel32.dll. + is one of two memory allocation methods in the class. ( is the other.) This method exposes the Win32 [LocalAlloc](http://go.microsoft.com/fwlink/?LinkId=148628) function from Kernel32.dll. When calls `LocalAlloc`, it passes a `LMEM_FIXED` flag, which causes the allocated memory to be locked in place. Also, the allocated memory is not zero-filled. @@ -243,7 +243,7 @@ is one of two memory allocation methods in the class. ( is the other.) This method exposes the Win32 [LocalAlloc](http://go.microsoft.com/fwlink/?LinkID=148628) function from Kernel32.dll. + is one of two memory allocation methods in the class. ( is the other.) This method exposes the Win32 [LocalAlloc](http://go.microsoft.com/fwlink/?LinkID=148628) function from Kernel32.dll. When calls `LocalAlloc`, it passes a `LMEM_FIXED` flag, which causes the allocated memory to be locked in place. Also, the allocated memory is not zero-filled. @@ -439,7 +439,7 @@ To solve this problem: -1. Use the method to turn off automatic cleanup of RCWs, and the message pumping that occurs, on a per-thread basis. This allows developers to opt out of automatic clean-up, and the corresponding message pumping. +1. Use the method to turn off automatic cleanup of RCWs, and the message pumping that occurs, on a per-thread basis. This allows developers to opt out of automatic clean-up, and the corresponding message pumping. 2. Use the method to notify the runtime to clean up all RCWs that are allocated in the current context. This companion method allows developers to precisely control when the runtime performs cleanup in the current context. @@ -1210,7 +1210,7 @@ method. + Unmanaged, C-style arrays do not contain bounds information, which prevents the `startIndex` and `length` parameters from being validated. Therefore, the unmanaged data that corresponds to the `source` parameter populates the managed array regardless of its usefulness. You must initialize the managed array with the appropriate size before calling the method. ]]> @@ -1516,7 +1516,7 @@ ## Remarks converts one COM class type, typically the generic `__ComObject` type, to another COM class type. The input COM object, represented by parameter `o`, is a [Runtime Callable Wrapper](~/docs/framework/interop/runtime-callable-wrapper.md) (RCW). - Both the `t` and `o` parameters must be classes whose signatures are attributed with . The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool applies this attribute for you when it imports a type library. If you create the RCW manually in source code, you should apply this attribute to the managed signature that represents the original coclass to signify its COM origins. + Both the `t` and `o` parameters must be classes whose signatures are attributed with . The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool applies this attribute for you when it imports a type library. If you create the RCW manually in source code, you should apply this attribute to the managed signature that represents the original coclass to signify its COM origins. Tlbimp.exe imports a COM [coclass](http://msdn.microsoft.com/en-us/333d0904-ffa2-4d25-878d-7422bcd40582) as a managed class and an interface. The coclass interface has the same name as the original coclass, and the managed class has the original coclass name appended with "Class". For example, a coclass called `MyCoclass` becomes a coclass interface called `MyCoclass` and a managed class called `MyCoclassClass`. Since `t` must be a class, not an interface, be sure to specify the managed class (`MyCoclassClass`) and not the coclass interface. @@ -1583,7 +1583,7 @@ ## Remarks converts a COM object of type `T` to the `TWrapper` COM class type. The input COM object, represented by parameter `o`, is a [Runtime Callable Wrapper](~/docs/framework/interop/runtime-callable-wrapper.md) (RCW). - Both the `T` generic type parameter and the `o` parameter must be classes whose signatures are attributed with the attribute. The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool applies this attribute for you when it imports a type library. If you create the RCW manually in source code, you should apply this attribute to the managed signature that represents the original coclass to signify its COM origins. + Both the `T` generic type parameter and the `o` parameter must be classes whose signatures are attributed with the attribute. The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool applies this attribute for you when it imports a type library. If you create the RCW manually in source code, you should apply this attribute to the managed signature that represents the original coclass to signify its COM origins. Tlbimp.exe imports a COM [coclass](http://msdn.microsoft.com/en-us/333d0904-ffa2-4d25-878d-7422bcd40582) as a managed class and an interface. The coclass interface has the same name as the original coclass, and the managed class has the original coclass name appended with "Class". For example, a coclass called `MyCoclass` becomes a coclass interface called `MyCoclass` and a managed class called `MyCoclassClass`. Because`T` must be a class, not an interface, be sure to specify the managed class (`MyCoclassClass`) and not the `coclass` interface. @@ -1646,7 +1646,7 @@ method uses this method to prevent memory leaks when reusing memory occupied by a structure. + You can use this method to free reference-type fields, such as strings, of an unmanaged structure. Unlike its fields, a structure can be a value type or a reference type. Value-type structures that contain value-type fields (all blittable) have no references whose memory must be freed. The method uses this method to prevent memory leaks when reusing memory occupied by a structure. calls the COM [SysFreeString](http://go.microsoft.com/fwlink/?LinkId=148633) function, which, in turn, frees an allocated string. @@ -1700,7 +1700,7 @@ method uses this method to prevent memory leaks when reusing memory occupied by a structure. + You can use this method to free reference type fields, such as strings, of an unmanaged structure. Unlike its fields, a structure can be a value type or a reference type. Value type structures that contain value type fields (all blittable) have no references whose memory must be freed. The method uses this method to prevent memory leaks when reusing memory occupied by a structure. calls the COM [SysFreeString](http://go.microsoft.com/fwlink/?LinkId=148633) function, which, in turn, frees an allocated string. @@ -1799,7 +1799,7 @@ and , you can use this method to deallocate memory. calls the COM [SysFreeString](http://go.microsoft.com/fwlink/?LinkID=148633) function, which frees memory allocated by any of the following unmanaged methods: `SysAllocString`, `SysAllocStringByteLen`, `SysAllocStringLen`, `SysReAllocString`, `SysReAllocStringLen`. You can call unmanaged methods such as these with platform invoke. For details, see [Consuming Unmanaged DLL Functions](~/docs/framework/interop/consuming-unmanaged-dll-functions.md). + Like and , you can use this method to deallocate memory. calls the COM [SysFreeString](http://go.microsoft.com/fwlink/?LinkID=148633) function, which frees memory allocated by any of the following unmanaged methods: `SysAllocString`, `SysAllocStringByteLen`, `SysAllocStringLen`, `SysReAllocString`, `SysReAllocStringLen`. You can call unmanaged methods such as these with platform invoke. For details, see [Consuming Unmanaged DLL Functions](~/docs/framework/interop/consuming-unmanaged-dll-functions.md). ]]> @@ -1894,7 +1894,7 @@ to free any memory from the global heap allocated by , , or any equivalent unmanaged API method. If the `hglobal` parameter is the method does nothing. + You can use to free any memory from the global heap allocated by , , or any equivalent unmanaged API method. If the `hglobal` parameter is the method does nothing. exposes the [LocalFree](http://go.microsoft.com/fwlink/?LinkId=148640) function from Kernel32.DLL, which frees all bytes so that you can no longer use the memory pointed to by `hglobal`. @@ -1947,7 +1947,7 @@ provides the same functionality as the property. + If the type has a GUID in the metadata, it is returned. Otherwise, a GUID is automatically generated. You can use this method to programmatically determine the COM GUID for any managed type, including COM-invisible types. Class interfaces are the only exception because they do not correspond to a managed type. provides the same functionality as the property. ]]> @@ -2079,9 +2079,9 @@ to decrement the reference count once you have finished with the pointer. You must adhere to the rules defined by COM when using raw COM interface pointers. + This method returns an interface pointer that represents the requested interface on the specified object. It is particularly useful if you have an unmanaged method that expects to be passed an interface pointer. Calling an object with this method causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. You must adhere to the rules defined by COM when using raw COM interface pointers. - is useful when calling a method that exposes a COM object parameter as an type, or with custom marshaling. Although less common, you can use this method on a managed object to obtain a pointer to the object's COM callable wrapper. For example, you can use on a managed object that is exported to COM to obtain an interface pointer for . You cannot obtain a pointer to a class interface since a class interface lacks the corresponding type to pass to the second parameter (`t`). Instead, use to invoke the members on the default interface of the COM callable wrapper, which is usually an auto-dispatch class interface. + is useful when calling a method that exposes a COM object parameter as an type, or with custom marshaling. Although less common, you can use this method on a managed object to obtain a pointer to the object's COM callable wrapper. For example, you can use on a managed object that is exported to COM to obtain an interface pointer for . You cannot obtain a pointer to a class interface since a class interface lacks the corresponding type to pass to the second parameter (`t`). Instead, use to invoke the members on the default interface of the COM callable wrapper, which is usually an auto-dispatch class interface. The method overload allows query interface customization by default. To specify whether to apply query interface customization, use the method overload. @@ -2214,9 +2214,9 @@ method to decrement the reference count when you have finished with the pointer. You must adhere to the rules defined by COM when using raw COM interface pointers. + This method returns an interface pointer that represents the `TInterface` interface on the specified object. It is particularly useful if you have an unmanaged method that expects to be passed an interface pointer. Calling an object with this method causes the reference count to increment on the interface pointer before the pointer is returned. Always use the method to decrement the reference count when you have finished with the pointer. You must adhere to the rules defined by COM when using raw COM interface pointers. - is useful when calling a method that exposes a COM object parameter as an type, or with custom marshaling. You can also use this method on a managed object to obtain a pointer to the object's COM callable wrapper, although this is less common. For example, you can use on a managed object that is exported to COM to obtain an interface pointer for . + is useful when calling a method that exposes a COM object parameter as an type, or with custom marshaling. You can also use this method on a managed object to obtain a pointer to the object's COM callable wrapper, although this is less common. For example, you can use on a managed object that is exported to COM to obtain an interface pointer for . The method overload allows query interface customization by default. To specify whether to apply query interface customization, use the method overload. @@ -2315,7 +2315,7 @@ retrieves. adds data to the hash table. You should never have to call either method from your code. + All COM objects wrapped in a [Runtime Callable Wrapper](~/docs/framework/interop/runtime-callable-wrapper.md) have an associated hash table, which retrieves. adds data to the hash table. You should never have to call either method from your code. ]]> @@ -2358,7 +2358,7 @@ provides the opposite functionality of . + The zero-based slot number returned by this method accounts for three [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) and possibly four [IDispatch](http://msdn.microsoft.com/en-us/ebbff4bc-36b2-4861-9efa-ffa45e013eb5) methods, making the value of the first available slot either 3 or 7. provides the opposite functionality of . You can use this method to retrieve slot numbers for members of interfaces that are not visible from COM and for members of private interfaces. The slot numbers returned correspond to the v-table numbers that would be reserved if the type was exposed to COM. COM-invisible members actually occupy a slot in an exposed v-table, even though the COM client cannot use the slot. You cannot use on a class interface by passing from a class. For additional information, see [Introducing the Class Interface](http://msdn.microsoft.com/en-us/733c0dd2-12e5-46e6-8de1-39d5b25df024). @@ -2414,7 +2414,7 @@ ## Remarks In versions 1.0 and 1.1 of the .NET Framework, it was possible to pass a delegate representing a managed method to unmanaged code as a function pointer, allowing the unmanaged code to call the managed method through the function pointer. It was also possible for the unmanaged code to pass that function pointer back to the managed code, and the pointer was resolved properly to the underlying managed method. - In the .NET Framework 2.0 and later versions, you can use the and methods to marshal delegates in both directions. With , `ptr` is imported as a . A can be obtained for a managed delegate by calling and passed as a parameter; it can then be called from inside the unmanaged method. Note that the parameter marshaler can also marshal function pointers to delegates in the .NET Framework 2.0 and later versions. + In the .NET Framework 2.0 and later versions, you can use the and methods to marshal delegates in both directions. With , `ptr` is imported as a . A can be obtained for a managed delegate by calling and passed as a parameter; it can then be called from inside the unmanaged method. Note that the parameter marshaler can also marshal function pointers to delegates in the .NET Framework 2.0 and later versions. The method has the following restrictions: @@ -2524,7 +2524,7 @@ and in conjunction with to pass slots within a specified range. For additional information, see [Introducing the Class Interface](http://msdn.microsoft.com/en-us/733c0dd2-12e5-46e6-8de1-39d5b25df024). + This method returns the zero-based, v-table number for an interface or a class. When used on a class, the slot number returned refers to the class interface for the class. If the class interface is auto-dual, this method always returns -1 to indicate that the dispatch-only interface does not expose a v-table to managed clients. You can use and in conjunction with to pass slots within a specified range. For additional information, see [Introducing the Class Interface](http://msdn.microsoft.com/en-us/733c0dd2-12e5-46e6-8de1-39d5b25df024). ]]> @@ -2924,7 +2924,7 @@ must be `true`. The process for setting this flag depends on the source language used: C# and C++ are `false` by default, but the `Declare` statement in Visual Basic is `true`. + The target function must have had the `setLastError` metadata flag set. For example, the `SetLastError` field of the must be `true`. The process for setting this flag depends on the source language used: C# and C++ are `false` by default, but the `Declare` statement in Visual Basic is `true`. @@ -2967,7 +2967,7 @@ is useful when calling a method that exposes a COM object parameter as an type, or with custom marshaling. Calling an object with this method causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. + In managed code, you seldom work directly with the `IDispatch` interface. However, is useful when calling a method that exposes a COM object parameter as an type, or with custom marshaling. Calling an object with this method causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. You can also use this method on a managed object to obtain an interface pointer to the COM callable wrapper for the object. For additional information, see [COM Callable Wrapper](~/docs/framework/interop/com-callable-wrapper.md). @@ -3037,7 +3037,7 @@ causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. You can apply the to replace standard interop marshaling behavior with this custom marshaler. + This method returns a pointer to an `ITypeInfo` implementation that is based on the original type. Calling an object with causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. You can apply the to replace standard interop marshaling behavior with this custom marshaler. @@ -3096,7 +3096,7 @@ is useful when calling a method that exposes a COM object parameter as an type, or with custom marshaling. Calling an object with this method causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. This method provides the opposite functionality of the method. + In managed code, you seldom work directly with the `IUnknown` interface. However, is useful when calling a method that exposes a COM object parameter as an type, or with custom marshaling. Calling an object with this method causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. This method provides the opposite functionality of the method. You can also use this method on a managed object to obtain an interface pointer to the [COM Callable Wrapper](~/docs/framework/interop/com-callable-wrapper.md) for the object. @@ -3193,7 +3193,7 @@ ## Remarks exposes the Win32 [GetLastError](http://go.microsoft.com/fwlink/?LinkId=148657) function from Kernel32.DLL. This method exists because it is not safe to make a direct platform invoke call to `GetLastError` to obtain this information. If you want to access this error code, you must call instead of writing your own platform invoke definition for `GetLastError` and calling it. The common language runtime can make internal calls to APIs that overwrite the `GetLastError` maintained by the operating system. - You can use this method to obtain error codes only if you apply the to the method signature and set the field to`true`. The process for this varies depending upon the source language used: C# and C++ are `false` by default, but the `Declare` statement in Visual Basic is `true`. + You can use this method to obtain error codes only if you apply the to the method signature and set the field to`true`. The process for this varies depending upon the source language used: C# and C++ are `false` by default, but the `Declare` statement in Visual Basic is `true`. @@ -3278,7 +3278,7 @@ ## Remarks The return value may be a , , or object. The return value depends on the type of managed member that exists in the given COM slot (hence the generalized return type from which all three derive). - The zero-based slot number that is returned by this method accounts for three [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) and possibly four [IDispatch](http://msdn.microsoft.com/en-us/ebbff4bc-36b2-4861-9efa-ffa45e013eb5) methods, making the value of the first available slot either 3 or 7. provides the opposite functionality of . You can use and in conjunction with to pass slots within a specified range. + The zero-based slot number that is returned by this method accounts for three [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) and possibly four [IDispatch](http://msdn.microsoft.com/en-us/ebbff4bc-36b2-4861-9efa-ffa45e013eb5) methods, making the value of the first available slot either 3 or 7. provides the opposite functionality of . You can use and in conjunction with to pass slots within a specified range. The `memberType` parameter is important only on return. It contains the type of the COM member (a regular method or a property accessor) that corresponds to the returned object. @@ -3432,7 +3432,7 @@ - Register the containing assembly with the [Regasm.exe (Assembly Registration Tool)](~/docs/framework/tools/regasm-exe-assembly-registration-tool.md). - Alternatively, you can avoid these requirements and still get an object that is wrapped with a specific managed class type by using the method. + Alternatively, you can avoid these requirements and still get an object that is wrapped with a specific managed class type by using the method. ]]> @@ -3478,7 +3478,7 @@ ## Remarks returns a managed object that corresponds to a raw pointer to an unmanaged VARIANT type. The interopmarshaler performs the identical transformation when exposing a VARIANT type to managed code. - provides the opposite functionality of . + provides the opposite functionality of . When the VARIANT type is VT_ERROR, returns an object of type `Int32` instead of `UInt32`. @@ -3688,7 +3688,7 @@ and in conjunction with to pass slots within a specified range. For additional information, see [Introducing the Class Interface](http://msdn.microsoft.com/en-us/733c0dd2-12e5-46e6-8de1-39d5b25df024). + This method returns the zero-based v-table number for an interface or a class. When used on a class, the slot number that is returned refers to the class interface for the class. If the class interface is auto-dispatch, this method always returns -1 to indicate that the dispatch-only interface does not expose a v-table to managed clients. You can use and in conjunction with to pass slots within a specified range. For additional information, see [Introducing the Class Interface](http://msdn.microsoft.com/en-us/733c0dd2-12e5-46e6-8de1-39d5b25df024). ]]> @@ -3803,7 +3803,7 @@ returns a instance that is based on the original type. You can apply the to replace standard interop marshaling behavior with this custom marshaler. The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool uses the custom marshaler to translate `ITypeInfo` parameters to parameters. However, if you obtain an `ITypeInfo` interface by some means other than Tlbimp.exe, you can use to manually perform the same translation. + returns a instance that is based on the original type. You can apply the to replace standard interop marshaling behavior with this custom marshaler. The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool uses the custom marshaler to translate `ITypeInfo` parameters to parameters. However, if you obtain an `ITypeInfo` interface by some means other than Tlbimp.exe, you can use to manually perform the same translation. ]]> @@ -3884,7 +3884,7 @@ method and passing -1 for its first parameter. + You can also retrieve the name of the type represented by an `ITypeInfo` by calling the method and passing -1 for its first parameter. ]]> @@ -3921,7 +3921,7 @@ method and passing -1 for its first parameter. + You can also retrieve the name of the type represented by an `ITypeInfo` object by calling the method and passing -1 for its first parameter. ]]> @@ -3952,7 +3952,7 @@ extracts the LIBID directly from an existing type library. This action differs from that of the method, which calculates what the LIBID should be based on the current assembly. + extracts the LIBID directly from an existing type library. This action differs from that of the method, which calculates what the LIBID should be based on the current assembly. For more information about library identifiers, see [Exported Assembly Conversion](http://msdn.microsoft.com/en-us/3fffd8db-240f-4fde-a558-a5bcc01e1a86). @@ -3990,7 +3990,7 @@ extracts the LIBID directly from an existing type library. This action differs from that of the method, which calculates what the LIBID should be based on the current assembly. + extracts the LIBID directly from an existing type library. This action differs from that of the method, which calculates what the LIBID should be based on the current assembly. For more information about library identifiers, see [Exported Assembly Conversion](http://msdn.microsoft.com/en-us/3fffd8db-240f-4fde-a558-a5bcc01e1a86). @@ -4023,7 +4023,7 @@ at the assembly level, or it can be generated automatically. The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool calculates a LIBID value based on the identity of the assembly. returns the LIBID that is associated with the , if the attribute is applied. Otherwise, returns the calculated value. Alternatively, you can use the method to extract the actual LIBID from an existing type library. + When assemblies are exported to type libraries, the type library is assigned a LIBID. You can set the LIBID explicitly by applying the at the assembly level, or it can be generated automatically. The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool calculates a LIBID value based on the identity of the assembly. returns the LIBID that is associated with the , if the attribute is applied. Otherwise, returns the calculated value. Alternatively, you can use the method to extract the actual LIBID from an existing type library. See the [Exported Assembly Conversion](http://msdn.microsoft.com/en-us/3fffd8db-240f-4fde-a558-a5bcc01e1a86) topic for more information about library identifiers. @@ -4113,7 +4113,7 @@ ## Remarks The name returned by this method is the identifier used with the library statement, such as ADODB for the Microsoft ADO type library. The name is not a file name. - You can also retrieve the type library name by calling the method and passing -1 for its first parameter. + You can also retrieve the type library name by calling the method and passing -1 for its first parameter. ]]> @@ -4152,7 +4152,7 @@ ## Remarks The name returned by this method is the identifier used with the library statement, such as ADODB for the Microsoft ADO type library. The name is not a file name. - You can also retrieve the type library name by calling the method and passing -1 for its first parameter. + You can also retrieve the type library name by calling the method and passing -1 for its first parameter. ]]> @@ -4319,9 +4319,9 @@ returns `true` if the class type of the instance is attributed with or if it derives directly or indirectly from a class attributed with . The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool applies this attribute for you when it imports a type library. + returns `true` if the class type of the instance is attributed with or if it derives directly or indirectly from a class attributed with . The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) tool applies this attribute for you when it imports a type library. - Two other methods also determine whether a specified object represents a COM object, but the requirements for returning `true` differ from this method's requirements. returns `true` if the class (or interface) is attributed with directly; it does not return `true` for derived types. returns `true` if the type is attributed with or derives from a type with the same GUID. + Two other methods also determine whether a specified object represents a COM object, but the requirements for returning `true` differ from this method's requirements. returns `true` if the class (or interface) is attributed with directly; it does not return `true` for derived types. returns `true` if the type is attributed with or derives from a type with the same GUID. ]]> @@ -4354,7 +4354,7 @@ enables you to check for COM visibility in one step. Types that are not visible cannot be used from COM. A type is visible if it is `public` and not hidden with the . + enables you to check for COM visibility in one step. Types that are not visible cannot be used from COM. A type is visible if it is `public` and not hidden with the . ]]> @@ -4434,7 +4434,7 @@ provides the offset in terms of the unmanaged structure layout, which does not necessarily correspond to the offset of the managed structure layout. Marshaling the structure can transform the layout and alter the offset. The `t` parameter can be a value type or a formatted reference type (with either a sequential or explicit layout). You can obtain the size of the entire layout by using the method. For additional information, see [Default Marshaling for Value Types](http://msdn.microsoft.com/en-us/4d9a876c-e05a-40ba-bd85-bd22877f984a). + provides the offset in terms of the unmanaged structure layout, which does not necessarily correspond to the offset of the managed structure layout. Marshaling the structure can transform the layout and alter the offset. The `t` parameter can be a value type or a formatted reference type (with either a sequential or explicit layout). You can obtain the size of the entire layout by using the method. For additional information, see [Default Marshaling for Value Types](http://msdn.microsoft.com/en-us/4d9a876c-e05a-40ba-bd85-bd22877f984a). > [!NOTE] > Beginning with the .NET Framework version 2.0, may expose private fields. @@ -4537,7 +4537,7 @@ - Locating the entry point in the process. - Calling on a method outside of platform invoke has no effect. To execute setup tasks on all platform invoke methods in a type, use . + Calling on a method outside of platform invoke has no effect. To execute setup tasks on all platform invoke methods in a type, use . ]]> @@ -4577,7 +4577,7 @@ method invokes on every method for a given type. executes one-time method setup tasks without calling each method. You can use only for platform invoke calls. + The method invokes on every method for a given type. executes one-time method setup tasks without calling each method. You can use only for platform invoke calls. ]]> @@ -4622,7 +4622,7 @@ is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the and methods. + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the and methods. @@ -4675,7 +4675,7 @@ is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the and methods. + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the and methods. @@ -4729,7 +4729,7 @@ ## Remarks If the current platform is Unicode, each ANSI character is widened to a Unicode character and this method calls . Otherwise, this method calls . - is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. provides the opposite functionality of the and methods. + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. provides the opposite functionality of the and methods. ]]> @@ -4776,7 +4776,7 @@ ## Remarks On Unicode platforms, this method calls ; on ANSI platforms, it calls . No transformations are done before these methods are called. - is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. provides the opposite functionality of and . + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. provides the opposite functionality of and . ]]> @@ -4824,7 +4824,7 @@ ## Remarks Call this method only on strings that were allocated with the unmanaged [SysAllocString](https://msdn.microsoft.com/library/ms221458\(v=vs.85\).aspx) and [SysAllocStringLen](https://msdn.microsoft.com/library/ms221639\(v=vs.85\).aspx) functions. - is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the method. + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the method. ]]> @@ -4870,7 +4870,7 @@ is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the and methods. + is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the and methods. ]]> @@ -4916,7 +4916,7 @@ is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the and methods. + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method creates a copy of the unmanaged string's contents, you must free the original string as appropriate. This method provides the opposite functionality of the and methods. ]]> @@ -5014,7 +5014,7 @@ is often necessary in COM interop and platform invoke when structure parameters are represented as an value. You cannot use this overload method with value types. + is often necessary in COM interop and platform invoke when structure parameters are represented as an value. You cannot use this overload method with value types. ]]> @@ -5070,7 +5070,7 @@ is often necessary in COM interop and platform invoke when structure parameters are represented as an value. You can pass a value type to this overload method. In this case, the returned object is a boxed instance. + is often necessary in COM interop and platform invoke when structure parameters are represented as an value. You can pass a value type to this overload method. In this case, the returned object is a boxed instance. @@ -5083,7 +5083,7 @@ The following example demonstrates how to marshal an unmanaged block of memory to a managed structure using the method. > [!IMPORTANT] -> This code assumes 32-bit compilation. Before using a 64-bit compiler, replace with . +> This code assumes 32-bit compilation. Before using a 64-bit compiler, replace with . [!code-cpp[PtrToStructure#1](~/samples/snippets/cpp/VS_Snippets_CLR/PtrToStructure/CPP/pts.cpp#1)] [!code-csharp[PtrToStructure#1](~/samples/snippets/csharp/VS_Snippets_CLR/PtrToStructure/CS/pts.cs#1)] @@ -5143,7 +5143,7 @@ is often necessary in COM interop and platform invoke when structure parameters are represented as values. You can pass a value type to this method overload. + is often necessary in COM interop and platform invoke when structure parameters are represented as values. You can pass a value type to this method overload. ]]> @@ -5244,7 +5244,7 @@ method exposes the [IUnknown::QueryInterface](http://go.microsoft.com/fwlink/?LinkID=144867) method of a COM object, which attempts to obtain a specific interface pointer. Using `QueryInterface` on a COM object is the same as performing a cast operation in managed code. Calling an object with this method causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. To obtain an value that represents a [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) interface pointer, you can call , , or . + The method exposes the [IUnknown::QueryInterface](http://go.microsoft.com/fwlink/?LinkID=144867) method of a COM object, which attempts to obtain a specific interface pointer. Using `QueryInterface` on a COM object is the same as performing a cast operation in managed code. Calling an object with this method causes the reference count to increment on the interface pointer before the pointer is returned. Always use to decrement the reference count once you have finished with the pointer. To obtain an value that represents a [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) interface pointer, you can call , , or . ]]> @@ -5288,7 +5288,7 @@ has an implied offset of 0. This method enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + has an implied offset of 0. This method enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5358,7 +5358,7 @@ enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5424,7 +5424,7 @@ enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5473,7 +5473,7 @@ has an implied offset of 0. This method enables direct interaction with an unmanaged C-style `Int16` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + has an implied offset of 0. This method enables direct interaction with an unmanaged C-style `Int16` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5543,7 +5543,7 @@ enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5609,7 +5609,7 @@ enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5663,7 +5663,7 @@ has an implied offset of 0. This method enables direct interaction with an unmanaged C-style `Int32` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + has an implied offset of 0. This method enables direct interaction with an unmanaged C-style `Int32` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5738,7 +5738,7 @@ enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5807,7 +5807,7 @@ enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5861,7 +5861,7 @@ has an implied offset of 0. This method enables direct interaction with an unmanaged C-style `Int64` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + has an implied offset of 0. This method enables direct interaction with an unmanaged C-style `Int64` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -5931,7 +5931,7 @@ enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -6000,7 +6000,7 @@ enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -6054,7 +6054,7 @@ has an implied offset of 0. This method enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + has an implied offset of 0. This method enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -6125,7 +6125,7 @@ enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -6187,7 +6187,7 @@ enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. + enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before reading its element values. Reading from unaligned memory locations is supported. @@ -6285,7 +6285,7 @@ is one of two memory reallocation API methods in the class. ( is the other.) + is one of two memory reallocation API methods in the class. ( is the other.) This method exposes the Win32 [GlobalReAlloc](http://go.microsoft.com/fwlink/?LinkId=148780) function from Kernel32.dll. The returned pointer can differ from the original. If it is different, the contents of the original memory block have been copied to the new block, and the original memory block has been freed. @@ -6337,9 +6337,9 @@ should call . Calling after the reference count has reached zero causes undefined behavior. + The common language runtime manages the reference count of a COM object for you, making it unnecessary to use this method directly. Use this value only for testing purposes. In rare cases, such as testing a custom marshaler, you might find it necessary to manipulate an object's lifetime manually. Only programs that call should call . Calling after the reference count has reached zero causes undefined behavior. - You can call , , or to obtain an value that represents a [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) interface pointer to release. You can also use these methods and the method on managed objects to release the COM interfaces represented by the managed object's [COM Callable Wrapper](~/docs/framework/interop/com-callable-wrapper.md). + You can call , , or to obtain an value that represents a [IUnknown](http://go.microsoft.com/fwlink/?LinkId=148003) interface pointer to release. You can also use these methods and the method on managed objects to release the COM interfaces represented by the managed object's [COM Callable Wrapper](~/docs/framework/interop/com-callable-wrapper.md). @@ -6395,7 +6395,7 @@ Every time a COM interface pointer enters the common language runtime (CLR), it is wrapped in an RCW. - The RCW has a reference count that is incremented every time a COM interface pointer is mapped to it. The method decrements the reference count of an RCW. When the reference count reaches zero, the runtime releases all its references on the unmanaged COM object, and throws a if you attempt to use the object further. If the same COM interface is passed more than one time from unmanaged to managed code, the reference count on the wrapper is incremented every time, and calling returns the number of remaining references. + The RCW has a reference count that is incremented every time a COM interface pointer is mapped to it. The method decrements the reference count of an RCW. When the reference count reaches zero, the runtime releases all its references on the unmanaged COM object, and throws a if you attempt to use the object further. If the same COM interface is passed more than one time from unmanaged to managed code, the reference count on the wrapper is incremented every time, and calling returns the number of remaining references. This method enables you to force an RCW reference count release so that it occurs precisely when you want it to. However, improper use of may cause your application to fail, or may cause an access violation. @@ -6731,7 +6731,7 @@ adds data. retrieves data from the hash table. You should never have to call either method from your code. + All COM objects wrapped in a [Runtime Callable Wrapper](~/docs/framework/interop/runtime-callable-wrapper.md) (RCW) have an associated hash table, to which adds data. retrieves data from the hash table. You should never have to call either method from your code. ]]> @@ -7004,7 +7004,7 @@ is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the `BSTR` when finished by calling . This method provides the opposite functionality of . + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the `BSTR` when finished by calling . This method provides the opposite functionality of . ]]> @@ -7050,7 +7050,7 @@ is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . The characters of the string are copied as ANSI characters. + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . The characters of the string are copied as ANSI characters. ]]> @@ -7091,7 +7091,7 @@ is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . + is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . The characters of the string are copied as either ANSI or Unicode characters, depending on the operating system where the code is executing. On Windows 98, the characters are copied as ANSI characters. On Windows NT 4.0, Windows 2000, Windows XP, and the Windows Server 2003 family, the characters are copied as Unicode characters. @@ -7139,7 +7139,7 @@ is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . The characters of the string are copied as Unicode characters. + is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . The characters of the string are copied as Unicode characters. ]]> @@ -7208,7 +7208,7 @@ is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . provides the opposite functionality of . + is useful for custom marshaling or when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . provides the opposite functionality of . This method copies embedded null characters, and includes a terminating null character. @@ -7259,7 +7259,7 @@ is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . + is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . This method copies embedded null characters, and includes a terminating null character. @@ -7313,7 +7313,7 @@ is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . + is useful for custom marshaling or for use when mixing managed and unmanaged code. Because this method allocates the unmanaged memory required for a string, always free the memory by calling . This method provides the opposite functionality of . This method copies embedded null characters, and includes a terminating null character. @@ -7375,9 +7375,9 @@ ## Remarks If `structure` is a value type, it can be boxed or unboxed. If it is boxed, it is unboxed before copying. - A formatted class is a reference type whose layout is specified by the attribute, as either or . + A formatted class is a reference type whose layout is specified by the attribute, as either or . - copies the contents of `structure` to the pre-allocated block of memory that the `ptr` parameter points to. If `structure` contains reference types that marshal to COM interface pointers (interfaces, classes without layout, and ), the managed objects are kept alive with reference counts. All other reference types (for example, strings and arrays) are marshaled to copies. To release these managed or unmanaged objects, you must call the method before you free the memory block. + copies the contents of `structure` to the pre-allocated block of memory that the `ptr` parameter points to. If `structure` contains reference types that marshal to COM interface pointers (interfaces, classes without layout, and ), the managed objects are kept alive with reference counts. All other reference types (for example, strings and arrays) are marshaled to copies. To release these managed or unmanaged objects, you must call the method before you free the memory block. If you use the method to copy a different instance to the memory block at a later time, specify `true` for `fDeleteOld` to remove reference counts for reference types in the previous instance. Otherwise, the managed reference typesand unmanaged copies are effectively leaked. @@ -7393,7 +7393,7 @@ 3. If the object contains reference types, you must call the method before you free the memory block. > [!NOTE] -> To pin an existing structure instead of copying it, use the type to create a pinned handle for the structure. For details on how to pin, see [Copying and Pinning](~/docs/framework/interop/copying-and-pinning.md). +> To pin an existing structure instead of copying it, use the type to create a pinned handle for the structure. For details on how to pin, see [Copying and Pinning](~/docs/framework/interop/copying-and-pinning.md). @@ -7460,9 +7460,9 @@ attribute, as either or . + A formatted class is a reference type whose layout is specified by the attribute, as either or . - copies the contents of `structure` to the pre-allocated block of memory that the `ptr` parameter points to. If `structure` contains reference types that marshal to COM interface pointers (interfaces, classes without layout, and ), the managed objects are kept alive with reference counts. All other reference types (for example, strings and arrays) are marshaled to copies. To release these managed or unmanaged objects, you must call the method before you free the memory block. + copies the contents of `structure` to the pre-allocated block of memory that the `ptr` parameter points to. If `structure` contains reference types that marshal to COM interface pointers (interfaces, classes without layout, and ), the managed objects are kept alive with reference counts. All other reference types (for example, strings and arrays) are marshaled to copies. To release these managed or unmanaged objects, you must call the method before you free the memory block. If you use the method to copy a different instance to the memory block at a later time, specify `true` for `fDeleteOld` to remove reference counts for reference types in the previous instance. Otherwise, the managed reference types and unmanaged copies are effectively leaked. @@ -7478,7 +7478,7 @@ 3. If the object contains reference types, you must call the method before you free the memory block. > [!NOTE] -> To pin an existing structure instead of copying it, use the type to create a pinned handle for the structure. For details on how to pin, see [Copying and Pinning](~/docs/framework/interop/copying-and-pinning.md). +> To pin an existing structure instead of copying it, use the type to create a pinned handle for the structure. For details on how to pin, see [Copying and Pinning](~/docs/framework/interop/copying-and-pinning.md). ]]> @@ -7671,7 +7671,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) Note that the method returns an exception based on the [IErrorInfo](https://msdn.microsoft.com/library/ms221233\(v=vs.85\).aspx) interface of the current thread if one is set. When this happens, the `errorCode` parameter is ignored. - Some failure HRESULTs map to defined exceptions, whereas others do not. If the HRESULT maps to a defined exception, creates an instance of the exception and throws it. Otherwise, it creates an instance of , initializes the error code field with the HRESULT, and throws that exception. The `errorInfo` parameter is used to retrieve extra information regarding the error. + Some failure HRESULTs map to defined exceptions, whereas others do not. If the HRESULT maps to a defined exception, creates an instance of the exception and throws it. Otherwise, it creates an instance of , initializes the error code field with the HRESULT, and throws that exception. The `errorInfo` parameter is used to retrieve extra information regarding the error. For the mapping from each HRESULT to its comparable exception class in the .NET Framework, see [How to: Map HRESULTs and Exceptions](~/docs/framework/interop/how-to-map-hresults-and-exceptions.md). @@ -7815,7 +7815,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. @@ -7880,7 +7880,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. @@ -7941,7 +7941,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. ]]> @@ -7989,7 +7989,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8054,7 +8054,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8121,7 +8121,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8179,7 +8179,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8237,7 +8237,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8294,7 +8294,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 16-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8344,7 +8344,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8411,7 +8411,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8474,7 +8474,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 32-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8524,7 +8524,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8591,7 +8591,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8654,7 +8654,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged 64-bit signed array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8704,7 +8704,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8773,7 +8773,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) ## Remarks This method writes a 32 bit integer on 32 bit systems, and a 64 bit integer on 64 bit systems. - enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged C-style `IntPtr` array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. @@ -8831,7 +8831,7 @@ public static void ThrowExceptionForHR(interrorCode,IntPtrerrorInfo) enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. + enables direct interaction with an unmanaged C-style byte array, eliminating the expense of copying an entire unmanaged array (using ) to a separate managed array before setting its element values. Writing to unaligned memory locations is supported. diff --git a/xml/System.Runtime.InteropServices/MarshalAsAttribute.xml b/xml/System.Runtime.InteropServices/MarshalAsAttribute.xml index 6a39c6f2cc619..b77a6021bde98 100644 --- a/xml/System.Runtime.InteropServices/MarshalAsAttribute.xml +++ b/xml/System.Runtime.InteropServices/MarshalAsAttribute.xml @@ -183,7 +183,7 @@ enumeration to specify the type of the array's elements. If a type is not specified, the default unmanaged type corresponding to the managed array's element type is used. For example, the `ArraySubType` for a `LPWStr` array in COM is . For additional information, see [Default Marshaling for Arrays](~/docs/framework/interop/default-marshaling-for-arrays.md). + You can set this parameter to a value from the enumeration to specify the type of the array's elements. If a type is not specified, the default unmanaged type corresponding to the managed array's element type is used. For example, the `ArraySubType` for a `LPWStr` array in COM is . For additional information, see [Default Marshaling for Arrays](~/docs/framework/interop/default-marshaling-for-arrays.md). ]]> @@ -297,7 +297,7 @@ or field specify a custom marshaler type for the attributed parameter, field, or return type. The field enables you to specify a string representing the fully qualified name of a custom marshaler. It is useful for late-bound references, but is less preferred than for specifying a custom marshaler. For additional information about creating and using custom marshalers, see [Custom Marshaling](http://msdn.microsoft.com/en-us/49f9ac47-1619-4d6e-9da6-bf06bba12079). + You can use either the or field specify a custom marshaler type for the attributed parameter, field, or return type. The field enables you to specify a string representing the fully qualified name of a custom marshaler. It is useful for late-bound references, but is less preferred than for specifying a custom marshaler. For additional information about creating and using custom marshalers, see [Custom Marshaling](http://msdn.microsoft.com/en-us/49f9ac47-1619-4d6e-9da6-bf06bba12079). ]]> @@ -388,7 +388,7 @@ enumeration to specify the type of the safe array's elements. If a type is not specified, the managed element type's default type (if passed as a VARIANT) is used. For example, the `SafeArraySubType` for an `int` array in COM is . For additional information, see [Default Marshaling for Arrays](~/docs/framework/interop/default-marshaling-for-arrays.md). + You can set this field to a value from the enumeration to specify the type of the safe array's elements. If a type is not specified, the managed element type's default type (if passed as a VARIANT) is used. For example, the `SafeArraySubType` for an `int` array in COM is . For additional information, see [Default Marshaling for Arrays](~/docs/framework/interop/default-marshaling-for-arrays.md). ]]> @@ -426,7 +426,7 @@ is either , , or . For additional information, see [Default Marshaling for Arrays](~/docs/framework/interop/default-marshaling-for-arrays.md). + Initialize this field with your custom type to enable the elements of the `SAFEARRAY` to be marshaled successfully. This field is only needed when the is either , , or . For additional information, see [Default Marshaling for Arrays](~/docs/framework/interop/default-marshaling-for-arrays.md). ]]> @@ -464,7 +464,7 @@ and members of the enumeration. Because the compressed format of the metadata is limited to 0x1FFFFFFF, the range of allowed values for are (>= 0 and <= 0x1FFFFFFF). + This field is required for the and members of the enumeration. Because the compressed format of the metadata is limited to 0x1FFFFFFF, the range of allowed values for are (>= 0 and <= 0x1FFFFFFF). For additional information, see [Default Marshaling for Arrays](~/docs/framework/interop/default-marshaling-for-arrays.md). @@ -516,7 +516,7 @@ The zero-based index of the array size parameter is defined by using the field. - If you specify both and with a field, the sum of the fields' values produces a size total. + If you specify both and with a field, the sum of the fields' values produces a size total. For more information, see [Default Marshaling for Arrays](~/docs/framework/interop/default-marshaling-for-arrays.md). diff --git a/xml/System.Runtime.InteropServices/PrimaryInteropAssemblyAttribute.xml b/xml/System.Runtime.InteropServices/PrimaryInteropAssemblyAttribute.xml index 4de1816501cbc..29a96a115b2de 100644 --- a/xml/System.Runtime.InteropServices/PrimaryInteropAssemblyAttribute.xml +++ b/xml/System.Runtime.InteropServices/PrimaryInteropAssemblyAttribute.xml @@ -43,7 +43,7 @@ - Apply the at design time. - To specify a primary interop assembly in managed source code, you must apply the and to the assembly at design time. The on the primary interop assembly identifies the LIBID of the type library and the identifies the version of the particular type library for which this assembly is the primary interop assembly. The can appear multiple times if the assembly is the primary interop assembly for multiple versions of the same type library. + To specify a primary interop assembly in managed source code, you must apply the and to the assembly at design time. The on the primary interop assembly identifies the LIBID of the type library and the identifies the version of the particular type library for which this assembly is the primary interop assembly. The can appear multiple times if the assembly is the primary interop assembly for multiple versions of the same type library. When using the types defined in a type library, always reference the primary interop assembly for that type library, rather than reimporting or redefining the types themselves. For guidelines and procedures on how to produce or use primary interop assemblies, see [Primary Interop Assemblies](http://msdn.microsoft.com/en-us/b977a8be-59a0-40a0-a806-b11ffba5c080). For a detailed description of the type library importing process, see [Type Library to Assembly Conversion Summary](http://msdn.microsoft.com/en-us/bf3f90c5-4770-4ab8-895c-3ba1055cc958). diff --git a/xml/System.Runtime.InteropServices/RegistrationServices.xml b/xml/System.Runtime.InteropServices/RegistrationServices.xml index 024af92a9198d..0e6000f3c4273 100644 --- a/xml/System.Runtime.InteropServices/RegistrationServices.xml +++ b/xml/System.Runtime.InteropServices/RegistrationServices.xml @@ -158,7 +158,7 @@ ## Remarks `RegisterAssembly` adds the appropriate registry entries for the types in the specified assembly. This method also calls any registration functions found in the assembly. - Use to get an assembly. + Use to get an assembly. ]]> diff --git a/xml/System.Runtime.InteropServices/SafeBuffer.xml b/xml/System.Runtime.InteropServices/SafeBuffer.xml index b9dba55fb8fb5..93f89bc5c61c2 100644 --- a/xml/System.Runtime.InteropServices/SafeBuffer.xml +++ b/xml/System.Runtime.InteropServices/SafeBuffer.xml @@ -31,11 +31,11 @@ method before you use any instance of . To avoid races when you store an instance of a object in a static variable, you should use one of the following approaches: + You must call the method before you use any instance of . To avoid races when you store an instance of a object in a static variable, you should use one of the following approaches: - Create a lock when publishing the . -- Create a local variable, initialize the , and then assign the to the static variable, for example, by using the method. +- Create a local variable, initialize the , and then assign the to the static variable, for example, by using the method. > [!NOTE] > Assignments in a static class constructor are implicitly locked. @@ -123,9 +123,9 @@ returns, you should perform bounds checking by verifying that the `pointer` parameter is `null`. If it is not `null`, you must call the method in a constrained execution region (CER). + When returns, you should perform bounds checking by verifying that the `pointer` parameter is `null`. If it is not `null`, you must call the method in a constrained execution region (CER). - calls the method and exposes the pointer. Unlike the method, it does not change the current position of the pointer. + calls the method and exposes the pointer. Unlike the method, it does not change the current position of the pointer. The following exampledemonstrates how to use the method: diff --git a/xml/System.Runtime.InteropServices/SafeHandle.xml b/xml/System.Runtime.InteropServices/SafeHandle.xml index 168543aca687f..a0785a90ed6eb 100644 --- a/xml/System.Runtime.InteropServices/SafeHandle.xml +++ b/xml/System.Runtime.InteropServices/SafeHandle.xml @@ -56,7 +56,7 @@ ## Why SafeHandle? Before the .NET Framework version 2.0, all operating system handles could only be encapsulated in the managed wrapper object. While this was a convenient way to interoperate with native code, handles could be leaked by asynchronous exceptions, such as a thread aborting unexpectedly or a stack overflow. These asynchronous exceptions are an obstacle to cleaning up operating system resources, and they can occur almost anywhere in your app. - Although overrides to the method allow cleanup of unmanaged resources when an object is being garbage collected, in some circumstances, finalizable objects can be reclaimed by garbage collection while executing a method within a platform invoke call. If a finalizer frees the handle passed to that platform invoke call, it could lead to handle corruption. The handle could also be reclaimed while your method is blocked during a platform invoke call, such as while reading a file. + Although overrides to the method allow cleanup of unmanaged resources when an object is being garbage collected, in some circumstances, finalizable objects can be reclaimed by garbage collection while executing a method within a platform invoke call. If a finalizer frees the handle passed to that platform invoke call, it could lead to handle corruption. The handle could also be reclaimed while your method is blocked during a platform invoke call, such as while reading a file. More critically, because Windows aggressively recycles handles, a handle could be recycled and point to another resource that might contain sensitive data. This is known as a recycle attack and can potentially corrupt data and be a security threat. @@ -64,7 +64,7 @@ ## What SafeHandle does The class simplifies several of these object lifetime issues, and is integrated with platform invoke so that operating system resources are not leaked. The class resolves object lifetime issues by assigning and releasing handles without interruption. It contains a critical finalizer that ensures that the handle is closed and is guaranteed to run during unexpected unloads, even in cases when the platform invoke call is assumed to be in a corrupted state. - Because inherits from , all the noncritical finalizers are called before any of the critical finalizers. The finalizers are called on objects that are no longer live during the same garbage collection pass. For example, a object can run a normal finalizer to flush out existing buffered data without the risk of the handle being leaked or recycled. This very weak ordering between critical and noncritical finalizers is not intended for general use. It exists primarily to assist in the migration of existing libraries by allowing those libraries to use without altering their semantics. Additionally, the critical finalizer and anything it calls, such as the method, must be in a constrained execution region. This imposes constraints on what code can be written within the finalizer's call graph. + Because inherits from , all the noncritical finalizers are called before any of the critical finalizers. The finalizers are called on objects that are no longer live during the same garbage collection pass. For example, a object can run a normal finalizer to flush out existing buffered data without the risk of the handle being leaked or recycled. This very weak ordering between critical and noncritical finalizers is not intended for general use. It exists primarily to assist in the migration of existing libraries by allowing those libraries to use without altering their semantics. Additionally, the critical finalizer and anything it calls, such as the method, must be in a constrained execution region. This imposes constraints on what code can be written within the finalizer's call graph. Platform invoke operations automatically increment the reference count of handles encapsulated by a and decrement them upon completion. This ensures that the handle will not be recycled or closed unexpectedly. diff --git a/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml b/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml index 35cde454e9c7b..4940e92bf39b9 100644 --- a/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml +++ b/xml/System.Runtime.InteropServices/StructLayoutAttribute.xml @@ -39,14 +39,14 @@ ## Remarks You can apply this attribute to classes or structures. - The common language runtime controls the physical layout of the data fields of a class or structure in managed memory. However, if you want to pass the type to unmanaged code, you can use the attribute to control the unmanaged layout of the type. Use the attribute with to force the members to be laid out sequentially in the order they appear. For , controls both the layout in managed memory and the layout in unmanaged memory. For non-blittable types, it controls the layout when the class or structure is marshaled to unmanaged code, but does not control the layout in managed memory. Use the attribute with to control the precise position of each data member. This affects both managed and unmanaged layout, for both blittable and non-blittable types. Using requires that you use the attribute to indicate the position of each field within the type. + The common language runtime controls the physical layout of the data fields of a class or structure in managed memory. However, if you want to pass the type to unmanaged code, you can use the attribute to control the unmanaged layout of the type. Use the attribute with to force the members to be laid out sequentially in the order they appear. For , controls both the layout in managed memory and the layout in unmanaged memory. For non-blittable types, it controls the layout when the class or structure is marshaled to unmanaged code, but does not control the layout in managed memory. Use the attribute with to control the precise position of each data member. This affects both managed and unmanaged layout, for both blittable and non-blittable types. Using requires that you use the attribute to indicate the position of each field within the type. - C#, Visual Basic, and C++ compilers apply the layout value to structures by default. For classes, you must apply the value explicitly. The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) also applies the attribute; it always applies the value when it imports a type library. + C#, Visual Basic, and C++ compilers apply the layout value to structures by default. For classes, you must apply the value explicitly. The [Tlbimp.exe (Type Library Importer)](~/docs/framework/tools/tlbimp-exe-type-library-importer.md) also applies the attribute; it always applies the value when it imports a type library. ## Examples - The following example demonstrates a managed declaration of the `GetSystemTime` function and defines `MySystemTime` class with layout. `GetSystemTime` gets the system time and prints to the console. + The following example demonstrates a managed declaration of the `GetSystemTime` function and defines `MySystemTime` class with layout. `GetSystemTime` gets the system time and prints to the console. [!code-cpp[StructLayoutAttribute#1](~/samples/snippets/cpp/VS_Snippets_CLR/StructLayoutAttribute/CPP/structlayoutattribute.cpp#1)] [!code-csharp[StructLayoutAttribute#1](~/samples/snippets/csharp/VS_Snippets_CLR/StructLayoutAttribute/CS/structlayoutattribute.cs#1)] @@ -159,7 +159,7 @@ , all string arguments are converted to Unicode characters (`LPWSTR`) before they are passed to the unmanaged implementation. If the field is set to , the strings are converted to ANSI strings (`LPSTR`). If the `CharSet` field is set to , the conversion is platform-dependent (ANSI on Windows 98 and Windows Me, and Unicode on later versions). + If the `CharSet` field is set to , all string arguments are converted to Unicode characters (`LPWSTR`) before they are passed to the unmanaged implementation. If the field is set to , the strings are converted to ANSI strings (`LPSTR`). If the `CharSet` field is set to , the conversion is platform-dependent (ANSI on Windows 98 and Windows Me, and Unicode on later versions). ]]> @@ -196,7 +196,7 @@ field controls the alignment of a type's fields in memory. It affects both and . By default, the value is 0, indicating the default packing size for the current platform. The value of must be 0, 1, 2, 4, 8, 16, 32, 64, or 128: + The field controls the alignment of a type's fields in memory. It affects both and . By default, the value is 0, indicating the default packing size for the current platform. The value of must be 0, 1, 2, 4, 8, 16, 32, 64, or 128: The fields of a type instance are aligned by using the following rules: diff --git a/xml/System.Runtime.InteropServices/TypeIdentifierAttribute.xml b/xml/System.Runtime.InteropServices/TypeIdentifierAttribute.xml index 006ccae3400f3..f6bcd5be02d45 100644 --- a/xml/System.Runtime.InteropServices/TypeIdentifierAttribute.xml +++ b/xml/System.Runtime.InteropServices/TypeIdentifierAttribute.xml @@ -44,7 +44,7 @@ - For types that don’t have GUIDs in their type library, it has a constructor that takes two strings (`scope` and `identifier`). These are combined into a GUID and become the key that is used for type equivalence. - Type equivalence is discussed in the topic. + Type equivalence is discussed in the topic. ]]> diff --git a/xml/System.Runtime.InteropServices/TypeLibConverter.xml b/xml/System.Runtime.InteropServices/TypeLibConverter.xml index 3c3671e8b5be0..95fa5fe030384 100644 --- a/xml/System.Runtime.InteropServices/TypeLibConverter.xml +++ b/xml/System.Runtime.InteropServices/TypeLibConverter.xml @@ -132,7 +132,7 @@ . Otherwise, at least one of these parameters must be specified. If `publicKey` is `null`, the public key in `keyPair` will be set in the target assembly's manifest metadata and a signature will be generated based on the contents of the assembly. If `keyPair` is `null`, `publicKey` will be set in the target assembly's manifest metadata and no signature will be generated. Specifying both parameters is not generally useful, and can result in an invalid signature. + If you do not want to generate a strong name for your assembly, it is valid for `publicKey` and `keyPair` to be `null`, as long as `flags` does not equal . Otherwise, at least one of these parameters must be specified. If `publicKey` is `null`, the public key in `keyPair` will be set in the target assembly's manifest metadata and a signature will be generated based on the contents of the assembly. If `keyPair` is `null`, `publicKey` will be set in the target assembly's manifest metadata and no signature will be generated. Specifying both parameters is not generally useful, and can result in an invalid signature. For more information on `ITypeLib`, please see its existing documentation in the MSDN library. @@ -207,7 +207,7 @@ . Otherwise, atleast one of these parameters must be specified. If `publicKey` is `null`, the public key in `keyPair` will be set in the target assembly's manifest metadata and a signature will be generated based on the contents of the assembly. If `keyPair` is `null`, `publicKey` will be set in the target assembly's manifest metadata and no signature will be generated. Specifying both parameters is not generally useful, and can result in an invalid signature. + If you do not want to generate a strong name for your assembly, it is valid for `publicKey` and `keyPair` to be `null`, as long as `flags` does not equal . Otherwise, atleast one of these parameters must be specified. If `publicKey` is `null`, the public key in `keyPair` will be set in the target assembly's manifest metadata and a signature will be generated based on the contents of the assembly. If `keyPair` is `null`, `publicKey` will be set in the target assembly's manifest metadata and no signature will be generated. Specifying both parameters is not generally useful, and can result in an invalid signature. For more information on `ITypeLib`, please see its existing documentation in the MSDN library. diff --git a/xml/System.Runtime.InteropServices/TypeLibImporterFlags.xml b/xml/System.Runtime.InteropServices/TypeLibImporterFlags.xml index 6a3d146cf2c72..db68f583d5b7f 100644 --- a/xml/System.Runtime.InteropServices/TypeLibImporterFlags.xml +++ b/xml/System.Runtime.InteropServices/TypeLibImporterFlags.xml @@ -24,7 +24,7 @@ method. + This enumeration is used with the method. ]]> diff --git a/xml/System.Runtime.InteropServices/UnmanagedType.xml b/xml/System.Runtime.InteropServices/UnmanagedType.xml index f15c1c0ff573b..324f6c750e2ef 100644 --- a/xml/System.Runtime.InteropServices/UnmanagedType.xml +++ b/xml/System.Runtime.InteropServices/UnmanagedType.xml @@ -34,14 +34,14 @@ enumeration with the attribute to specify how types are marshaled during interoperation with unmanaged code. You can use this enumeration to marshal code using simple value types (I1, I2, I4, I8, R4, R8, U2, U4, and U8), unmanaged types that are unavailable in the .NET Framework, and various miscellaneous types. + Use the enumeration with the attribute to specify how types are marshaled during interoperation with unmanaged code. You can use this enumeration to marshal code using simple value types (I1, I2, I4, I8, R4, R8, U2, U4, and U8), unmanaged types that are unavailable in the .NET Framework, and various miscellaneous types. For more information, see [Interoperating with Unmanaged Code](http://msdn.microsoft.com/library/ccb68ce7-b0e9-4ffb-839d-03b1cd2c1258). ## Examples - The following code fragment demonstrates how to declare, in managed source code, an unmanaged interface implemented by a COM component. The attribute prevents the `IMyStorage` interface from being exported back for use by COM. (COM clients should use the existing COM component directly.) In this example, specifies serveral members, which represent the types used by the original COM interface. + The following code fragment demonstrates how to declare, in managed source code, an unmanaged interface implemented by a COM component. The attribute prevents the `IMyStorage` interface from being exported back for use by COM. (COM clients should use the existing COM component directly.) In this example, specifies serveral members, which represent the types used by the original COM interface. [!code-cpp[ImprovedInteropSnippets#2](~/samples/snippets/cpp/VS_Snippets_CLR/ImprovedInteropSnippets/CPP/codefile2.cpp#2)] [!code-csharp[ImprovedInteropSnippets#2](~/samples/snippets/csharp/VS_Snippets_CLR/ImprovedInteropSnippets/CS/codefile2.cs#2)] diff --git a/xml/System.Runtime.InteropServices/VarEnum.xml b/xml/System.Runtime.InteropServices/VarEnum.xml index c6f878f43fe03..298ad4ecd07fe 100644 --- a/xml/System.Runtime.InteropServices/VarEnum.xml +++ b/xml/System.Runtime.InteropServices/VarEnum.xml @@ -34,7 +34,7 @@ to explicitly control the element type of the . + Used with to explicitly control the element type of the . diff --git a/xml/System.Runtime.InteropServices/_Assembly.xml b/xml/System.Runtime.InteropServices/_Assembly.xml index 08c6427b52d24..90c0d139d60f7 100644 --- a/xml/System.Runtime.InteropServices/_Assembly.xml +++ b/xml/System.Runtime.InteropServices/_Assembly.xml @@ -33,7 +33,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code, and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> @@ -61,7 +61,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the location of the assembly as specified originally, for example, in an object. + The property gets the location of the assembly as specified originally, for example, in an object. ]]> diff --git a/xml/System.Runtime.InteropServices/_ConstructorInfo.xml b/xml/System.Runtime.InteropServices/_ConstructorInfo.xml index 14422a237829d..f37a0d6a461c2 100644 --- a/xml/System.Runtime.InteropServices/_ConstructorInfo.xml +++ b/xml/System.Runtime.InteropServices/_ConstructorInfo.xml @@ -33,9 +33,9 @@ ## Remarks This interface is for access to managed classes from unmanaged code, and should not be called from managed code. - The class discovers the attributes of a class constructor and provides access to constructor metadata. + The class discovers the attributes of a class constructor and provides access to constructor metadata. - The interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + The interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> diff --git a/xml/System.Runtime.InteropServices/_EventInfo.xml b/xml/System.Runtime.InteropServices/_EventInfo.xml index 1e75972fa57a9..fd35a3ebafbe3 100644 --- a/xml/System.Runtime.InteropServices/_EventInfo.xml +++ b/xml/System.Runtime.InteropServices/_EventInfo.xml @@ -33,7 +33,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> diff --git a/xml/System.Runtime.InteropServices/_Exception.xml b/xml/System.Runtime.InteropServices/_Exception.xml index d2c87033075e0..799d489dad5da 100644 --- a/xml/System.Runtime.InteropServices/_Exception.xml +++ b/xml/System.Runtime.InteropServices/_Exception.xml @@ -30,7 +30,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> @@ -63,7 +63,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method determines whether the specified is equal to the current . + The method determines whether the specified is equal to the current . ]]> @@ -92,7 +92,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method returns the that is the root cause of one or more subsequent exceptions. + The method returns the that is the root cause of one or more subsequent exceptions. ]]> @@ -121,7 +121,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. + The method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. ]]> @@ -154,7 +154,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method sets the object with information about the exception. + The method sets the object with information about the exception. ]]> @@ -184,7 +184,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method gets the runtime type of the current instance. + The method gets the runtime type of the current instance. ]]> @@ -212,7 +212,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets or sets a link to the help file associated with this exception. + The property gets or sets a link to the help file associated with this exception. ]]> @@ -240,7 +240,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets the instance that caused the current exception. + The property gets the instance that caused the current exception. ]]> @@ -268,7 +268,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets a message that describes the current exception. + The property gets a message that describes the current exception. ]]> @@ -296,7 +296,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets or sets the name of the application or the object that causes the error. + The property gets or sets the name of the application or the object that causes the error. ]]> @@ -324,7 +324,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets a string representation of the frames on the call stack at the time the current exception was thrown. + The property gets a string representation of the frames on the call stack at the time the current exception was thrown. ]]> @@ -352,7 +352,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets the method that throws the current exception. + The property gets the method that throws the current exception. ]]> @@ -381,7 +381,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method creates and returns a string representation of the current exception. + The method creates and returns a string representation of the current exception. ]]> diff --git a/xml/System.Runtime.InteropServices/_FieldInfo.xml b/xml/System.Runtime.InteropServices/_FieldInfo.xml index 6966626f3bf71..b95146986467a 100644 --- a/xml/System.Runtime.InteropServices/_FieldInfo.xml +++ b/xml/System.Runtime.InteropServices/_FieldInfo.xml @@ -33,7 +33,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code, and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> diff --git a/xml/System.Runtime.InteropServices/_MemberInfo.xml b/xml/System.Runtime.InteropServices/_MemberInfo.xml index d6d1b031702b8..89879e37faa4b 100644 --- a/xml/System.Runtime.InteropServices/_MemberInfo.xml +++ b/xml/System.Runtime.InteropServices/_MemberInfo.xml @@ -33,7 +33,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> @@ -61,7 +61,7 @@ ## Remarks This property is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets the class that declares this member. + The property gets the class that declares this member. ]]> @@ -94,7 +94,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method determines whether the specified is equal to the current . + The method determines whether the specified is equal to the current . ]]> @@ -114,7 +114,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method returns all attributes applied to this member. + The method returns all attributes applied to this member. ]]> @@ -147,7 +147,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method returns an array containing all the custom attributes. + The method returns an array containing all the custom attributes. ]]> @@ -182,7 +182,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method returns an array of custom attributes identified by . + The method returns an array of custom attributes identified by . ]]> @@ -211,7 +211,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. + The method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. ]]> @@ -277,7 +277,7 @@ ## Remarks This method is for access to managed classes from unmanaged code and should not be called from managed code. - The method gets the type of the current instance. + The method gets the type of the current instance. ]]> @@ -446,7 +446,7 @@ ## Remarks This property is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets a value indicating the type of the member — method, constructor, event, and so on. + The property gets a value indicating the type of the member — method, constructor, event, and so on. ]]> @@ -474,7 +474,7 @@ ## Remarks This property is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets the name of the current member. + The property gets the name of the current member. ]]> @@ -502,7 +502,7 @@ ## Remarks This property is for access to managed classes from unmanaged code and should not be called from managed code. - The property gets the class object that was used to obtain this instance of . + The property gets the class object that was used to obtain this instance of . ]]> diff --git a/xml/System.Runtime.InteropServices/_MethodBase.xml b/xml/System.Runtime.InteropServices/_MethodBase.xml index 38a2180cd60e0..8643c3e990ba7 100644 --- a/xml/System.Runtime.InteropServices/_MethodBase.xml +++ b/xml/System.Runtime.InteropServices/_MethodBase.xml @@ -33,7 +33,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> diff --git a/xml/System.Runtime.InteropServices/_MethodInfo.xml b/xml/System.Runtime.InteropServices/_MethodInfo.xml index c11cc2e363989..b3a5dc7526bdc 100644 --- a/xml/System.Runtime.InteropServices/_MethodInfo.xml +++ b/xml/System.Runtime.InteropServices/_MethodInfo.xml @@ -33,7 +33,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> diff --git a/xml/System.Runtime.InteropServices/_PropertyInfo.xml b/xml/System.Runtime.InteropServices/_PropertyInfo.xml index 27fab90187279..2004ac38213a8 100644 --- a/xml/System.Runtime.InteropServices/_PropertyInfo.xml +++ b/xml/System.Runtime.InteropServices/_PropertyInfo.xml @@ -33,7 +33,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> diff --git a/xml/System.Runtime.InteropServices/_Type.xml b/xml/System.Runtime.InteropServices/_Type.xml index 313872646800b..94b5afb1e62bc 100644 --- a/xml/System.Runtime.InteropServices/_Type.xml +++ b/xml/System.Runtime.InteropServices/_Type.xml @@ -33,7 +33,7 @@ ## Remarks This interface is for access to managed classes from unmanaged code and should not be called from managed code. - This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + This interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. ]]> @@ -61,7 +61,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the in which the type is declared. For generic types, this property gets the in which the generic type is defined. + The property gets the in which the type is declared. For generic types, this property gets the in which the generic type is defined. ]]> @@ -89,7 +89,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the assembly-qualified name of the , including the name of the assembly from which the was loaded. + The property gets the assembly-qualified name of the , including the name of the assembly from which the was loaded. ]]> @@ -117,7 +117,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the attributes associated with the . + The property gets the attributes associated with the . ]]> @@ -145,7 +145,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the type from which the current directly inherits. + The property gets the type from which the current directly inherits. ]]> @@ -173,7 +173,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the class that declares this member. + The property gets the class that declares this member. ]]> @@ -193,7 +193,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method determines if the underlying system type of the current is the same as the underlying system type of the specified or . + The method determines if the underlying system type of the current is the same as the underlying system type of the specified or . . @@ -228,7 +228,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method determines if the underlying system type of the current is the same as the underlying system type of the specified . + The method determines if the underlying system type of the current is the same as the underlying system type of the specified . ]]> @@ -261,7 +261,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method determines if the underlying system type of the current is the same as the underlying system type of the specified . + The method determines if the underlying system type of the current is the same as the underlying system type of the specified . ]]> @@ -299,7 +299,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns an array of objects representing a filtered list of interfaces implemented or inherited by the current . + The method returns an array of objects representing a filtered list of interfaces implemented or inherited by the current . ]]> @@ -347,7 +347,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns a filtered array of objects of the specified member type. + The method returns a filtered array of objects of the specified member type. ]]> @@ -375,7 +375,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the fully qualified name of the , including the namespace of the but not the assembly. + The property gets the fully qualified name of the , including the namespace of the but not the assembly. ]]> @@ -404,7 +404,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the number of dimensions in an . + The method gets the number of dimensions in an . ]]> @@ -424,7 +424,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets a specific constructor of the current . + The method gets a specific constructor of the current . ]]> @@ -460,7 +460,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for a public instance constructor whose parameters match the types in the specified array. + The method searches for a public instance constructor whose parameters match the types in the specified array. ]]> @@ -514,7 +514,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for a constructor whose parameters match the specified argument types and modifiers, using the specified binding constraints. + The method searches for a constructor whose parameters match the specified argument types and modifiers, using the specified binding constraints. ]]> @@ -566,7 +566,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for a constructor whose parameters match the specified argument types and modifiers, using the specified binding constraints and the specified calling convention. + The method searches for a constructor whose parameters match the specified argument types and modifiers, using the specified binding constraints and the specified calling convention. ]]> @@ -586,7 +586,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the constructors of the current . + The method gets the constructors of the current . ]]> @@ -615,7 +615,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all the public constructors defined for the current . + The method returns all the public constructors defined for the current . ]]> @@ -651,7 +651,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the constructors defined for the current , using the specified . + The method searches for the constructors defined for the current , using the specified . ]]> @@ -671,7 +671,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all attributes applied to this member. + The method returns all attributes applied to this member. ]]> @@ -703,7 +703,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all attributes applied to this member. + The method returns all attributes applied to this member. ]]> @@ -737,7 +737,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all attributes applied to this member. + The method returns all attributes applied to this member. ]]> @@ -770,7 +770,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the members defined for the current whose is set. + The method searches for the members defined for the current whose is set. ]]> @@ -803,7 +803,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns the of the object encompassed or referred to by the current array, pointer or reference type. + The method returns the of the object encompassed or referred to by the current array, pointer or reference type. ]]> @@ -823,7 +823,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets a specific event declared or inherited by the current . + The method gets a specific event declared or inherited by the current . ]]> @@ -863,7 +863,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for events that are declared or inherited by the current , using the specified binding constraints. + The method searches for events that are declared or inherited by the current , using the specified binding constraints. ]]> @@ -901,7 +901,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns the object representing the specified event, using the specified binding constraints. + The method returns the object representing the specified event, using the specified binding constraints. ]]> @@ -921,7 +921,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the events that are declared or inherited by the current . + The method gets the events that are declared or inherited by the current . ]]> @@ -954,7 +954,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all the public events that are declared or inherited by the current . + The method returns all the public events that are declared or inherited by the current . ]]> @@ -994,7 +994,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for events that are declared or inherited by the current , using the specified binding constraints. + The method searches for events that are declared or inherited by the current , using the specified binding constraints. ]]> @@ -1014,7 +1014,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets a specific field of the current . + The method gets a specific field of the current . ]]> @@ -1046,7 +1046,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the public field with the specified name. + The method searches for the public field with the specified name. ]]> @@ -1084,7 +1084,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified field, using the specified binding constraints. + The method searches for the specified field, using the specified binding constraints. ]]> @@ -1104,7 +1104,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets a specific field of the current . + The method gets a specific field of the current . ]]> @@ -1137,7 +1137,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all the public fields of the current . + The method returns all the public fields of the current . ]]> @@ -1177,7 +1177,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the fields defined for the current , using the specified binding constraints. + The method searches for the fields defined for the current , using the specified binding constraints. ]]> @@ -1206,7 +1206,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method. + The method. ]]> @@ -1263,7 +1263,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets a specific interface implemented or inherited by the current . + The method gets a specific interface implemented or inherited by the current . ]]> @@ -1295,7 +1295,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the interface with the specified name.. + The method searches for the interface with the specified name.. ]]> @@ -1334,7 +1334,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified interface, specifying whether to do a case-sensitive search. + The method searches for the specified interface, specifying whether to do a case-sensitive search. ]]> @@ -1366,7 +1366,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns an interface mapping for the specified interface type. + The method returns an interface mapping for the specified interface type. ]]> @@ -1399,7 +1399,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets all the interfaces implemented or inherited by the current . + The method gets all the interfaces implemented or inherited by the current . ]]> @@ -1419,7 +1419,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the specified members of the current . + The method gets the specified members of the current . ]]> @@ -1451,7 +1451,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the public members with the specified name. + The method searches for the public members with the specified name. ]]> @@ -1489,7 +1489,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified members, using the specified binding constraints. + The method searches for the specified members, using the specified binding constraints. ]]> @@ -1529,7 +1529,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified members of the specified member type, using the specified binding constraints. + The method searches for the specified members of the specified member type, using the specified binding constraints. ]]> @@ -1549,7 +1549,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the members (properties, methods, fields, events, and so on) of the current . + The method gets the members (properties, methods, fields, events, and so on) of the current . ]]> @@ -1582,7 +1582,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all the public members of the current . + The method returns all the public members of the current . ]]> @@ -1622,7 +1622,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the members defined for the current , using the specified binding constraints. + The method searches for the members defined for the current , using the specified binding constraints. ]]> @@ -1642,7 +1642,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method. + The method. ]]> @@ -1674,7 +1674,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the public method with the specified name.. + The method searches for the public method with the specified name.. ]]> @@ -1712,7 +1712,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified method, using the specified binding constraints. + The method searches for the specified method, using the specified binding constraints. ]]> @@ -1750,7 +1750,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified public method whose parameters match the specified argument types. + The method searches for the specified public method whose parameters match the specified argument types. ]]> @@ -1790,7 +1790,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified public method whose parameters match the specified argument types and modifiers. + The method searches for the specified public method whose parameters match the specified argument types and modifiers. ]]> @@ -1842,7 +1842,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified method whose parameters match the specified argument types and modifiers, using the specified binding constraints. + The method searches for the specified method whose parameters match the specified argument types and modifiers, using the specified binding constraints. ]]> @@ -1896,7 +1896,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified method whose parameters match the specified argument types and modifiers, using the specified binding constraints and the specified calling convention. + The method searches for the specified method whose parameters match the specified argument types and modifiers, using the specified binding constraints and the specified calling convention. ]]> @@ -1916,7 +1916,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the methods of the current . + The method gets the methods of the current . ]]> @@ -1949,7 +1949,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all the public methods of the current . + The method returns all the public methods of the current . ]]> @@ -1989,7 +1989,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the methods defined for the current , using the specified binding constraints. + The method searches for the methods defined for the current , using the specified binding constraints. ]]> @@ -2009,7 +2009,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets a specific type nested within the current . + The method gets a specific type nested within the current . ]]> @@ -2041,7 +2041,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the public nested type with the specified name. + The method searches for the public nested type with the specified name. ]]> @@ -2079,7 +2079,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified nested type, using the specified binding constraints. + The method searches for the specified nested type, using the specified binding constraints. ]]> @@ -2099,7 +2099,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the types nested within the current . + The method gets the types nested within the current . ]]> @@ -2132,7 +2132,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all the types nested within the current . + The method returns all the types nested within the current . ]]> @@ -2190,7 +2190,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the properties of the current .. + The method gets the properties of the current .. ]]> @@ -2223,7 +2223,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns all the public properties of the current . + The method returns all the public properties of the current . ]]> @@ -2263,7 +2263,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the properties of the current , using the specified binding constraints. + The method searches for the properties of the current , using the specified binding constraints. ]]> @@ -2283,7 +2283,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets a specific property of the current . + The method gets a specific property of the current . ]]> @@ -2315,7 +2315,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the public property with the specified name. + The method searches for the public property with the specified name. ]]> @@ -2353,7 +2353,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified property, using the specified binding constraints. + The method searches for the specified property, using the specified binding constraints. ]]> @@ -2387,7 +2387,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the public property with the specified name and return type. + The method searches for the public property with the specified name and return type. ]]> @@ -2425,7 +2425,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified public property whose parameters match the specified argument types.. + The method searches for the specified public property whose parameters match the specified argument types.. ]]> @@ -2465,7 +2465,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified public property whose parameters match the specified argument types. + The method searches for the specified public property whose parameters match the specified argument types. ]]> @@ -2507,7 +2507,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified public property whose parameters match the specified argument types and modifiers. + The method searches for the specified public property whose parameters match the specified argument types and modifiers. ]]> @@ -2561,7 +2561,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method searches for the specified property whose parameters match the specified argument types and modifiers, using the specified binding constraints. + The method searches for the specified property whose parameters match the specified argument types and modifiers, using the specified binding constraints. ]]> @@ -2590,7 +2590,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method gets the current . + The method gets the current . ]]> @@ -2680,7 +2680,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the GUID associated with the . + The property gets the GUID associated with the . ]]> @@ -2709,7 +2709,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property + The property ]]> @@ -2772,7 +2772,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method invokes a specific member of the current . + The method invokes a specific member of the current . . @@ -2826,7 +2826,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method invokes the specified member, using the specified binding constraints and matching the specified argument list. + The method invokes the specified member, using the specified binding constraints and matching the specified argument list. ]]> @@ -2884,7 +2884,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method invokes the specified member, using the specified binding constraints and matching the specified argument list and culture. + The method invokes the specified member, using the specified binding constraints and matching the specified argument list and culture. ]]> @@ -2946,7 +2946,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method invokes the specified member, using the specified binding constraints and matching the specified argument list, modifiers, and culture. + The method invokes the specified member, using the specified binding constraints and matching the specified argument list, modifiers, and culture. ]]> @@ -2975,7 +2975,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is abstract and must be overridden. + The property gets a value indicating whether the is abstract and must be overridden. ]]> @@ -3004,7 +3004,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the string format attribute `AnsiClass` is selected for the . + The property gets a value indicating whether the string format attribute `AnsiClass` is selected for the . ]]> @@ -3033,7 +3033,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is an array. + The property gets a value indicating whether the is an array. ]]> @@ -3093,7 +3093,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the string format attribute `AutoClass` is selected for the . + The property gets a value indicating whether the string format attribute `AutoClass` is selected for the . ]]> @@ -3122,7 +3122,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the class layout attribute `AutoLayout` is selected for the . + The property gets a value indicating whether the class layout attribute `AutoLayout` is selected for the . ]]> @@ -3151,7 +3151,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is passed by reference. + The property gets a value indicating whether the is passed by reference. ]]> @@ -3180,7 +3180,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is a class; that is, not a value type or interface. + The property gets a value indicating whether the is a class; that is, not a value type or interface. ]]> @@ -3209,7 +3209,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is a COM object. + The property gets a value indicating whether the is a COM object. ]]> @@ -3238,7 +3238,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the can be hosted in a context. + The property gets a value indicating whether the can be hosted in a context. ]]> @@ -3273,7 +3273,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method indicates whether one or more instance of `attributeType` is applied to this member. + The method indicates whether one or more instance of `attributeType` is applied to this member. ]]> @@ -3302,7 +3302,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the current represents an enumeration. + The property gets a value indicating whether the current represents an enumeration. ]]> @@ -3331,7 +3331,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the class layout attribute `ExplicitLayout` is selected for the . + The property gets a value indicating whether the class layout attribute `ExplicitLayout` is selected for the . ]]> @@ -3360,7 +3360,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the has , indicating that it was imported from a COM type library. + The property gets a value indicating whether the has , indicating that it was imported from a COM type library. ]]> @@ -3393,7 +3393,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method determines whether the specified object is an instance of the current . + The method determines whether the specified object is an instance of the current . ]]> @@ -3422,7 +3422,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is an interface; that is, not a class or a value type. + The property gets a value indicating whether the is an interface; that is, not a class or a value type. ]]> @@ -3451,7 +3451,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the class layout attribute `SequentialLayout` is selected for the . + The property gets a value indicating whether the class layout attribute `SequentialLayout` is selected for the . ]]> @@ -3480,7 +3480,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the Type is marshaled by reference. + The property gets a value indicating whether the Type is marshaled by reference. ]]> @@ -3509,7 +3509,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and visible only within its own assembly. + The property gets a value indicating whether the is nested and visible only within its own assembly. ]]> @@ -3538,7 +3538,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and visible only to classes that belong to both its own family and its own assembly. + The property gets a value indicating whether the is nested and visible only to classes that belong to both its own family and its own assembly. ]]> @@ -3567,7 +3567,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and visible only within its own family. + The property gets a value indicating whether the is nested and visible only within its own family. ]]> @@ -3596,7 +3596,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and visible only to classes that belong to either its own family or to its own assembly. + The property gets a value indicating whether the is nested and visible only to classes that belong to either its own family or to its own assembly. ]]> @@ -3625,7 +3625,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and declared private. + The property gets a value indicating whether the is nested and declared private. ]]> @@ -3654,7 +3654,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether a class is nested and declared public. + The property gets a value indicating whether a class is nested and declared public. ]]> @@ -3683,7 +3683,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the top-level is not declared public. + The property gets a value indicating whether the top-level is not declared public. ]]> @@ -3712,7 +3712,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is a pointer. + The property gets a value indicating whether the is a pointer. ]]> @@ -3741,7 +3741,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is one of the primitive types. + The property gets a value indicating whether the is one of the primitive types. ]]> @@ -3770,7 +3770,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the top-level is declared public. + The property gets a value indicating whether the top-level is declared public. ]]> @@ -3799,7 +3799,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is declared sealed. + The property gets a value indicating whether the is declared sealed. ]]> @@ -3828,7 +3828,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is serializable. + The property gets a value indicating whether the is serializable. ]]> @@ -3857,7 +3857,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the has a name that requires special handling. + The property gets a value indicating whether the has a name that requires special handling. ]]> @@ -3890,7 +3890,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method determines whether the class represented by the current derives from the class represented by the specified . + The method determines whether the class represented by the current derives from the class represented by the specified . ]]> @@ -3919,7 +3919,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the string format attribute `UnicodeClass` is selected for the . + The property gets a value indicating whether the string format attribute `UnicodeClass` is selected for the . ]]> @@ -3948,7 +3948,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is a value type. + The property gets a value indicating whether the is a value type. ]]> @@ -3976,7 +3976,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating that this member is a type or a nested type. + The property gets a value indicating that this member is a type or a nested type. ]]> @@ -4004,7 +4004,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the module (the DLL) in which the current is defined. + The property gets the module (the DLL) in which the current is defined. ]]> @@ -4032,7 +4032,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the name of the . + The property gets the name of the . ]]> @@ -4060,7 +4060,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the namespace of the . + The property gets the namespace of the . ]]> @@ -4088,7 +4088,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the class object that was used to obtain this member. + The property gets the class object that was used to obtain this member. ]]> @@ -4117,7 +4117,7 @@ ## Remarks This method is for access to managed classes from unmanaged code, and should not be called from managed code. - The method returns the name of the current . + The method returns the name of the current . ]]> @@ -4145,7 +4145,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the handle for the current . + The property gets the handle for the current . ]]> @@ -4173,7 +4173,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the initializer for the . + The property gets the initializer for the . ]]> @@ -4201,7 +4201,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property indicates the type provided by the common language runtime that represents this type. + The property indicates the type provided by the common language runtime that represents this type. ]]> diff --git a/xml/System.Runtime.Remoting.Activation/ActivatorLevel.xml b/xml/System.Runtime.Remoting.Activation/ActivatorLevel.xml index e2e4439137a45..e9f225ecb8bc9 100644 --- a/xml/System.Runtime.Remoting.Activation/ActivatorLevel.xml +++ b/xml/System.Runtime.Remoting.Activation/ActivatorLevel.xml @@ -21,7 +21,7 @@ . Because each activator is responsible for calling the next one in the chain, an activator can position itself anywhere in the chain. The enumerator helps activators find the appropriate position in the chain. + The design of activators allows for more than one activator to participate in the activation process, and additional activators can be added to the chain by using . Because each activator is responsible for calling the next one in the chain, an activator can position itself anywhere in the chain. The enumerator helps activators find the appropriate position in the chain. ]]> diff --git a/xml/System.Runtime.Remoting.Activation/IConstructionCallMessage.xml b/xml/System.Runtime.Remoting.Activation/IConstructionCallMessage.xml index 5391bb3de0dcc..b3881dec6e5f3 100644 --- a/xml/System.Runtime.Remoting.Activation/IConstructionCallMessage.xml +++ b/xml/System.Runtime.Remoting.Activation/IConstructionCallMessage.xml @@ -23,7 +23,7 @@ and before the thread returns to the user code, a is sent to the remote application. When the construction message arrives at the remote application, it is processed by a remoting activator (either the default one, or one that is specified in the property) and a new object is created. The remoting application then returns a to the local application. The contains an instance of , which packages information about the remote object. The remoting infrastructure converts the instance into a proxy to the remote object, which is returned to the user code. + When the user creates an instance of a new client-activated object by calling `new` or and before the thread returns to the user code, a is sent to the remote application. When the construction message arrives at the remote application, it is processed by a remoting activator (either the default one, or one that is specified in the property) and a new object is created. The remoting application then returns a to the local application. The contains an instance of , which packages information about the remote object. The remoting infrastructure converts the instance into a proxy to the remote object, which is returned to the user code. ]]> @@ -91,7 +91,7 @@ property on the activator that is returned by the current property to traverse the chain of activators. + A chain of activators that are arranged in a hierarchy typically completes the various tasks that are involved in the activation process. If you intend to plug in a custom activator, then you should traverse the activator hierarchy and plug in your activator at the appropriate location. Use the property on the activator that is returned by the current property to traverse the chain of activators. If you add your own activator into the message's activator chain on the client side, the activator may be serialized and transported to the server side, if deemed necessary. For this reason, custom activators should be fairly lightweight in terms of serialization requirements. @@ -121,7 +121,7 @@ indexer allows you to specify additional attributes to use during object activation. The user specifies the in the `activationAttributes` parameter to . + The indexer allows you to specify additional attributes to use during object activation. The user specifies the in the `activationAttributes` parameter to . ]]> diff --git a/xml/System.Runtime.Remoting.Activation/UrlAttribute.xml b/xml/System.Runtime.Remoting.Activation/UrlAttribute.xml index 9e7a0e7b0f32a..3a9a817038801 100644 --- a/xml/System.Runtime.Remoting.Activation/UrlAttribute.xml +++ b/xml/System.Runtime.Remoting.Activation/UrlAttribute.xml @@ -22,7 +22,7 @@ is passed in the activation attributes array as a parameter to when creating activated objects with the method. + The is passed in the activation attributes array as a parameter to when creating activated objects with the method. For more information about using attributes, see [Attributes](~/docs/standard/attributes/index.md). @@ -107,7 +107,7 @@ method. + This method overrides the default method. ]]> diff --git a/xml/System.Runtime.Remoting.Channels.Http/HttpChannel.xml b/xml/System.Runtime.Remoting.Channels.Http/HttpChannel.xml index 39f648bd14cb3..9350090f88066 100644 --- a/xml/System.Runtime.Remoting.Channels.Http/HttpChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Http/HttpChannel.xml @@ -33,7 +33,7 @@ Channels are used by the .NET Framework remoting infrastructure to transport remote calls. When a client makes a call to a remote object, the call is serialized into a message that is sent by a client channel and received by a server channel. It is then deserialized and processed. Any returned values are transmitted by the server channel and received by the client channel. - A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see [Channel and Formatter Configuration Properties](http://msdn.microsoft.com/en-us/226ecf74-ebbd-4ea0-a701-dcf4441deefe). + A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see [Channel and Formatter Configuration Properties](http://msdn.microsoft.com/en-us/226ecf74-ebbd-4ea0-a701-dcf4441deefe). diff --git a/xml/System.Runtime.Remoting.Channels.Http/HttpClientChannel.xml b/xml/System.Runtime.Remoting.Channels.Http/HttpClientChannel.xml index d9c8d5b2cf8d0..6a9855bfec567 100644 --- a/xml/System.Runtime.Remoting.Channels.Http/HttpClientChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Http/HttpClientChannel.xml @@ -31,7 +31,7 @@ By default, the uses a SOAP formatter to serialize all messages. - A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see [Channel and Formatter Configuration Properties](http://msdn.microsoft.com/en-us/226ecf74-ebbd-4ea0-a701-dcf4441deefe). + A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see [Channel and Formatter Configuration Properties](http://msdn.microsoft.com/en-us/226ecf74-ebbd-4ea0-a701-dcf4441deefe). diff --git a/xml/System.Runtime.Remoting.Channels.Http/HttpRemotingHandler.xml b/xml/System.Runtime.Remoting.Channels.Http/HttpRemotingHandler.xml index cd6fcf8eac8b8..ab30e418e7bfb 100644 --- a/xml/System.Runtime.Remoting.Channels.Http/HttpRemotingHandler.xml +++ b/xml/System.Runtime.Remoting.Channels.Http/HttpRemotingHandler.xml @@ -109,7 +109,7 @@ methods, see . + For more information about the methods, see . ]]> diff --git a/xml/System.Runtime.Remoting.Channels.Http/HttpRemotingHandlerFactory.xml b/xml/System.Runtime.Remoting.Channels.Http/HttpRemotingHandlerFactory.xml index 94ef13e7282ec..7300354fd27c7 100644 --- a/xml/System.Runtime.Remoting.Channels.Http/HttpRemotingHandlerFactory.xml +++ b/xml/System.Runtime.Remoting.Channels.Http/HttpRemotingHandlerFactory.xml @@ -70,7 +70,7 @@ . + For more information about the current method, see . ]]> diff --git a/xml/System.Runtime.Remoting.Channels.Http/HttpServerChannel.xml b/xml/System.Runtime.Remoting.Channels.Http/HttpServerChannel.xml index b8d509cb21064..e530c90388ac3 100644 --- a/xml/System.Runtime.Remoting.Channels.Http/HttpServerChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Http/HttpServerChannel.xml @@ -31,7 +31,7 @@ The accepts messages serialized in either binary or SOAP format. - A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see the documentation for . + A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see the documentation for . @@ -259,7 +259,7 @@ , the value of this property can be cast to an instance of describing the channel to which the object listens. + Although returned as an instance of , the value of this property can be cast to an instance of describing the channel to which the object listens. ]]> @@ -428,7 +428,7 @@ . + The current method is used by . diff --git a/xml/System.Runtime.Remoting.Channels.Ipc/IpcChannel.xml b/xml/System.Runtime.Remoting.Channels.Ipc/IpcChannel.xml index b28a15b8e607b..0119ddbe070e9 100644 --- a/xml/System.Runtime.Remoting.Channels.Ipc/IpcChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Ipc/IpcChannel.xml @@ -201,7 +201,7 @@ , the value of this property can be cast to an instance of describing the channel to which the object listens. + Although returned as an instance of , the value of this property can be cast to an instance of describing the channel to which the object listens. @@ -347,7 +347,7 @@ . + This method is used by . diff --git a/xml/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel.xml b/xml/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel.xml index e5775727a55cd..995ae84eded60 100644 --- a/xml/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel.xml @@ -31,7 +31,7 @@ By default, the class uses a binary formatter to serialize all messages. - A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see the documentation for the constructor. + A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see the documentation for the constructor. @@ -180,7 +180,7 @@ method. The default name is "ipc client". + Every registered channel has a unique name. The name is used to retrieve a specific channel when calling the method. The default name is "ipc client". diff --git a/xml/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel.xml b/xml/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel.xml index 5780387bb3d40..2cf8d419ac56c 100644 --- a/xml/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel.xml @@ -31,7 +31,7 @@ The instance accepts messages serialized in either binary or SOAP format. - A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing an collection to the constructor). For a list of these configuration properties, see the documentation for the constructor. + A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing an collection to the constructor). For a list of these configuration properties, see the documentation for the constructor. > [!CAUTION] > When setting the `exclusiveAddressUse` property to `false` in the `properties` argument, several objects can be registered for the same named pipe. In such a case requests can go to any of the channels registered. This setting is considered secure only if ALCs are also used. @@ -250,7 +250,7 @@ class, the value of this property can be cast to an instance of that describes the channel to which the object listens. + Although returned as an instance of the class, the value of this property can be cast to an instance of that describes the channel to which the object listens. @@ -387,7 +387,7 @@ method. + This method is used by the method. diff --git a/xml/System.Runtime.Remoting.Channels.Tcp/TcpChannel.xml b/xml/System.Runtime.Remoting.Channels.Tcp/TcpChannel.xml index 0a1c12e6b0713..39772a7074b8a 100644 --- a/xml/System.Runtime.Remoting.Channels.Tcp/TcpChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Tcp/TcpChannel.xml @@ -32,7 +32,7 @@ To perform additional processing of messages, you can specify implementations of the and through which all messages processed by the are passed. - A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For more information about channel configuration properties, see [Channel and Formatter Configuration Properties](http://msdn.microsoft.com/en-us/226ecf74-ebbd-4ea0-a701-dcf4441deefe). + A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For more information about channel configuration properties, see [Channel and Formatter Configuration Properties](http://msdn.microsoft.com/en-us/226ecf74-ebbd-4ea0-a701-dcf4441deefe). > [!NOTE] > If the server computer is running Windows 95/98/Me, the server cannot be specified as secure. @@ -189,7 +189,7 @@ , the value of this property can be cast to an instance of describing the channel to which the object listens. + Although returned as an instance of , the value of this property can be cast to an instance of describing the channel to which the object listens. @@ -330,7 +330,7 @@ . + This method is used by . diff --git a/xml/System.Runtime.Remoting.Channels.Tcp/TcpClientChannel.xml b/xml/System.Runtime.Remoting.Channels.Tcp/TcpClientChannel.xml index 87e8b53ccf9e5..ff6fc714aca23 100644 --- a/xml/System.Runtime.Remoting.Channels.Tcp/TcpClientChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Tcp/TcpClientChannel.xml @@ -31,7 +31,7 @@ By default, the class uses a binary formatter to serialize all messages. - A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see the documentation for . + A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see the documentation for . diff --git a/xml/System.Runtime.Remoting.Channels.Tcp/TcpServerChannel.xml b/xml/System.Runtime.Remoting.Channels.Tcp/TcpServerChannel.xml index c8336d586289e..56247efcf2fd8 100644 --- a/xml/System.Runtime.Remoting.Channels.Tcp/TcpServerChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Tcp/TcpServerChannel.xml @@ -31,7 +31,7 @@ The instance accepts messages serialized in either binary or SOAP format. - A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see [Channel and Formatter Configuration Properties](http://msdn.microsoft.com/en-us/226ecf74-ebbd-4ea0-a701-dcf4441deefe). + A object has associated configuration properties that can be set at run time either in a configuration file (by invoking the static method) or programmatically (by passing a collection to the constructor). For a list of these configuration properties, see [Channel and Formatter Configuration Properties](http://msdn.microsoft.com/en-us/226ecf74-ebbd-4ea0-a701-dcf4441deefe). > [!NOTE] > If the server computer is running Windows 95/98/Me, the cannot be specified as secure. @@ -257,7 +257,7 @@ , the value of this property can be cast to an instance of describing the channel to which the object listens. + Although returned as an instance of , the value of this property can be cast to an instance of describing the channel to which the object listens. @@ -389,7 +389,7 @@ . + This method is used by . diff --git a/xml/System.Runtime.Remoting.Channels/BinaryServerFormatterSink.xml b/xml/System.Runtime.Remoting.Channels/BinaryServerFormatterSink.xml index 870d6c0d7560e..a2579c394387c 100644 --- a/xml/System.Runtime.Remoting.Channels/BinaryServerFormatterSink.xml +++ b/xml/System.Runtime.Remoting.Channels/BinaryServerFormatterSink.xml @@ -20,7 +20,7 @@ method, which is called by server channels to create the server channel sink chains. When the message reaches the dispatch sink, the dispatch sink passes the message to the remoting infrastructure. + The request stream propagates from the server transport sink through the server channel sinks until it reaches the appropriate formatter sink. The formatter sink deserializes the message and passes it through the pipeline. A special dispatch sink is inserted at the end of the channel sink chain by the method, which is called by server channels to create the server channel sink chains. When the message reaches the dispatch sink, the dispatch sink passes the message to the remoting infrastructure. The following table shows the sink configuration properties that can be specified for the current sink provider. diff --git a/xml/System.Runtime.Remoting.Channels/BinaryServerFormatterSinkProvider.xml b/xml/System.Runtime.Remoting.Channels/BinaryServerFormatterSinkProvider.xml index 5abbb40851dbc..6963998a64701 100644 --- a/xml/System.Runtime.Remoting.Channels/BinaryServerFormatterSinkProvider.xml +++ b/xml/System.Runtime.Remoting.Channels/BinaryServerFormatterSinkProvider.xml @@ -24,7 +24,7 @@ Channel sink providers are stored in a chain, and the user is responsible for chaining all channel sink providers together before passing the outer one to the channel constructor. provides a property called for this purpose. - When multiple channel sink providers are provided in a configuration file, the remoting infrastructure will chain them together in the order they are found in the configuration file. The channel sink providers will be created when the channel is created during the call. + When multiple channel sink providers are provided in a configuration file, the remoting infrastructure will chain them together in the order they are found in the configuration file. The channel sink providers will be created when the channel is created during the call. Formatter sinks use sink configuration properties to configure the channel at run time. Sink properties can be specified in a configuration file, or programmatically, inside of a . In a configuration file all values are represented by strings, but when building a property programmatically, value types can be specified with their native values or with strings. diff --git a/xml/System.Runtime.Remoting.Channels/ChannelServices.xml b/xml/System.Runtime.Remoting.Channels/ChannelServices.xml index ab3b7d5442cb1..ffc8abc53ee3c 100644 --- a/xml/System.Runtime.Remoting.Channels/ChannelServices.xml +++ b/xml/System.Runtime.Remoting.Channels/ChannelServices.xml @@ -24,7 +24,7 @@ ## Remarks Channels transport messages between applications across such remoting boundaries as application domains, processes, and computers. These crossings can be inbound and outbound. A channel can listen on an endpoint for inbound messages, send to an endpoint for outbound messages, or both. This provides an extensibility point in the runtime to plug in a wide range of protocols, even though the runtime might not be at the other end of the channel. Run-time objects can be used to expose a wide range of semantics and entities. The channel provides the extensibility point to convert the messages to and from the specific protocols. - Channels must expose the interface, which provides informational properties such as the and . Channels are registered using the method. Channels can also be loaded from the remoting configuration. (See [\ Element (Template)](http://msdn.microsoft.com/en-us/73399d48-f0fd-46e9-828b-6cdafde5ffce) for details.) + Channels must expose the interface, which provides informational properties such as the and . Channels are registered using the method. Channels can also be loaded from the remoting configuration. (See [\ Element (Template)](http://msdn.microsoft.com/en-us/73399d48-f0fd-46e9-828b-6cdafde5ffce) for details.) On the client side, messages are handed off to the client channel sink chain after they traverse the client chain. The first channel sink is typically a , which serializes the message into a stream that is passed down the channel sink chain to the client transport sink. The client transport sink then writes this stream out to the wire. @@ -267,7 +267,7 @@ > [!NOTE] > is obsolete. Please use instead. - The method takes in the interface from a channel object. The channel's must be unique, or the channel must be anonymous. A channel is anonymous if the is set to either `null` or by using the `name` configuration property. + The method takes in the interface from a channel object. The channel's must be unique, or the channel must be anonymous. A channel is anonymous if the is set to either `null` or by using the `name` configuration property. You cannot register two channels with the same name in a . By default, the name of a is "http" and the name of a is "tcp." Therefore, if you want to register two channels of the same type, you must specify a different name for one of them through configuration properties. @@ -314,7 +314,7 @@ method receives the interface from a channel object. The channel's must be unique, or the channel must be anonymous. A channel is anonymous if the is set to either `null` or by using the `name` configuration property. + The method receives the interface from a channel object. The channel's must be unique, or the channel must be anonymous. A channel is anonymous if the is set to either `null` or by using the `name` configuration property. You cannot register two channels with the same name in a . By default, the name of a is "http" and the name of a is "tcp". Therefore, if you want to register two channels of the same type, you must specify a different name for one of them through configuration properties. diff --git a/xml/System.Runtime.Remoting.Channels/ClientChannelSinkStack.xml b/xml/System.Runtime.Remoting.Channels/ClientChannelSinkStack.xml index 9b5ee7a5bbf71..55eaf25ff2f13 100644 --- a/xml/System.Runtime.Remoting.Channels/ClientChannelSinkStack.xml +++ b/xml/System.Runtime.Remoting.Channels/ClientChannelSinkStack.xml @@ -93,7 +93,7 @@ method initializes asynchronous processing on the top sink in the current sink stack. For additional information, see . + The method initializes asynchronous processing on the top sink in the current sink stack. For additional information, see . ]]> diff --git a/xml/System.Runtime.Remoting.Channels/IChannel.xml b/xml/System.Runtime.Remoting.Channels/IChannel.xml index 73641fa23504e..f173bd0220d81 100644 --- a/xml/System.Runtime.Remoting.Channels/IChannel.xml +++ b/xml/System.Runtime.Remoting.Channels/IChannel.xml @@ -25,7 +25,7 @@ The client part of the channel is located at the end of a client context sink chain. The server part of the channel is located at the start of the server context sink chain. Messages are delivered to the client channel using the interface, travel through the channel, and are then received by the server channel. The server channel delivers the message to the first server context sink. - Channels must expose the interface, which provides informational properties such as the and properties. Channels can be registered using the method. + Channels must expose the interface, which provides informational properties such as the and properties. Channels can be registered using the method. ]]> diff --git a/xml/System.Runtime.Remoting.Channels/IChannelReceiver.xml b/xml/System.Runtime.Remoting.Channels/IChannelReceiver.xml index 248e0b8460316..061a272fe4dde 100644 --- a/xml/System.Runtime.Remoting.Channels/IChannelReceiver.xml +++ b/xml/System.Runtime.Remoting.Channels/IChannelReceiver.xml @@ -56,7 +56,7 @@ is called and a is created. + This property is used when is called and a is created. ]]> @@ -88,7 +88,7 @@ method. + This method is used by the method. diff --git a/xml/System.Runtime.Remoting.Channels/IClientChannelSinkProvider.xml b/xml/System.Runtime.Remoting.Channels/IClientChannelSinkProvider.xml index c5c6269a5fa5d..e878aa81bcdd2 100644 --- a/xml/System.Runtime.Remoting.Channels/IClientChannelSinkProvider.xml +++ b/xml/System.Runtime.Remoting.Channels/IClientChannelSinkProvider.xml @@ -23,7 +23,7 @@ Channel sink providers are stored in a chain, and the user is responsible for chaining all channel sink providers together before passing the outer one to the channel constructor. provides a property called for this purpose. - When multiple channel sink providers are specified in a configuration file, the remoting infrastructure will chain them together in the order they are found in the configuration file. The channel sink providers will be created when the channel is created during the call. + When multiple channel sink providers are specified in a configuration file, the remoting infrastructure will chain them together in the order they are found in the configuration file. The channel sink providers will be created when the channel is created during the call. diff --git a/xml/System.Runtime.Remoting.Channels/IClientChannelSinkStack.xml b/xml/System.Runtime.Remoting.Channels/IClientChannelSinkStack.xml index 16e18b18fc90d..b84ab968cf350 100644 --- a/xml/System.Runtime.Remoting.Channels/IClientChannelSinkStack.xml +++ b/xml/System.Runtime.Remoting.Channels/IClientChannelSinkStack.xml @@ -25,7 +25,7 @@ ## Remarks The is used during processing of responses to asynchronous calls. - During a synchronous call, the method is called when a message is outbound to the server. Each sink in the sink chain calls the method on the next sink until the call reaches the transport sink at the end of the chain. From there the message is transported to the server. + During a synchronous call, the method is called when a message is outbound to the server. Each sink in the sink chain calls the method on the next sink until the call reaches the transport sink at the end of the chain. From there the message is transported to the server. When the formatter sink is called through the method, it dispatches the call asynchronously by calling on the next channel sink. A stack of reply sinks is needed to process the response. Any sink that wants to process the response needs to push itself to the client channel sink stack inside of . diff --git a/xml/System.Runtime.Remoting.Channels/IClientResponseChannelSinkStack.xml b/xml/System.Runtime.Remoting.Channels/IClientResponseChannelSinkStack.xml index 589212b7b4ea1..24e673ee6451e 100644 --- a/xml/System.Runtime.Remoting.Channels/IClientResponseChannelSinkStack.xml +++ b/xml/System.Runtime.Remoting.Channels/IClientResponseChannelSinkStack.xml @@ -43,7 +43,7 @@ method initializes asynchronous processing on the top sink in the current sink stack. For additional information, see . + The method initializes asynchronous processing on the top sink in the current sink stack. For additional information, see . ]]> diff --git a/xml/System.Runtime.Remoting.Channels/IServerChannelSinkProvider.xml b/xml/System.Runtime.Remoting.Channels/IServerChannelSinkProvider.xml index 020b69249db87..125d2c0669ae2 100644 --- a/xml/System.Runtime.Remoting.Channels/IServerChannelSinkProvider.xml +++ b/xml/System.Runtime.Remoting.Channels/IServerChannelSinkProvider.xml @@ -23,7 +23,7 @@ Channel sink providers are stored in a chain, and the user is responsible for chaining all channel sink providers together before passing the outer one to the channel constructor. provides a property called for this purpose. - When multiple channel sink providers are specified in a configuration file, the remoting infrastructure will chain them together in the order they are found in the configuration file. The channel sink providers are created at the same time as the channel, during a call. + When multiple channel sink providers are specified in a configuration file, the remoting infrastructure will chain them together in the order they are found in the configuration file. The channel sink providers are created at the same time as the channel, during a call. After the is generated, .NET Framework searches through the list of registered channels to find one that can process the call. Once an appropriate channel has been found, the channel sink is retrieved from the channel, and the is forwarded to the sink for processing. diff --git a/xml/System.Runtime.Remoting.Channels/ServerChannelSinkStack.xml b/xml/System.Runtime.Remoting.Channels/ServerChannelSinkStack.xml index 278bf7757f0db..98f246f3003d3 100644 --- a/xml/System.Runtime.Remoting.Channels/ServerChannelSinkStack.xml +++ b/xml/System.Runtime.Remoting.Channels/ServerChannelSinkStack.xml @@ -110,7 +110,7 @@ called with the `msg` and `headers` parameters ( (`msg`, `headers`)) on the top sink in the current sink stack. The top sink in the sink stack remains unchanged. + This method returns the stream returned by the called with the `msg` and `headers` parameters ( (`msg`, `headers`)) on the top sink in the current sink stack. The top sink in the sink stack remains unchanged. ]]> diff --git a/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSink.xml b/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSink.xml index a516ad39e4c7f..ad66de776dfff 100644 --- a/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSink.xml +++ b/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSink.xml @@ -20,7 +20,7 @@ method, which is called by server channels to create the server channel sink chains. When the message reaches the dispatch sink, the dispatch sink passes the message to the remoting infrastructure. + The request stream propagates from the server transport sink through the server channel sinks until it reaches the appropriate formatter sink. The formatter sink deserializes the message and passes it through the pipeline. A special dispatch sink is inserted at the end of the channel sink chain by method, which is called by server channels to create the server channel sink chains. When the message reaches the dispatch sink, the dispatch sink passes the message to the remoting infrastructure. |Property|Description| |--------------|-----------------| diff --git a/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSinkProvider.xml b/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSinkProvider.xml index 29ea5189c0e79..376a988338538 100644 --- a/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSinkProvider.xml +++ b/xml/System.Runtime.Remoting.Channels/SoapServerFormatterSinkProvider.xml @@ -24,7 +24,7 @@ Channel sink providers are stored in a chain, and the user is responsible for chaining all channel sink providers together before passing the outer one to the channel constructor. provides a property called for this purpose. - When multiple channel sink providers are specified in a configuration file, the remoting infrastructure will chain them together in the order they are found in the configuration file. The channel sink providers and the channels are created during the call. + When multiple channel sink providers are specified in a configuration file, the remoting infrastructure will chain them together in the order they are found in the configuration file. The channel sink providers and the channels are created during the call. Formatter sinks use sink configuration properties to configure the channel at run time. Sink properties can be specified in a configuration file, or programmatically, inside of a . In a configuration file all values are represented by strings, but when building a property programmatically, value types can be specified with their native values or with strings. diff --git a/xml/System.Runtime.Remoting.Contexts/SynchronizationAttribute.xml b/xml/System.Runtime.Remoting.Contexts/SynchronizationAttribute.xml index b73d7da366cb9..51a105777abae 100644 --- a/xml/System.Runtime.Remoting.Contexts/SynchronizationAttribute.xml +++ b/xml/System.Runtime.Remoting.Contexts/SynchronizationAttribute.xml @@ -35,7 +35,7 @@ When this attribute is applied to an object, only one thread can be executing in all contexts that share an instance of this property. This is done by contributing sinks that intercept and serialize incoming calls for the respective contexts. If the property is marked for reentry, then callouts are intercepted too. The callout interception allows other waiting threads to enter the synchronization domain for maximal throughput. > [!NOTE] -> There are two classes named `SynchronizationAttribute` : one in the namespace, and the other in the namespace. The class supports only synchronous calls, and can be used only with serviced components. (For more information on serviced components, see [[\]](http://msdn.microsoft.com/en-us/5133a620-9c8c-47bd-8e36-130e722fe463).) The supports both synchronous and asynchronous calls, and can be used only with context bound objects. (For more information on context bound objects, see the class.) +> There are two classes named `SynchronizationAttribute` : one in the namespace, and the other in the namespace. The class supports only synchronous calls, and can be used only with serviced components. (For more information on serviced components, see [[\]](http://msdn.microsoft.com/en-us/5133a620-9c8c-47bd-8e36-130e722fe463).) The supports both synchronous and asynchronous calls, and can be used only with context bound objects. (For more information on context bound objects, see the class.) > [!NOTE] > This class makes a link demand and an inheritance demand at the class level. A is thrown when either the immediate caller or the derived class does not have infrastructure permission. For details about security demands, see [Link Demands](~/docs/framework/misc/link-demands.md) and [Inheritance Demands](http://msdn.microsoft.com/en-us/28b9adbb-8f08-4f10-b856-dbf59eb932d9). @@ -177,7 +177,7 @@ . + The current method is an implementation of . ]]> @@ -234,7 +234,7 @@ . + The current method is an implementation of . ]]> diff --git a/xml/System.Runtime.Remoting.Lifetime/ClientSponsor.xml b/xml/System.Runtime.Remoting.Lifetime/ClientSponsor.xml index fb5feca24b432..f5f51b6a3972b 100644 --- a/xml/System.Runtime.Remoting.Lifetime/ClientSponsor.xml +++ b/xml/System.Runtime.Remoting.Lifetime/ClientSponsor.xml @@ -62,7 +62,7 @@ property. + The default time by which the lifetime of a sponsored object is increased when renewal is requested to 2 minutes. For more information on the renewal time, see the property. ]]> @@ -155,7 +155,7 @@ . + For more information, see . diff --git a/xml/System.Runtime.Remoting.Lifetime/ILease.xml b/xml/System.Runtime.Remoting.Lifetime/ILease.xml index b9b82e77bc9e4..3d8441823a0e1 100644 --- a/xml/System.Runtime.Remoting.Lifetime/ILease.xml +++ b/xml/System.Runtime.Remoting.Lifetime/ILease.xml @@ -95,7 +95,7 @@ property is set to , then the lease will never time out and the object associated with it will have an infinite lifetime. + If the property is set to , then the lease will never time out and the object associated with it will have an infinite lifetime. ]]> @@ -240,7 +240,7 @@ is , then this lease will not take sponsors. + If the is , then this lease will not take sponsors. If a sponsor does not respond to a call to renew a lease within the time-out period, it is assumed to be dead and is removed from the list of sponsors for the current lease. diff --git a/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml b/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml index 5ac21456d888e..7b41c70447087 100644 --- a/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml +++ b/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml @@ -193,10 +193,10 @@ ## Remarks The returned by this method is automatically signaled when the asynchronous operation has completed. - The wait handle is not closed automatically when you call `EndInvoke` on the delegate that was used to make the asynchronous method call. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, call the method. Garbage collection works more efficiently when disposable objects are explicitly closed or disposed. + The wait handle is not closed automatically when you call `EndInvoke` on the delegate that was used to make the asynchronous method call. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, call the method. Garbage collection works more efficiently when disposable objects are explicitly closed or disposed. > [!CAUTION] -> The contained in the property can be used to block the current thread until the asynchronous call is complete. However the will ignore the , if one was specified during the `BeginInvoke` call. Therefore, a situation can occur where the application shuts down before the has finished executing, even if a is used to block until the asynchronous call completion. For an example of such a situation, see the example for the class, and remove the statement. +> The contained in the property can be used to block the current thread until the asynchronous call is complete. However the will ignore the , if one was specified during the `BeginInvoke` call. Therefore, a situation can occur where the application shuts down before the has finished executing, even if a is used to block until the asynchronous call completion. For an example of such a situation, see the example for the class, and remove the statement. diff --git a/xml/System.Runtime.Remoting.Messaging/IMethodReturnMessage.xml b/xml/System.Runtime.Remoting.Messaging/IMethodReturnMessage.xml index 7c2028f47fbc5..00e155f72b054 100644 --- a/xml/System.Runtime.Remoting.Messaging/IMethodReturnMessage.xml +++ b/xml/System.Runtime.Remoting.Messaging/IMethodReturnMessage.xml @@ -175,7 +175,7 @@ Although the property is redundant since the same functionality can be achieved through the field and method, there might be performance optimization available if the implementer understands when all the arguments will be retrieved. > [!WARNING] -> If is not `null`, a exception is thrown when is accessed. +> If is not `null`, a exception is thrown when is accessed. diff --git a/xml/System.Runtime.Remoting.Proxies/RealProxy.xml b/xml/System.Runtime.Remoting.Proxies/RealProxy.xml index bec0d0551f0db..2559c1b6c9c01 100644 --- a/xml/System.Runtime.Remoting.Proxies/RealProxy.xml +++ b/xml/System.Runtime.Remoting.Proxies/RealProxy.xml @@ -495,7 +495,7 @@ ## Remarks When the transparent proxy that is backed by the is called, it delegates the calls to the method. The method transforms the message in the `msg` parameter into a , and sends it to the remote object that is represented by the current instance of . - The parameter provides a dictionary through the property. The dictionary contains name/value pairs of information about the method call, such as the name of the method called and its parameters. + The parameter provides a dictionary through the property. The dictionary contains name/value pairs of information about the method call, such as the name of the method called and its parameters. diff --git a/xml/System.Runtime.Remoting.Services/EnterpriseServicesHelper.xml b/xml/System.Runtime.Remoting.Services/EnterpriseServicesHelper.xml index fc34da95f99bd..a33cb28844046 100644 --- a/xml/System.Runtime.Remoting.Services/EnterpriseServicesHelper.xml +++ b/xml/System.Runtime.Remoting.Services/EnterpriseServicesHelper.xml @@ -136,7 +136,7 @@ method is similar to the method, but does not attempt to maintain the identity of the unmanaged object. For example, two calls with the same `IUnknown` to the current method return two different RCWs, but two calls to the method with the same `IUnknown` return the same RCW. + The method is similar to the method, but does not attempt to maintain the identity of the unmanaged object. For example, two calls with the same `IUnknown` to the current method return two different RCWs, but two calls to the method with the same `IUnknown` return the same RCW. ]]> diff --git a/xml/System.Runtime.Remoting/ActivatedClientTypeEntry.xml b/xml/System.Runtime.Remoting/ActivatedClientTypeEntry.xml index c8dce044d6372..85b9e13734ec2 100644 --- a/xml/System.Runtime.Remoting/ActivatedClientTypeEntry.xml +++ b/xml/System.Runtime.Remoting/ActivatedClientTypeEntry.xml @@ -24,7 +24,7 @@ ## Remarks To create an instance of a client-activated object on the client, you must know its and it must be registered on the client by using the method. To obtain a proxy for a new instance of the client-activated object the client must first register a channel with and then activate the object by calling `new`. - To activate a client-activated object type with the `new` keyword, you must first register the object type on the client using the method. By calling you are giving the remoting infrastructure the location of the remote application where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client end is necessary. To supply the method with the URL of the server on which you want to create the object, you must encapsulate the URL in an instance of the class. + To activate a client-activated object type with the `new` keyword, you must first register the object type on the client using the method. By calling you are giving the remoting infrastructure the location of the remote application where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client end is necessary. To supply the method with the URL of the server on which you want to create the object, you must encapsulate the URL in an instance of the class. For a detailed description of client activated objects and remote object activation see [[\]](http://msdn.microsoft.com/en-us/e90d0c64-00da-4080-ae78-a6c558825c25). diff --git a/xml/System.Runtime.Remoting/ActivatedServiceTypeEntry.xml b/xml/System.Runtime.Remoting/ActivatedServiceTypeEntry.xml index e4c534bfedb31..3d70ef9ce6fec 100644 --- a/xml/System.Runtime.Remoting/ActivatedServiceTypeEntry.xml +++ b/xml/System.Runtime.Remoting/ActivatedServiceTypeEntry.xml @@ -22,9 +22,9 @@ method, which is the server-side counterpart of the method. The method is used on the server to allow remote activation by clients of specified object types. + The current class is used by the method, which is the server-side counterpart of the method. The method is used on the server to allow remote activation by clients of specified object types. - To create a client-activated object on the server, you must know its , and it must be registered on the server end by using the method. To obtain a proxy for a new client-activated object, the client must first register a channel with and then activate the object by calling `new` or . + To create a client-activated object on the server, you must know its , and it must be registered on the server end by using the method. To obtain a proxy for a new client-activated object, the client must first register a channel with and then activate the object by calling `new` or . To activate a client-activated object type with the `new` keyword, you must first register the object type on the client using the method. By calling you are giving the remoting infrastructure the location of the remote application where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client is necessary. To supply the method with the URL of the server on which you want to create the object, you must encapsulate the URL in an instance of the class. diff --git a/xml/System.Runtime.Remoting/IChannelInfo.xml b/xml/System.Runtime.Remoting/IChannelInfo.xml index 5aae6fa37a05b..3b121b06e23da 100644 --- a/xml/System.Runtime.Remoting/IChannelInfo.xml +++ b/xml/System.Runtime.Remoting/IChannelInfo.xml @@ -19,7 +19,7 @@ property. It provides access to transport specific information contributed by the channels that are able to receive calls in the process or application domain where the object lives. This interface might also be used when building custom classes. + This interface is implemented by the property. It provides access to transport specific information contributed by the channels that are able to receive calls in the process or application domain where the object lives. This interface might also be used when building custom classes. When an existing object instance is marshaled to produce a , the is copied from the channel (see ) for each registered channel and stored in the . When the is unmarshaled at its destination, the provided through the interface can be examined and used by corresponding channels in that process or application domain to create a transport message sink that manages the communication between the proxy and the server object. diff --git a/xml/System.Runtime.Remoting/ObjRef.xml b/xml/System.Runtime.Remoting/ObjRef.xml index bef6477c6ca03..94bae9b705c33 100644 --- a/xml/System.Runtime.Remoting/ObjRef.xml +++ b/xml/System.Runtime.Remoting/ObjRef.xml @@ -29,7 +29,7 @@ is a serializable representation of an object that extends (MBR). A is used to transfer an object reference across a boundary. Creating a for an object is known as marshaling. You can create a (marshal a ) either explicitly, by registering the MBR object with the remoting infrastructure (see and ), or implicitly, by passing an MBR object as a parameter when calling a remote object. Remoting uses objects to store and transmit all the relevant information about the being remoted. + A is a serializable representation of an object that extends (MBR). A is used to transfer an object reference across a boundary. Creating a for an object is known as marshaling. You can create a (marshal a ) either explicitly, by registering the MBR object with the remoting infrastructure (see and ), or implicitly, by passing an MBR object as a parameter when calling a remote object. Remoting uses objects to store and transmit all the relevant information about the being remoted. The contains information that describes the and class of the object being marshaled, its exact location, and communication-related information on how to reach the remoting subdivision where the object is located. diff --git a/xml/System.Runtime.Remoting/RemotingConfiguration.xml b/xml/System.Runtime.Remoting/RemotingConfiguration.xml index 43e214d6abd42..0d6381e00510d 100644 --- a/xml/System.Runtime.Remoting/RemotingConfiguration.xml +++ b/xml/System.Runtime.Remoting/RemotingConfiguration.xml @@ -129,7 +129,7 @@ For configuration file syntax, see [Remoting Settings Schema](http://msdn.microsoft.com/en-us/dc2d1e62-9af7-4ca1-99fd-98b93bb4db9e). > [!NOTE] -> Marshal-by-reference objects (MBRs) do not reside in memory forever. Instead, unless the type overrides to control its own lifetime policies, each MBR has a finite lifetime before the .NET Framework remoting system begins the process of deleting it and reclaiming the memory. For more information, see [Lifetime Leases](http://msdn.microsoft.com/en-us/c72d561c-1266-4c8b-b258-2c168c08da9a). +> Marshal-by-reference objects (MBRs) do not reside in memory forever. Instead, unless the type overrides to control its own lifetime policies, each MBR has a finite lifetime before the .NET Framework remoting system begins the process of deleting it and reclaiming the memory. For more information, see [Lifetime Leases](http://msdn.microsoft.com/en-us/c72d561c-1266-4c8b-b258-2c168c08da9a). @@ -174,7 +174,7 @@ For configuration file syntax, see [Remoting Settings Schema](http://msdn.microsoft.com/en-us/dc2d1e62-9af7-4ca1-99fd-98b93bb4db9e). > [!NOTE] -> Marshal-by-reference objects (MBRs) do not reside in memory forever. Instead, unless the type overrides to control its own lifetime policies, each MBR has a finite lifetime before the .NET Framework remoting system begins the process of deleting it and reclaiming the memory. For more information, see [Lifetime Leases](http://msdn.microsoft.com/en-us/c72d561c-1266-4c8b-b258-2c168c08da9a). +> Marshal-by-reference objects (MBRs) do not reside in memory forever. Instead, unless the type overrides to control its own lifetime policies, each MBR has a finite lifetime before the .NET Framework remoting system begins the process of deleting it and reclaiming the memory. For more information, see [Lifetime Leases](http://msdn.microsoft.com/en-us/c72d561c-1266-4c8b-b258-2c168c08da9a). ]]> @@ -624,7 +624,7 @@ ## Remarks To create an instance of a client-activated object on the server, you must know its and it must be registered on the server end by using the method. To obtain a proxy for a new instance of the client-activated object, the client must first register a channel with and then activate the object by calling `new`. - To activate a client-activated object type with the `new` keyword, you must first register the object type on the client end using the method. Calling the method gives the remoting infrastructure the location of the remote application where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client end is necessary. To supply the method with the URL of the server where you want to create the object, you must encapsulate the URL in an instance of the class. + To activate a client-activated object type with the `new` keyword, you must first register the object type on the client end using the method. Calling the method gives the remoting infrastructure the location of the remote application where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client end is necessary. To supply the method with the URL of the server where you want to create the object, you must encapsulate the URL in an instance of the class. For a detailed description of client-activated objects, see [[\]](http://msdn.microsoft.com/en-us/4a791494-c18a-4711-a5c1-4ab0e49a8f1a). @@ -661,7 +661,7 @@ ## Remarks To create an instance of a client-activated object on the server, you must know its and it must be registered on the server end by using the method. To obtain a proxy for a new instance of the client-activated object, the client must first register a channel with and then activate the object by calling `new`. - To activate a client-activated object type with the `new` keyword, you must first register the object type on the client end using the method. Calling the method gives the remoting infrastructure the location of the remote application where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client end is necessary. To supply the method with the URL of the server where you want to create the object, you must encapsulate the URL in an instance of the class. + To activate a client-activated object type with the `new` keyword, you must first register the object type on the client end using the method. Calling the method gives the remoting infrastructure the location of the remote application where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client end is necessary. To supply the method with the URL of the server where you want to create the object, you must encapsulate the URL in an instance of the class. For a detailed description of client-activated objects, see [[\]](http://msdn.microsoft.com/en-us/4a791494-c18a-4711-a5c1-4ab0e49a8f1a) @@ -704,7 +704,7 @@ and it must be registered on the server end by using the method. To obtain a proxy for a new instance of the client-activated object, the client must first register a channel with and then activate the object by calling `new` or . + To create an instance of a client-activated object on the server, you must know its and it must be registered on the server end by using the method. To obtain a proxy for a new instance of the client-activated object, the client must first register a channel with and then activate the object by calling `new` or . To activate a client-activated object type with the `new` keyword, you must first register the object type on the client end using the method. Calling the method gives the remoting infrastructure the location of the remote application, where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client end is necessary. To supply the method with the URL of the server where you want to create the object, you must encapsulate the URL in an instance of the class. @@ -739,7 +739,7 @@ and it must be registered on the server end by using the method. To obtain a proxy for a new instance of the client-activated object, the client must first register a channel with and then activate the object by calling `new` or . + To create an instance of a client-activated object on the server, you must know its and it must be registered on the server end by using the method. To obtain a proxy for a new instance of the client-activated object, the client must first register a channel with and then activate the object by calling `new` or . To activate a client-activated object type with the `new` keyword, you must first register the object type on the client end using the method. Calling the method gives the remoting infrastructure the location of the remote application, where `new` attempts to create it. If, on the other hand, you use the method to create a new instance of the client-activated object, you must supply the remote application's URL as a parameter, so no prior registration on the client end is necessary. To supply the method with the URL of the server where you want to create the object, you must encapsulate the URL in an instance of the class. @@ -789,7 +789,7 @@ , and activating the object by calling `new` or . To activate a well-known object with `new`, you must first register the well-known object type on the client using the method. Calling the method gives the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate the well-known object, you must supply it with the object's URL as an argument, so no prior registration on the client end is necessary. + Any client that knows the URI of a registered well-known object can obtain a proxy for the object by registering the channel it prefers with , and activating the object by calling `new` or . To activate a well-known object with `new`, you must first register the well-known object type on the client using the method. Calling the method gives the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate the well-known object, you must supply it with the object's URL as an argument, so no prior registration on the client end is necessary. For a detailed description of well-known objects, see [[\]](http://msdn.microsoft.com/en-us/77ded6e2-4ca8-448b-acf2-562d27fd4396). @@ -824,7 +824,7 @@ , and activating the object by calling `new` or . To activate a well-known object with `new`, you must first register the well-known object type on the client using the method. Calling the method gives the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate the well-known object, you must supply it with the object's URL as an argument, so no prior registration on the client end is necessary. + Any client that knows the URI of a registered well-known object can obtain a proxy for the object by registering the channel it prefers with , and activating the object by calling `new` or . To activate a well-known object with `new`, you must first register the well-known object type on the client using the method. Calling the method gives the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate the well-known object, you must supply it with the object's URL as an argument, so no prior registration on the client end is necessary. For a detailed description of well-known objects, see [[\]](http://msdn.microsoft.com/en-us/77ded6e2-4ca8-448b-acf2-562d27fd4396). @@ -872,9 +872,9 @@ , and activating the object by calling `new` or the method. To activate a well-known object with `new`, you must first register the well-known object type on the client using the method. Calling the method gives the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate the well-known object, you must supply it with the object's URL as an argument, so no prior registration on the client end is necessary. + Any client that knows the URI of a registered well-known object can obtain a proxy for the object by registering the channel it prefers with , and activating the object by calling `new` or the method. To activate a well-known object with `new`, you must first register the well-known object type on the client using the method. Calling the method gives the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate the well-known object, you must supply it with the object's URL as an argument, so no prior registration on the client end is necessary. - When the call arrives at the server, the .NET Framework extracts the URI from the message, examines the remoting tables to locate the reference for the object that matches the URI, and then instantiates the object if necessary, forwarding the method call to the object. If the object is registered as , it is destroyed after the method call is completed. A new instance of the object is created for each method called. The only difference between and `new` is that the former allows you to specify a URL as a parameter, and the latter obtains the URL from the configuration. + When the call arrives at the server, the .NET Framework extracts the URI from the message, examines the remoting tables to locate the reference for the object that matches the URI, and then instantiates the object if necessary, forwarding the method call to the object. If the object is registered as , it is destroyed after the method call is completed. A new instance of the object is created for each method called. The only difference between and `new` is that the former allows you to specify a URL as a parameter, and the latter obtains the URL from the configuration. The remote object itself is not instantiated by the registration process. This only happens when a client attempts to call a method on the object or activates the object from the client side. @@ -920,9 +920,9 @@ , and activating the object by calling `new` or the method. To activate a well-known object with `new`, you must first register the well-known object type on the client using the method. Calling the method gives the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate the well-known object, you must supply it with the object's URL as an argument, so no prior registration on the client end is necessary. + Any client that knows the URI of a registered well-known object can obtain a proxy for the object by registering the channel it prefers with , and activating the object by calling `new` or the method. To activate a well-known object with `new`, you must first register the well-known object type on the client using the method. Calling the method gives the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate the well-known object, you must supply it with the object's URL as an argument, so no prior registration on the client end is necessary. - When the call arrives at the server, the .NET Framework extracts the URI from the message, examines the remoting tables to locate the reference for the object that matches the URI, and then instantiates the object if necessary, forwarding the method call to the object. If the object is registered as , it is destroyed after the method call is completed. A new instance of the object is created for each method called. The only difference between and `new` is that the former allows you to specify a URL as a parameter, and the latter obtains the URL from the configuration. + When the call arrives at the server, the .NET Framework extracts the URI from the message, examines the remoting tables to locate the reference for the object that matches the URI, and then instantiates the object if necessary, forwarding the method call to the object. If the object is registered as , it is destroyed after the method call is completed. A new instance of the object is created for each method called. The only difference between and `new` is that the former allows you to specify a URL as a parameter, and the latter obtains the URL from the configuration. The remote object itself is not instantiated by the registration process. This only happens when a client attempts to call a method on the object or activates the object from the client side. diff --git a/xml/System.Runtime.Remoting/RemotingServices.xml b/xml/System.Runtime.Remoting/RemotingServices.xml index 797d3f5bbdea1..8be2fffa2221b 100644 --- a/xml/System.Runtime.Remoting/RemotingServices.xml +++ b/xml/System.Runtime.Remoting/RemotingServices.xml @@ -111,7 +111,7 @@ ## Remarks The returned proxy object points to an endpoint served by the specified well-known object. No messages are sent over the network until a method is called on the proxy. - The `data` object is used to communicate information to the channel, and is passed to the method. + The `data` object is used to communicate information to the channel, and is passed to the method. ]]> @@ -311,7 +311,7 @@ , , and properties of and is used by classes implementing the interface. Consumers of classes should reference the property. + This determines the method base from the , , and properties of and is used by classes implementing the interface. Consumers of classes should reference the property. ]]> diff --git a/xml/System.Runtime.Remoting/SoapServices.xml b/xml/System.Runtime.Remoting/SoapServices.xml index bf24721dee9af..1cfa5b099b635 100644 --- a/xml/System.Runtime.Remoting/SoapServices.xml +++ b/xml/System.Runtime.Remoting/SoapServices.xml @@ -800,7 +800,7 @@ property, or is read off the wire. The current method associates the SOAPAction with the for use in channel sinks. + The SOAPAction of the specified method is contained in the property, or is read off the wire. The current method associates the SOAPAction with the for use in channel sinks. The SOAPAction HTTP request header field indicates the intent of the SOAP HTTP request. The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or that it is resolvable. An HTTP client must use this header field when issuing a SOAP HTTP request. diff --git a/xml/System.Runtime.Remoting/WellKnownClientTypeEntry.xml b/xml/System.Runtime.Remoting/WellKnownClientTypeEntry.xml index c050fc3a194ef..7c5ada9ef29b1 100644 --- a/xml/System.Runtime.Remoting/WellKnownClientTypeEntry.xml +++ b/xml/System.Runtime.Remoting/WellKnownClientTypeEntry.xml @@ -24,7 +24,7 @@ ## Remarks Server-activated types can be either single call or singleton. If a class is registered as a single call type, a new instance is created each time a call from the client arrives. All calls to a singleton object are handled by one instance of that object, unless that object has been collected. - Any client that knows the URI of a registered server-activated object can obtain a proxy for this object by registering the channel it prefers with and activating the object by calling `new` or . To activate a server-activated object with `new`, you must first register the server-activated object type on the client using the method. By calling , you are giving the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate a server-activated object, you must supply it with the object's URL as an argument, so no prior registration on the client is necessary. + Any client that knows the URI of a registered server-activated object can obtain a proxy for this object by registering the channel it prefers with and activating the object by calling `new` or . To activate a server-activated object with `new`, you must first register the server-activated object type on the client using the method. By calling , you are giving the remoting infrastructure the location of the remote object, which allows the `new` keyword to create it. If, on the other hand, you use the method to activate a server-activated object, you must supply it with the object's URL as an argument, so no prior registration on the client is necessary. For a detailed description of server-activated objects and remote object activation, see [[\]](http://msdn.microsoft.com/en-us/e90d0c64-00da-4080-ae78-a6c558825c25). diff --git a/xml/System.Runtime.Remoting/WellKnownObjectMode.xml b/xml/System.Runtime.Remoting/WellKnownObjectMode.xml index 167417d44a0bc..6a79dd4cca11d 100644 --- a/xml/System.Runtime.Remoting/WellKnownObjectMode.xml +++ b/xml/System.Runtime.Remoting/WellKnownObjectMode.xml @@ -21,7 +21,7 @@ method on the server side. + Well-known objects are objects exposed on the server end. The current enumerator is used by the method on the server side. ]]> diff --git a/xml/System.Runtime.Remoting/WellKnownServiceTypeEntry.xml b/xml/System.Runtime.Remoting/WellKnownServiceTypeEntry.xml index 43757fd9f9d5d..ee5987392d4c3 100644 --- a/xml/System.Runtime.Remoting/WellKnownServiceTypeEntry.xml +++ b/xml/System.Runtime.Remoting/WellKnownServiceTypeEntry.xml @@ -24,7 +24,7 @@ ## Remarks Server-activated object types can be either single call or singleton. If an object type is single call, a new instance of it is created each time a call from the client comes in. All calls to a singleton object are handled by one instance of that object. - Any client that knows the URI of this object can obtain a proxy for this object by registering the channel it prefers with and activating the object by calling `new` or . + Any client that knows the URI of this object can obtain a proxy for this object by registering the channel it prefers with and activating the object by calling `new` or . It is important to note that the remote object itself is not created by the registration process. This only happens when a client attempts to call a method on the object or activates the object from the client side. diff --git a/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml b/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml index 138067d5e0dc5..92af59725d6d2 100644 --- a/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml +++ b/xml/System.Runtime.Serialization.Formatters.Binary/BinaryFormatter.xml @@ -120,7 +120,7 @@ |Property Type|Condition| |-------------------|---------------| ||`null`| -||A with a value that indicates that serialized data can be transmitted to or received from any of the other contexts. ()| +||A with a value that indicates that serialized data can be transmitted to or received from any of the other contexts. ()| @@ -663,7 +663,7 @@ ## Remarks Headers are used only for specific remoting applications. - This method uses to prevent it from being called from untrusted code; only the immediate caller is required to have permission. Do not use this method if your code can be called from partially trusted code. In partially trusted scenarios, use instead. In full trust scenarios, provides better performance than . + This method uses to prevent it from being called from untrusted code; only the immediate caller is required to have permission. Do not use this method if your code can be called from partially trusted code. In partially trusted scenarios, use instead. In full trust scenarios, provides better performance than . For successful deserialization, the current position in the stream must be at the beginning of the object graph. @@ -716,7 +716,7 @@ ## Remarks Details about the caller object are not sent to the remote object during the method call. Instead, these details are obtained from the original method call that is passed to the current method in the `methodCallMessage` parameter. - This method uses to prevent it from being called from untrusted code; only the immediate caller is required to have permission. Do not use this method if your code can be called from partially trusted code. In partially trusted scenarios, use instead. In full trust scenarios, provides better performance than . + This method uses to prevent it from being called from untrusted code; only the immediate caller is required to have permission. Do not use this method if your code can be called from partially trusted code. In partially trusted scenarios, use instead. In full trust scenarios, provides better performance than . For successful deserialization, the current position in the stream must be at the beginning of the object graph. diff --git a/xml/System.Runtime.Serialization.Formatters/IFieldInfo.xml b/xml/System.Runtime.Serialization.Formatters/IFieldInfo.xml index fb4d94e7051ed..c6b4df38a8cfc 100644 --- a/xml/System.Runtime.Serialization.Formatters/IFieldInfo.xml +++ b/xml/System.Runtime.Serialization.Formatters/IFieldInfo.xml @@ -56,7 +56,7 @@ ## Remarks If a name is `null`, a default parameter name is used. - This property's `get` and `set` accessors are protected by a for the with the specified. + This property's `get` and `set` accessors are protected by a for the with the specified. ]]> @@ -95,7 +95,7 @@ for the with the specified. + This property's `get` and `set` accessors are protected by a for the with the specified. ]]> diff --git a/xml/System.Runtime.Serialization.Formatters/ISoapMessage.xml b/xml/System.Runtime.Serialization.Formatters/ISoapMessage.xml index d059c07d8e4bf..90625294e7348 100644 --- a/xml/System.Runtime.Serialization.Formatters/ISoapMessage.xml +++ b/xml/System.Runtime.Serialization.Formatters/ISoapMessage.xml @@ -21,7 +21,7 @@ ## Remarks When an object that supports this interface is the root of a serialization graph, SOAP is produced in RPC format. The interface contains the method call parameter types used during deserialization of a method call. - To support SOAP RPC calls that are based on the interface and do not use the functionality, set the property to an object that supports this interface. + To support SOAP RPC calls that are based on the interface and do not use the functionality, set the property to an object that supports this interface. ]]> diff --git a/xml/System.Runtime.Serialization.Formatters/SoapMessage.xml b/xml/System.Runtime.Serialization.Formatters/SoapMessage.xml index 9068e7ee04e6b..74fcd47b56861 100644 --- a/xml/System.Runtime.Serialization.Formatters/SoapMessage.xml +++ b/xml/System.Runtime.Serialization.Formatters/SoapMessage.xml @@ -26,7 +26,7 @@ is the root of a serialization graph, SOAP is produced in RPC (Remote Procedure Call) format and a object is used to specify the method call parameter types. The property can be set to this object during deserialization. + When is the root of a serialization graph, SOAP is produced in RPC (Remote Procedure Call) format and a object is used to specify the method call parameter types. The property can be set to this object during deserialization. ]]> diff --git a/xml/System.Runtime.Serialization/ExportOptions.xml b/xml/System.Runtime.Serialization/ExportOptions.xml index 67c2a1cf1c049..7602a3871fc03 100644 --- a/xml/System.Runtime.Serialization/ExportOptions.xml +++ b/xml/System.Runtime.Serialization/ExportOptions.xml @@ -118,7 +118,7 @@ property is used by the to include types that can be read in an object graph (set using the property). + The property is used by the to include types that can be read in an object graph (set using the property). [!INCLUDE[crabout](~/includes/crabout-md.md)] the data contract and known types, see [Data Contract Known Types](~/docs/framework/wcf/feature-details/data-contract-known-types.md). diff --git a/xml/System.Runtime.Serialization/FormatterConverter.xml b/xml/System.Runtime.Serialization/FormatterConverter.xml index 56c6ab280cb9c..7196e22f94bbf 100644 --- a/xml/System.Runtime.Serialization/FormatterConverter.xml +++ b/xml/System.Runtime.Serialization/FormatterConverter.xml @@ -157,7 +157,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and .) + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and .) ]]> @@ -196,7 +196,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , and . ]]> @@ -235,7 +235,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -274,7 +274,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -313,7 +313,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -352,7 +352,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -391,7 +391,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -430,7 +430,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -469,7 +469,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -513,7 +513,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -552,7 +552,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -591,7 +591,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -635,7 +635,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -679,7 +679,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> @@ -723,7 +723,7 @@ ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . + This method uses the invariant culture (see ). To use the current culture or to specify a culture, use the method instead. For more information, see , , and . ]]> diff --git a/xml/System.Runtime.Serialization/IObjectReference.xml b/xml/System.Runtime.Serialization/IObjectReference.xml index dc351b648ad98..2f9a03a13231b 100644 --- a/xml/System.Runtime.Serialization/IObjectReference.xml +++ b/xml/System.Runtime.Serialization/IObjectReference.xml @@ -79,7 +79,7 @@ For example, consider how objects are serialized. Instead of transmitting the data from the object, the system transmits a holder object with the name of the type object and information on the assembly where it is found in an object implementing . When both the type name and assembly name are available, the deserialization infrastructure calls on the holder object that has been transmitted. This holder returns the object that is inserted into the graph. - This method is protected by a for the with the specified. + This method is protected by a for the with the specified. diff --git a/xml/System.Runtime.Serialization/ISerializable.xml b/xml/System.Runtime.Serialization/ISerializable.xml index 7c6950398317e..399c268eab2f2 100644 --- a/xml/System.Runtime.Serialization/ISerializable.xml +++ b/xml/System.Runtime.Serialization/ISerializable.xml @@ -109,7 +109,7 @@ ## Remarks Any objects that are included in the are automatically tracked and serialized by the formatter. - Code that calls requires the for providing serialization services. Associated enumeration: . + Code that calls requires the for providing serialization services. Associated enumeration: . > [!NOTE] > It is not guaranteed that this method will be called only once per object instance during serialization. Therefore, the method should be implemented in such a way that its behavior will be the same regardless of the number of times it is called. diff --git a/xml/System.Runtime.Serialization/ISerializationSurrogate.xml b/xml/System.Runtime.Serialization/ISerializationSurrogate.xml index 671ddbc8f86bc..f6206f7ff2808 100644 --- a/xml/System.Runtime.Serialization/ISerializationSurrogate.xml +++ b/xml/System.Runtime.Serialization/ISerializationSurrogate.xml @@ -70,7 +70,7 @@ Having located the surrogate, this method stores information on the object `obj` in the `info` parameter. This information describes its view of that object, including the object's fields, properties, and current values. The might correspond to the actual object, or it can be a synthesized view of the surrogate. - This method is protected by a for the with the specified. + This method is protected by a for the with the specified. ]]> @@ -122,7 +122,7 @@ ## Remarks The method is called during deserialization. With this method, you can take the empty `obj` that has already been created, and enter `info` data into that object. Constructors are not invoked during deserialization of information and reconstruction of the object. - This method is protected by a for the with the specified. + This method is protected by a for the with the specified. ]]> diff --git a/xml/System.Runtime.Serialization/ISurrogateSelector.xml b/xml/System.Runtime.Serialization/ISurrogateSelector.xml index 3258e16764b1c..cb72d8eb0a72b 100644 --- a/xml/System.Runtime.Serialization/ISurrogateSelector.xml +++ b/xml/System.Runtime.Serialization/ISurrogateSelector.xml @@ -69,7 +69,7 @@ for the with the specified. + This method is protected by a for the with the specified. ]]> @@ -110,7 +110,7 @@ for the with the specified. + This method is protected by a for the with the specified. ]]> @@ -158,7 +158,7 @@ for the with the specified. + This method is protected by a for the with the specified. ]]> diff --git a/xml/System.Runtime.Serialization/NetDataContractSerializer.xml b/xml/System.Runtime.Serialization/NetDataContractSerializer.xml index 0a6e7ba3045bc..f184b67b680dd 100644 --- a/xml/System.Runtime.Serialization/NetDataContractSerializer.xml +++ b/xml/System.Runtime.Serialization/NetDataContractSerializer.xml @@ -494,7 +494,7 @@ ## Remarks The determines whether it can read an object by examining the name and namespace of the XML element the reader is positioned at, and comparing the values to expected name and namespace. The expected name and namespace can be set with the following: the data contract name and namespace of the type passed into the constructor, or the `rootName` and `rootNamespace` values passed into the constructor (if present). - You can set the `rootName` and `rootNamespace` in the following constructors: , , and . + You can set the `rootName` and `rootNamespace` in the following constructors: , , and . ]]> diff --git a/xml/System.Runtime.Serialization/SerializationInfo.xml b/xml/System.Runtime.Serialization/SerializationInfo.xml index 959a85f741f46..4122eeb4b3f3b 100644 --- a/xml/System.Runtime.Serialization/SerializationInfo.xml +++ b/xml/System.Runtime.Serialization/SerializationInfo.xml @@ -1853,7 +1853,7 @@ End Sub is of the type requested (or one of its derived classes), that value is returned directly. Otherwise, is called to convert it to the appropriate type. + If the data stored in the is of the type requested (or one of its derived classes), that value is returned directly. Otherwise, is called to convert it to the appropriate type. The value returned by the method can always be safely cast to the type specified in the `type` parameter. diff --git a/xml/System.Runtime.Serialization/XmlObjectSerializer.xml b/xml/System.Runtime.Serialization/XmlObjectSerializer.xml index 741a5f1b8b046..41b797ea135e6 100644 --- a/xml/System.Runtime.Serialization/XmlObjectSerializer.xml +++ b/xml/System.Runtime.Serialization/XmlObjectSerializer.xml @@ -572,7 +572,7 @@ overload. + This is a virtual method, and has a default implementation that delegates writing to the overload. ]]> diff --git a/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml b/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml index 4bbf411507c04..967ce51f57d41 100644 --- a/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml +++ b/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml @@ -38,27 +38,27 @@ ## Levels of Compatibility The supports the following levels of compatibility, which are represented by members of the enumeration: -- No version-to-version compatibility (). The client can expect that future versions will break the existing client. For more information, see the [No Compatibility](#None) section later in this topic. +- No version-to-version compatibility (). The client can expect that future versions will break the existing client. For more information, see the [No Compatibility](#None) section later in this topic. -- Side-by-side version-to-version compatibility (). The component has been tested to work when more than one version of the assembly is loaded in the same application domain. In general, future versions can break compatibility. However, when breaking changes are made, the old version is not modified but exists alongside the new version. Side-by-side execution is the expected way to make existing clients work when breaking changes are made. For more information, see the [Side-by-Side Compatibility](#SideBySide) section later in this topic. +- Side-by-side version-to-version compatibility (). The component has been tested to work when more than one version of the assembly is loaded in the same application domain. In general, future versions can break compatibility. However, when breaking changes are made, the old version is not modified but exists alongside the new version. Side-by-side execution is the expected way to make existing clients work when breaking changes are made. For more information, see the [Side-by-Side Compatibility](#SideBySide) section later in this topic. -- Stable version-to-version compatibility (). Future versions should not break the client, and side-by-side execution should not be needed. However, if the client is inadvertently broken, it may be possible to use side-by-side execution to fix the problem. For more information, see the [Stable Compatibility](#Standard) section. +- Stable version-to-version compatibility (). Future versions should not break the client, and side-by-side execution should not be needed. However, if the client is inadvertently broken, it may be possible to use side-by-side execution to fix the problem. For more information, see the [Stable Compatibility](#Standard) section. -- Exchange version-to-version compatibility (). Extraordinary care is taken to ensure that future versions will not break the client. The client should use only these types in the signature of interfaces that are used for communication with other assemblies that are deployed independently of one another. Only one version of these types is expected to be in a given application domain, which means that if a client breaks, side-by-side execution cannot fix the compatibility problem. For more information, see the [Exchange Type Compatibility](#Exchange) section. +- Exchange version-to-version compatibility (). Extraordinary care is taken to ensure that future versions will not break the client. The client should use only these types in the signature of interfaces that are used for communication with other assemblies that are deployed independently of one another. Only one version of these types is expected to be in a given application domain, which means that if a client breaks, side-by-side execution cannot fix the compatibility problem. For more information, see the [Exchange Type Compatibility](#Exchange) section. The following sections discuss each level of guarantee in greater detail. ### No Compatibility - Marking a component as indicates that the provider makes no guarantees about compatibility. Clients should avoid taking any dependencies on the exposed interfaces. This level of compatibility is useful for types that are experimental or that are publicly exposed but are intended only for components that are always updated at the same time. explicitly indicates that this component should not be used by external components. + Marking a component as indicates that the provider makes no guarantees about compatibility. Clients should avoid taking any dependencies on the exposed interfaces. This level of compatibility is useful for types that are experimental or that are publicly exposed but are intended only for components that are always updated at the same time. explicitly indicates that this component should not be used by external components. ### Side-by-Side Compatibility - Marking a component as indicates that the component has been tested to work when more than one version of the assembly is loaded into the same application domain. Breaking changes are allowed as long as they are made to the assembly that has the greater version number. Components that are bound to an old version of the assembly are expected to continue to bind to the old version, and other components can bind to the new version. It is also possible to update a component that is declared to be by destructively modifying the old version. + Marking a component as indicates that the component has been tested to work when more than one version of the assembly is loaded into the same application domain. Breaking changes are allowed as long as they are made to the assembly that has the greater version number. Components that are bound to an old version of the assembly are expected to continue to bind to the old version, and other components can bind to the new version. It is also possible to update a component that is declared to be by destructively modifying the old version. ### Stable Compatibility - Marking a type as indicates that the type should remain stable across versions. However, it may also be possible for side-by-side versions of a stable type to exist in the same application domain. + Marking a type as indicates that the type should remain stable across versions. However, it may also be possible for side-by-side versions of a stable type to exist in the same application domain. Stable types maintain a high binary compatibility bar. Because of this, providers should avoid making breaking changes to stable types. The following kinds of changes are acceptable: @@ -84,7 +84,7 @@ ### Exchange Type Compatibility - Marking a type as provides a stronger version compatibility guarantee than , and should be applied to the most stable of all types. These types are intended to be used for interchange between independently built components across all component boundaries in both time (any version of the CLR or any version of a component or application) and space (cross-process, cross-CLR in one process, cross-application domain in one CLR). If a breaking change is made to an exchange type, it is impossible to fix the issue by loading multiple versions of the type. + Marking a type as provides a stronger version compatibility guarantee than , and should be applied to the most stable of all types. These types are intended to be used for interchange between independently built components across all component boundaries in both time (any version of the CLR or any version of a component or application) and space (cross-process, cross-CLR in one process, cross-application domain in one CLR). If a breaking change is made to an exchange type, it is impossible to fix the issue by loading multiple versions of the type. Exchange types should be changed only when a problem is very serious (such as a severe security issue) or the probability of breakage is very low (that is, if the behavior was already broken in a random way that code could not have conceivably taken a dependency on). You can make the following kinds of changes to an exchange type: diff --git a/xml/System.Runtime.Versioning/FrameworkName.xml b/xml/System.Runtime.Versioning/FrameworkName.xml index 5fac07ae452fe..65f04f5859487 100644 --- a/xml/System.Runtime.Versioning/FrameworkName.xml +++ b/xml/System.Runtime.Versioning/FrameworkName.xml @@ -78,7 +78,7 @@ - Any leading or trailing white space in the *identifier* component is removed and the resulting string is assigned to the property. -- Any leading or trailing white space and the initial "v" or "V", if present, are removed from the `versionNumber`. The returned string is then passed to the constructor, and the resulting object is assigned to the property. +- Any leading or trailing white space and the initial "v" or "V", if present, are removed from the `versionNumber`. The returned string is then passed to the constructor, and the resulting object is assigned to the property. - Any leading or trailing white space in the `profileName` component is removed and the resulting string is assigned to the property. @@ -243,7 +243,7 @@ object and calls the overload to test for equality. If the conversion does not succeed or if `obj` is `null`, the method returns `false`. + The method converts `obj` to a object and calls the overload to test for equality. If the conversion does not succeed or if `obj` is `null`, the method returns `false`. ]]> @@ -290,7 +290,7 @@ - An ordinal comparison of the property values of the current instance and `other`. -- A comparison of the version properties by calling the method. +- A comparison of the version properties by calling the method. ]]> @@ -330,7 +330,7 @@ *identifier*, Version=*version*[, Profile=*profile*] - where *identifier* corresponds to the property, `version` is equivalent to calling on the value of the property, and `profile` corresponds to the property. If a profile has not been assigned to the object, the profile component is not included in the string. + where *identifier* corresponds to the property, `version` is equivalent to calling on the value of the property, and `profile` corresponds to the property. If a profile has not been assigned to the object, the profile component is not included in the string. The value of the property is identical to the string returned by the method. @@ -443,7 +443,7 @@ ## Remarks The method defines the operation of the equality operator for objects. - Languages that do not support custom operators can call the method instead. + Languages that do not support custom operators can call the method instead. @@ -496,7 +496,7 @@ ## Remarks The method defines the operation of the inequality operator for objects. - Languages that do not support custom operators can test for inequality by calling the method and reversing its value. + Languages that do not support custom operators can test for inequality by calling the method and reversing its value. @@ -581,7 +581,7 @@ *identifier*, Version=*version*[, Profile=*profile*] - where *identifier* corresponds to the property, `version` is equivalent to calling on the value of the property, and `profile` corresponds to the property. If a profile has not been assigned to the object, the profile component is not included in the returned string. + where *identifier* corresponds to the property, `version` is equivalent to calling on the value of the property, and `profile` corresponds to the property. If a profile has not been assigned to the object, the profile component is not included in the returned string. The value returned by the method is identical to the value of the property. diff --git a/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml b/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml index 2db739732f72a..8eeaf41817eaf 100644 --- a/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml +++ b/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml @@ -80,7 +80,7 @@ method. + The string that is assigned to the `frameworkName` parameter generally takes the same form as the string that is returned by the method. ]]> @@ -158,7 +158,7 @@ property maps to the `frameworkName` parameter of the constructor. It represents the .NET Framework version in a compact form and typically corresponds to the string that is returned by the method. + The property maps to the `frameworkName` parameter of the constructor. It represents the .NET Framework version in a compact form and typically corresponds to the string that is returned by the method. ]]> diff --git a/xml/System.Runtime/GCLargeObjectHeapCompactionMode.xml b/xml/System.Runtime/GCLargeObjectHeapCompactionMode.xml index df8b191115f8c..7baccf1630988 100644 --- a/xml/System.Runtime/GCLargeObjectHeapCompactionMode.xml +++ b/xml/System.Runtime/GCLargeObjectHeapCompactionMode.xml @@ -29,7 +29,7 @@ property is a member of the enumeration that indicates whether the next full blocking garbage collection also compacts the large object heap (LOH). By default, the LOH is not compacted. A value of CompactOnce indicates that the blocking garbage collection will compact the LOH. After the garbage collection, the value of the property reverts to Default. + The value of the property is a member of the enumeration that indicates whether the next full blocking garbage collection also compacts the large object heap (LOH). By default, the LOH is not compacted. A value of CompactOnce indicates that the blocking garbage collection will compact the LOH. After the garbage collection, the value of the property reverts to Default. ]]> diff --git a/xml/System.Runtime/GCLatencyMode.xml b/xml/System.Runtime/GCLatencyMode.xml index f4f73ac0ee346..c611d93043620 100644 --- a/xml/System.Runtime/GCLatencyMode.xml +++ b/xml/System.Runtime/GCLatencyMode.xml @@ -28,7 +28,7 @@ property to any enumeration value except NoGCRegion. You can also determine the garbage collector's current latency mode by retrieving the property value. + You can adjust the intrusiveness of garbage collection in your application by setting the property to any enumeration value except NoGCRegion. You can also determine the garbage collector's current latency mode by retrieving the property value. See [Latency Modes](~/docs/standard/garbage-collection/latency.md) for a discussion of how the runtime configuration settings for garbage collection affect the default value for this enumeration. diff --git a/xml/System.Runtime/GCSettings.xml b/xml/System.Runtime/GCSettings.xml index 209756671c26f..cc30599888294 100644 --- a/xml/System.Runtime/GCSettings.xml +++ b/xml/System.Runtime/GCSettings.xml @@ -137,12 +137,12 @@ ## Remarks The LOH is used for allocating memory for large objects (such as arrays) that require more than 85,000 bytes. Because of the performance impact of copying large blocks of memory, the garbage collector ordinarily sweeps the LOH, which involves creating a list of the memory locations that were occupied by dead objects and that can be reused to satisfy future requests for allocation of memory for large objects. However, in apps that make extensive use of the LOH to store transient objects, memory fragmentation can also adversely impact performance. In this case, it is possible to use the property to compact rather than simply sweep the LOH during a garbage collection. - The default value of the property is , which indicates that the LOH is not compacted during garbage collections. If you assign the property a value of , the LOH is compacted during the next full blocking garbage collection, and the property value is reset to . + The default value of the property is , which indicates that the LOH is not compacted during garbage collections. If you assign the property a value of , the LOH is compacted during the next full blocking garbage collection, and the property value is reset to . > [!NOTE] -> Background garbage collections are not blocking. This means that, if you set the property to , any background generation 2 collections that occur subsequently do not compact the LOH. Only the first blocking generation 2 collection compacts the LOH. +> Background garbage collections are not blocking. This means that, if you set the property to , any background generation 2 collections that occur subsequently do not compact the LOH. Only the first blocking generation 2 collection compacts the LOH. - After the property is set to , the next full blocking garbage collection (and compaction of the LOH) occurs at an indeterminate future time. You can compact the LOH immediately by using code like the following: + After the property is set to , the next full blocking garbage collection (and compaction of the LOH) occurs at an indeterminate future time. You can compact the LOH immediately by using code like the following: [!code-csharp[System.Runtime.GCSettings#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.runtime.gcsettings/cs/lohcompactionmode1.cs#1)] [!code-vb[System.Runtime.GCSettings#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.runtime.gcsettings/vb/lohcompactionmode1.vb#1)] @@ -193,7 +193,7 @@ ## Remarks You can reduce the level of intrusiveness of garbage collection in your application by setting the to during critical operations. After such operations are completed, return to a higher latency mode so that more objects can be reclaimed to increase memory. - Ordinarily, you set the value of the property to define the garbage collector's latency mode. However, you cannot set the no GC region latency mode by assigning the enumeration value to the property. Instead, you call the method to begin the no GC region latency mode, and you call the to end it. + Ordinarily, you set the value of the property to define the garbage collector's latency mode. However, you cannot set the no GC region latency mode by assigning the enumeration value to the property. Instead, you call the method to begin the no GC region latency mode, and you call the to end it. See [Latency Modes](~/docs/standard/garbage-collection/latency.md) for a discussion of how the runtime configuration settings for garbage collection affect the default value of the enumeration. diff --git a/xml/System.Runtime/MemoryFailPoint.xml b/xml/System.Runtime/MemoryFailPoint.xml index fecbaa8633717..3449a19c205cd 100644 --- a/xml/System.Runtime/MemoryFailPoint.xml +++ b/xml/System.Runtime/MemoryFailPoint.xml @@ -88,7 +88,7 @@ method to determine the amount of memory available before and after calling the method that processes the work item. See the class for a code example that dynamically determines the value for the `sizeInMegabytes` parameter. + The amount of memory used by your application to process a work item can be determined empirically. To estimate the amount of memory your application needs to process a request, consider using the method to determine the amount of memory available before and after calling the method that processes the work item. See the class for a code example that dynamically determines the value for the `sizeInMegabytes` parameter. diff --git a/xml/System.Security.AccessControl/DirectorySecurity.xml b/xml/System.Security.AccessControl/DirectorySecurity.xml index 3798540fa2e1b..c20d91e48171b 100644 --- a/xml/System.Security.AccessControl/DirectorySecurity.xml +++ b/xml/System.Security.AccessControl/DirectorySecurity.xml @@ -34,10 +34,10 @@ |Task|Methods| |----------|-------------| -|Add rules|

| -|Remove rules|

| -|Retrieve the access control to a directory|

| -|Persist the access control to a directory|

| +|Add rules|

| +|Remove rules|

| +|Retrieve the access control to a directory|

| +|Persist the access control to a directory|

| diff --git a/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml b/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml index d42a40f5fd4e0..c800d0c95431b 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml @@ -27,7 +27,7 @@ > [!NOTE] > Windows access control security is meaningful only for named system events. If an object represents a local event, access control is irrelevant. - To get a list of the rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. + To get a list of the rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for an event, the set contains the minimum number of rules currently required to express all the access control entries. @@ -36,10 +36,10 @@ Use objects to specify the access rights to allow or deny to a user or group. An object always represents either allowed access or denied access, never both. - To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. +> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. objects are immutable. Security for an event is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -52,7 +52,7 @@ The following code example demonstrates the creation and use of objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/VB/source.vb#1)] @@ -90,7 +90,7 @@ (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. + To wait on an (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. ]]> @@ -139,9 +139,9 @@ (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. + To wait on an (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -149,7 +149,7 @@ The following code example demonstrates the use of this constructor to create objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/VB/source.vb#1)] @@ -209,7 +209,7 @@ The following code example demonstrates the use of the property to display the rights in the set of rules contained in an object. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/EventWaitHandleAuditRule.xml b/xml/System.Security.AccessControl/EventWaitHandleAuditRule.xml index bb1237dac48e1..bc28c4024f07a 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleAuditRule.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleAuditRule.xml @@ -27,17 +27,17 @@ > [!NOTE] > Windows access control security is meaningful only for named system events. If an object represents a local event, access control is irrelevant. - To get a list of the audit rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. + To get a list of the audit rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for an event, the set contains the minimum number of rules currently required to express all the access control entries. > [!NOTE] > The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. +> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. objects are immutable. Security for an event is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -77,7 +77,7 @@ object from a string representing a user or group name, use the constructor. + To create an object from a string representing a user or group name, use the constructor. ]]> diff --git a/xml/System.Security.AccessControl/EventWaitHandleRights.xml b/xml/System.Security.AccessControl/EventWaitHandleRights.xml index 7bc62e8ee4876..5afa02d1ce88b 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleRights.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleRights.xml @@ -26,7 +26,7 @@ enumeration to specify access control rights when you create objects. To apply access rights to a named system event, first add objects to an object, then attach the object to the named system event using the constructor or the method. + Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system event, first add objects to an object, then attach the object to the named system event using the constructor or the method. > [!NOTE] > Security on synchronization objects is not supported for Windows 98 or Windows Millennium Edition. @@ -34,10 +34,10 @@ ## Examples - The following code example demonstrates the use of values when creating and using objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + The following code example demonstrates the use of values when creating and using objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to an object; see , method, and . +> This example does not attach the security object to an object; see , method, and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml b/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml index 794161349c95b..39070c2a2d823 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml @@ -49,12 +49,12 @@ - Adding or removing access control entries in ways that do not maintain the canonical ordering. - To modify Windows access control security for a named wait handle, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. + To modify Windows access control security for a named wait handle, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. > [!IMPORTANT] -> Changes you make to an object do not affect the access levels of the named wait handle until you call the method to assign the altered security object to the named wait handle. +> Changes you make to an object do not affect the access levels of the named wait handle until you call the method to assign the altered security object to the named wait handle. - To copy access control security from one wait handle to another, use the method to get an object representing the access and audit rules for the first wait handle, and then use the method, or a constructor that accepts an object, to assign those rules to the second wait handle. + To copy access control security from one wait handle to another, use the method to get an object representing the access and audit rules for the first wait handle, and then use the method, or a constructor that accepts an object, to assign those rules to the second wait handle. Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named wait handle, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. @@ -64,7 +64,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/VB/source.vb#1)] @@ -258,7 +258,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.AddAccessRule/VB/source.vb#1)] @@ -437,7 +437,7 @@ The example creates an object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The right in `rule` is ignored. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRule/VB/source.vb#1)] @@ -486,7 +486,7 @@ The example creates an object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the rule. The example then creates a new rule that allows the current user to take ownership, and uses that rule to remove the rule from the object. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRuleAll#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRuleAll/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRuleAll#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRuleAll/VB/source.vb#1)] @@ -538,7 +538,7 @@ The example creates an object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRuleSpecific#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRuleSpecific/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRuleSpecific#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.RemoveAccessRuleSpecific/VB/source.vb#1)] @@ -703,7 +703,7 @@ The example creates an object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.ResetAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.ResetAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.ResetAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.ResetAccessRule/VB/source.vb#1)] @@ -754,7 +754,7 @@ The example creates an object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing rule with the new rule. The rule that denies access is not affected. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.EventWaitHandleSecurity.SetAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.SetAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.EventWaitHandleSecurity.SetAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.EventWaitHandleSecurity.SetAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/GenericAce.xml b/xml/System.Security.AccessControl/GenericAce.xml index 932acd3540fcb..858a8ac4933e2 100644 --- a/xml/System.Security.AccessControl/GenericAce.xml +++ b/xml/System.Security.AccessControl/GenericAce.xml @@ -349,7 +349,7 @@ if the two objects are equal; otherwise, . - .]]> + .]]> @@ -382,7 +382,7 @@ if the two objects are unequal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Security.AccessControl/MutexAccessRule.xml b/xml/System.Security.AccessControl/MutexAccessRule.xml index ba8a66eba27e8..f9a972b312c00 100644 --- a/xml/System.Security.AccessControl/MutexAccessRule.xml +++ b/xml/System.Security.AccessControl/MutexAccessRule.xml @@ -27,7 +27,7 @@ > [!NOTE] > Windows access control security is meaningful only for named system mutexes. If a object represents a local mutex, access control is irrelevant. - To get a list of the rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. + To get a list of the rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for a mutex, the set contains the minimum number of rules currently required to express all the access control entries. @@ -36,10 +36,10 @@ Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. - To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. +> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. objects are immutable. Security for a mutex is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -52,7 +52,7 @@ The following code example demonstrates the creation and use of objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/VB/source.vb#1)] @@ -90,7 +90,7 @@ (by calling the , or method), a user must have access. To release the mutex, by calling the method, the user must have access. + To wait on a (by calling the , or method), a user must have access. To release the mutex, by calling the method, the user must have access. ]]> @@ -139,9 +139,9 @@ (by calling the , or method), a user must have access. To release the mutex, by calling the methods, the user must have access. + To wait on a (by calling the , or method), a user must have access. To release the mutex, by calling the methods, the user must have access. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -149,7 +149,7 @@ The following code example demonstrates the use of this constructor to create objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/VB/source.vb#1)] @@ -209,7 +209,7 @@ The following code example demonstrates the use of the property to display the rights in the set of rules contained in a object. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/MutexAuditRule.xml b/xml/System.Security.AccessControl/MutexAuditRule.xml index c248957f19003..e13367d6a11c7 100644 --- a/xml/System.Security.AccessControl/MutexAuditRule.xml +++ b/xml/System.Security.AccessControl/MutexAuditRule.xml @@ -27,17 +27,17 @@ > [!NOTE] > Windows access control security is meaningful only for named system mutexes. If a object represents a local mutex, access control is irrelevant. - To get a list of the audit rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. + To get a list of the audit rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for a mutex, the set contains the minimum number of rules currently required to express all the access control entries. > [!NOTE] > The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. +> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. objects are immutable. Security for a mutex is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -77,7 +77,7 @@ object from a string representing a user or group name, use the constructor. + To create an object from a string representing a user or group name, use the constructor. ]]> diff --git a/xml/System.Security.AccessControl/MutexRights.xml b/xml/System.Security.AccessControl/MutexRights.xml index 0e137a949de94..665da37150549 100644 --- a/xml/System.Security.AccessControl/MutexRights.xml +++ b/xml/System.Security.AccessControl/MutexRights.xml @@ -26,7 +26,7 @@ enumeration to specify access control rights when you create objects. To apply access rights to a named system mutex, use objects with the constructor and the method. + Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system mutex, use objects with the constructor and the method. > [!NOTE] > Security on synchronization objects is not supported for Windows 98 or Windows Millennium Edition. @@ -34,10 +34,10 @@ ## Examples - The following code example demonstrates the use of values when creating and using objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + The following code example demonstrates the use of values when creating and using objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object; see , method, and . +> This example does not attach the security object to a object; see , method, and . [!code-csharp[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/MutexSecurity.xml b/xml/System.Security.AccessControl/MutexSecurity.xml index 55b0a9530a1fd..acbafbd89163b 100644 --- a/xml/System.Security.AccessControl/MutexSecurity.xml +++ b/xml/System.Security.AccessControl/MutexSecurity.xml @@ -49,12 +49,12 @@ - Adding or removing access control entries in ways that do not maintain the canonical ordering. - To modify Windows access control security for a named mutex, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. + To modify Windows access control security for a named mutex, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. +> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. - To copy access control security from one mutex to another, use the method to get a object representing the access and audit rules for the first mutex, and then use the method, or a constructor that accepts a object, to assign those rules to the second mutex. + To copy access control security from one mutex to another, use the method to get a object representing the access and audit rules for the first mutex, and then use the method, or a constructor that accepts a object, to assign those rules to the second mutex. Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named mutex, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. @@ -67,7 +67,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/VB/source.vb#1)] @@ -298,7 +298,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in . +> This example does not attach the security object to a object. Examples that attach security objects can be found in . [!code-csharp[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.AddAccessRule/VB/source.vb#1)] @@ -477,7 +477,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The extraneous right in `rule` is ignored. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.RemoveAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.RemoveAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.RemoveAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.RemoveAccessRule/VB/source.vb#1)] @@ -526,7 +526,7 @@ The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the rule. The example then creates a new rule that allows the current user to take ownership, and uses that rule to remove the rule from the object. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.RemoveAccessRuleAll#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.RemoveAccessRuleAll/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.RemoveAccessRuleAll#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.RemoveAccessRuleAll/VB/source.vb#1)] @@ -578,7 +578,7 @@ The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.RemoveAccessRuleSpecific#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.RemoveAccessRuleSpecific/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.RemoveAccessRuleSpecific#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.RemoveAccessRuleSpecific/VB/source.vb#1)] @@ -743,7 +743,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.ResetAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.ResetAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.ResetAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.ResetAccessRule/VB/source.vb#1)] @@ -794,7 +794,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing Allow rule with the new rule. The rule that denies access is not affected. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.MutexSecurity.SetAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.SetAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.MutexSecurity.SetAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.MutexSecurity.SetAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/RegistryAccessRule.xml b/xml/System.Security.AccessControl/RegistryAccessRule.xml index 131e27b405d5a..99543df24850b 100644 --- a/xml/System.Security.AccessControl/RegistryAccessRule.xml +++ b/xml/System.Security.AccessControl/RegistryAccessRule.xml @@ -30,7 +30,7 @@ > [!NOTE] > Windows access control security can only be applied to registry keys. It cannot be applied to individual key/value pairs stored in a key. - To get a list of the rules currently applied to a registry key, use the method to get a object, and then use its method to obtain a collection of objects. + To get a list of the rules currently applied to a registry key, use the method to get a object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary control access list (DACL). When you get the set of all access rules for a registry key, the set contains the minimum number of rules currently required to express all the access control entries. @@ -39,10 +39,10 @@ Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. - To apply a rule to a registry key, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + To apply a rule to a registry key, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. +> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. objects are immutable. Security for a registry key is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -92,7 +92,7 @@ and . + This constructor specifies default propagation and inheritance. That is, and . ]]> @@ -144,9 +144,9 @@ and . + This constructor specifies default propagation and inheritance. That is, and . - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -214,7 +214,7 @@ flag. If this flag is not specified, the propagation flags are ignored, and only the immediate key is affected. If the flag is present, the rule is propagated as shown in the following table. The table assumes there is a subkey S with child subkey CS and grandchild subkey GS. That is, the path for the grandchild subkey is S\CS\GS. + All registry keys are containers, so the only inheritance flag that is meaningful for registry keys is the flag. If this flag is not specified, the propagation flags are ignored, and only the immediate key is affected. If the flag is present, the rule is propagated as shown in the following table. The table assumes there is a subkey S with child subkey CS and grandchild subkey GS. That is, the path for the grandchild subkey is S\CS\GS. |Propagation flags|S|CS|GS| |-----------------------|-------|--------|--------| @@ -228,7 +228,7 @@ For example, if the flag is specified for `inheritanceFlags` and the propagation flag is specified for `propagationFlags`, this rule does not apply to the immediate subkey, but does apply to all its immediate child subkeys and to all subkeys they contain. > [!NOTE] -> Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the combination of otherwise compatible rules. +> Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the combination of otherwise compatible rules. ]]> @@ -292,7 +292,7 @@ flag. If this flag is not specified, the propagation flags are ignored, and only the immediate key is affected. If the flag is present, the rule is propagated as shown in the following table. The table assumes there is a subkey S with child subkey CS and grandchild subkey GS. That is, the path for the grandchild subkey is S\CS\GS. + All registry keys are containers, so the only inheritance flag that is meaningful for registry keys is the flag. If this flag is not specified, the propagation flags are ignored, and only the immediate key is affected. If the flag is present, the rule is propagated as shown in the following table. The table assumes there is a subkey S with child subkey CS and grandchild subkey GS. That is, the path for the grandchild subkey is S\CS\GS. |Propagation flags|S|CS|GS| |-----------------------|-------|--------|--------| @@ -306,9 +306,9 @@ For example, if the flag is specified for `inheritanceFlags` and the propagation flag is specified for `propagationFlags`, this rule does not apply to the immediate subkey, but does apply to all its immediate child subkeys and to all subkeys they contain. > [!NOTE] -> Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the combination of otherwise compatible rules. +> Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the combination of otherwise compatible rules. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. diff --git a/xml/System.Security.AccessControl/RegistryAuditRule.xml b/xml/System.Security.AccessControl/RegistryAuditRule.xml index 7a60cb778c0eb..17d2505352ba6 100644 --- a/xml/System.Security.AccessControl/RegistryAuditRule.xml +++ b/xml/System.Security.AccessControl/RegistryAuditRule.xml @@ -30,17 +30,17 @@ > [!NOTE] > Windows access control security can only be applied to registry keys. It cannot be applied to individual key/value pairs stored in a key. - To get a list of the audit rules currently applied to a registry key, use the method to get a object, and then use its method to obtain a collection of objects. + To get a list of the audit rules currently applied to a registry key, use the method to get a object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for a registry key, the set contains the minimum number of rules currently required to express all the access control entries. > [!NOTE] > The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - Use objects to specify access rights to be audited for a user or group. To apply a rule to a registry key, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + Use objects to specify access rights to be audited for a user or group. To apply a rule to a registry key, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. +> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. objects are immutable. Security for a registry key is modified by using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -84,7 +84,7 @@ flag. If this flag is not specified, the propagation flags are ignored, and only the immediate key is affected. If the flag is present, the rule is propagated as shown in the following table. The table assumes there is a subkey S with child subkey CS and grandchild subkey GS. That is, the path for the grandchild subkey is S\CS\GS. + All registry keys are containers, so the only inheritance flag that is meaningful for registry keys is the flag. If this flag is not specified, the propagation flags are ignored, and only the immediate key is affected. If the flag is present, the rule is propagated as shown in the following table. The table assumes there is a subkey S with child subkey CS and grandchild subkey GS. That is, the path for the grandchild subkey is S\CS\GS. |Propagation flags|S|CS|GS| |-----------------------|-------|--------|--------| @@ -98,7 +98,7 @@ For example, if the flag is specified for `inheritanceFlags` and the propagation flag is specified for `propagationFlags`, this rule does not apply to the immediate subkey, but does apply to all its immediate child subkeys and to all subkeys they contain. > [!NOTE] -> Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. +> Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. ]]> @@ -162,7 +162,7 @@ flag. If this flag is not specified, the propagation flags are ignored, and only the immediate key is affected. If the flag is present, the rule is propagated as shown in the following table. The table assumes there is a subkey S with child subkey CS and grandchild subkey GS. That is, the path for the grandchild subkey is S\CS\GS. + All registry keys are containers, so the only inheritance flag that is meaningful for registry keys is the flag. If this flag is not specified, the propagation flags are ignored, and only the immediate key is affected. If the flag is present, the rule is propagated as shown in the following table. The table assumes there is a subkey S with child subkey CS and grandchild subkey GS. That is, the path for the grandchild subkey is S\CS\GS. |Propagation flags|S|CS|GS| |-----------------------|-------|--------|--------| @@ -176,9 +176,9 @@ For example, if the flag is specified for `inheritanceFlags` and the propagation flag is specified for `propagationFlags`, this rule does not apply to the immediate subkey, but does apply to all its immediate child subkeys and to all subkeys they contain. > [!NOTE] -> Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. +> Although you can specify the flag for `inheritanceFlags`, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. ]]> diff --git a/xml/System.Security.AccessControl/RegistryRights.xml b/xml/System.Security.AccessControl/RegistryRights.xml index bea4c3d2ee67b..690619ca70d48 100644 --- a/xml/System.Security.AccessControl/RegistryRights.xml +++ b/xml/System.Security.AccessControl/RegistryRights.xml @@ -26,7 +26,7 @@ enumeration to specify registry access rights when you create objects. To apply access rights to a registry key, first add objects to a object, then attach the object to the key using the method, or an appropriate overload of the method. + Use the enumeration to specify registry access rights when you create objects. To apply access rights to a registry key, first add objects to a object, then attach the object to the key using the method, or an appropriate overload of the method. diff --git a/xml/System.Security.AccessControl/RegistrySecurity.xml b/xml/System.Security.AccessControl/RegistrySecurity.xml index ccdea57d96d33..cc0e8cc9edf84 100644 --- a/xml/System.Security.AccessControl/RegistrySecurity.xml +++ b/xml/System.Security.AccessControl/RegistrySecurity.xml @@ -52,12 +52,12 @@ - Adding or removing access control entries in ways that do not maintain the canonical ordering. - To modify Windows access control security for a registry key, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. + To modify Windows access control security for a registry key, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. +> Changes you make to a object do not affect the access levels of the registry key until you call the method to assign the altered security object to the registry key. - To copy access control security from one registry key to another, use the method to get a object representing the access and audit rules for the first registry key, and then use the method to assign those rules to the second registry key. You can also assign the rules to a second registry key with an or method that takes a object parameter. + To copy access control security from one registry key to another, use the method to get a object representing the access and audit rules for the first registry key, and then use the method to assign those rules to the second registry key. You can also assign the rules to a second registry key with an or method that takes a object parameter. Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a registry key, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. @@ -70,12 +70,12 @@ The following code example shows how the method removes rights from a compatible rule, and how the method merges rights with compatible rules. - The example creates a object and adds a rule that allows the current user rights. The example then creates a rule that grants the user , with the same inheritance and propagation rights as the first rule, and uses the method to remove this new rule from the object. is a constituent of , so it is removed from the compatible rule. The rules in the object are displayed, showing the remaining constituents of . + The example creates a object and adds a rule that allows the current user rights. The example then creates a rule that grants the user , with the same inheritance and propagation rights as the first rule, and uses the method to remove this new rule from the object. is a constituent of , so it is removed from the compatible rule. The rules in the object are displayed, showing the remaining constituents of . The example code then calls the method to merge the right back into the rule in the object. > [!NOTE] -> This example does not attach the security object to a object. The second example in this section attaches a security object, and so do the examples in and . +> This example does not attach the security object to a object. The second example in this section attaches a security object, and so do the examples in and . [!code-csharp[System.Security.AccessControl.RegistrySecurity.RemoveAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.RemoveAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.RegistrySecurity.RemoveAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.RemoveAccessRule/VB/source.vb#1)] @@ -203,7 +203,7 @@ The recommended way to create access control rules is to use the constructors of the class. > [!NOTE] -> Although you can specify the flag, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. +> Although you can specify the flag, there is no point in doing so. For the purposes of access control, the name/value pairs in a subkey are not separate objects. The access rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. ]]> @@ -286,7 +286,7 @@ ## Remarks The method searches for rules with the same user or group and the same as `rule`. If none are found, `rule` is added. If a matching rule is found, the rights in `rule` are merged with the existing rule. - Rules cannot be merged if they have different inheritance flags. For example, if a user is allowed read access with no inheritance flags, and is used to add a rule giving the user write access with inheritance for subkeys (), the two rules cannot be merged. + Rules cannot be merged if they have different inheritance flags. For example, if a user is allowed read access with no inheritance flags, and is used to add a rule giving the user write access with inheritance for subkeys (), the two rules cannot be merged. Rules with different values are never merged. @@ -298,7 +298,7 @@ The following code example creates registry access rules and adds them to a object, showing how rules that allow and deny rights remain separate, while compatible rules of the same kind are merged. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . A code example that demonstrates inheritance and propagation flags can be found in the class. @@ -344,7 +344,7 @@ ## Remarks The method searches for rules with the same user or group as `rule`. If none are found, `rule` is added. If a matching rule is found, the flags in `rule` are merged into the existing rule. - Rules cannot be merged if they have different inheritance flags. For example, if failed attempts to write to a key are audited for a particular user, with no inheritance flags, and is used to add a rule specifying that failed attempts to change permissions are to be audited for the same user, but with inheritance for subkeys (), the two rules cannot be merged. + Rules cannot be merged if they have different inheritance flags. For example, if failed attempts to write to a key are audited for a particular user, with no inheritance flags, and is used to add a rule specifying that failed attempts to change permissions are to be audited for the same user, but with inheritance for subkeys (), the two rules cannot be merged. ]]> @@ -395,7 +395,7 @@ The recommended way to create audit rules is to use the constructors of the class. > [!NOTE] -> Although you can specify the flag, there is no point in doing so. For the purposes of audit control, the name/value pairs in a subkey are not separate objects. The audit rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. +> Although you can specify the flag, there is no point in doing so. For the purposes of audit control, the name/value pairs in a subkey are not separate objects. The audit rights to name/value pairs are controlled by the rights of the subkey. Furthermore, since all subkeys are containers (that is, they can contain other subkeys), they are not affected by the flag. Finally, specifying the flag needlessly complicates the maintenance of rules, because it interferes with the normal combination of compatible rules. ]]> @@ -485,12 +485,12 @@ ## Examples The following code example shows how the method removes rights from a compatible rule, and how the method merges rights with compatible rules. - The example creates a object and adds a rule that allows the current user rights. The example then creates a rule that grants the user , with the same inheritance and propagation rights as the first rule, and uses the method to remove this new rule from the object. is a constituent of , so it is removed from the compatible rule. The rules in the object are displayed, showing the remaining constituents of . + The example creates a object and adds a rule that allows the current user rights. The example then creates a rule that grants the user , with the same inheritance and propagation rights as the first rule, and uses the method to remove this new rule from the object. is a constituent of , so it is removed from the compatible rule. The rules in the object are displayed, showing the remaining constituents of . The example code then calls the method to merge the right back into the rule in the object. > [!NOTE] -> This example does not attach the security object to a object. The second example in this section attaches a security object, and so do the examples in . +> This example does not attach the security object to a object. The second example in this section attaches a security object, and so do the examples in . [!code-csharp[System.Security.AccessControl.RegistrySecurity.RemoveAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.RemoveAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.RegistrySecurity.RemoveAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.RemoveAccessRule/VB/source.vb#1)] @@ -534,7 +534,7 @@ ## Remarks The current is searched for rules that have the same user and the same value as `rule`. Any rights, inheritance flags, or propagation flags specified by `rule` are ignored when performing this search. If no matching rules are found, no action is taken. - For example, if a user has multiple rules that allow various rights with different inheritance and propagation flags, you can remove all those rules by creating a object that specifies the user and , with any arbitrary rights and flags, and passing that rule to the method. + For example, if a user has multiple rules that allow various rights with different inheritance and propagation flags, you can remove all those rules by creating a object that specifies the user and , with any arbitrary rights and flags, and passing that rule to the method. @@ -544,7 +544,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user to take ownership, and passes that rule to the method to remove the two rules that allow access. > [!NOTE] -> This example does not attach the security object to a object. See the method and the method. +> This example does not attach the security object to a object. See the method and the method. [!code-csharp[System.Security.AccessControl.RegistrySecurity.RemoveAccessRuleAll#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.RemoveAccessRuleAll/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.RegistrySecurity.RemoveAccessRuleAll#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.RemoveAccessRuleAll/VB/source.vb#1)] @@ -599,7 +599,7 @@ The example creates two rules that allow different rights. The rules have compatible inheritance and propagation flags, so when the second rule is added it merges with the first. The example calls the method, specifying the first rule, but because the rules are merged there is no rule that matches. The example then calls the method to the remove the second rule from the merged rule, and finally calls the method to remove the first rule. > [!NOTE] -> This example does not attach the security object to a object. See the method and the method. +> This example does not attach the security object to a object. See the method and the method. [!code-csharp[System.Security.AccessControl.RegistrySecurity.RemoveAccessRuleSpecific#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.RemoveAccessRuleSpecific/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.RegistrySecurity.RemoveAccessRuleSpecific#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.RemoveAccessRuleSpecific/VB/source.vb#1)] @@ -773,7 +773,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user only to read the key, and uses the method to remove the all rules for the user and replace them with the new rule. > [!NOTE] -> This example does not attach the security object to a object. See the method and the method. +> This example does not attach the security object to a object. See the method and the method. [!code-csharp[System.Security.AccessControl.RegistrySecurity.ResetAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.ResetAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.RegistrySecurity.ResetAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.ResetAccessRule/VB/source.vb#1)] @@ -825,7 +825,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user, with different inheritance and propagation flags. The example then creates a new rule that allows the current user only to read the key, and uses the method to remove the two rules that allow access and to replace them with the new rule. The rule that denies access is not affected. > [!NOTE] -> This example does not attach the security object to a object. See the method and the method. +> This example does not attach the security object to a object. See the method and the method. [!code-csharp[System.Security.AccessControl.RegistrySecurity.SetAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.SetAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.RegistrySecurity.SetAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.RegistrySecurity.SetAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/SemaphoreAccessRule.xml b/xml/System.Security.AccessControl/SemaphoreAccessRule.xml index 807dd97fe6a7b..5f7f875e5ed24 100644 --- a/xml/System.Security.AccessControl/SemaphoreAccessRule.xml +++ b/xml/System.Security.AccessControl/SemaphoreAccessRule.xml @@ -32,7 +32,7 @@ > [!NOTE] > Windows access control security is meaningful only for named system semaphores. If a object represents a local semaphore, access control is irrelevant. - To get a list of the rules currently applied to a named semaphore, use the method to get a object, then use its method to obtain a collection of objects. + To get a list of the rules currently applied to a named semaphore, use the method to get a object, then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for a semaphore, the set contains the minimum number of rules currently required to express all the access control entries. @@ -41,10 +41,10 @@ Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. - To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. +> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. objects are immutable. Security for a semaphore is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -57,7 +57,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/VB/source.vb#1)] @@ -95,7 +95,7 @@ , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. + To enter a , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. ]]> @@ -144,9 +144,9 @@ , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. + To enter a , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. @@ -154,7 +154,7 @@ The following code example demonstrates the use of this constructor to create objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/VB/source.vb#1)] @@ -214,7 +214,7 @@ The following code example demonstrates the use of the property to display the rights in the set of rules contained in a object. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/SemaphoreAuditRule.xml b/xml/System.Security.AccessControl/SemaphoreAuditRule.xml index 4077973ef7f74..ff5e84217d2be 100644 --- a/xml/System.Security.AccessControl/SemaphoreAuditRule.xml +++ b/xml/System.Security.AccessControl/SemaphoreAuditRule.xml @@ -32,17 +32,17 @@ > [!NOTE] > Windows access control security is meaningful only for named system semaphores. If a object represents a local semaphore, access control is irrelevant. - To get a list of the audit rules currently applied to a named semaphore, use the method to get a object, and then use its method to obtain a collection of objects. + To get a list of the audit rules currently applied to a named semaphore, use the method to get a object, and then use its method to obtain a collection of objects. objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all audit rules for a semaphore, the set contains the minimum number of rules currently required to express all the access control entries. > [!NOTE] > The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + Use objects to specify access rights to be audited for a user or group. To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. +> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. objects are immutable. Security for a semaphore is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. @@ -82,7 +82,7 @@ object from a string representing a user or group name, use the constructor. + To create an object from a string representing a user or group name, use the constructor. ]]> diff --git a/xml/System.Security.AccessControl/SemaphoreRights.xml b/xml/System.Security.AccessControl/SemaphoreRights.xml index 869a8f99a4217..c59addf2c7241 100644 --- a/xml/System.Security.AccessControl/SemaphoreRights.xml +++ b/xml/System.Security.AccessControl/SemaphoreRights.xml @@ -29,7 +29,7 @@ enumeration to specify access control rights when you create objects. To apply access rights to a named system semaphore, use objects with the constructor and the method. + Use the enumeration to specify access control rights when you create objects. To apply access rights to a named system semaphore, use objects with the constructor and the method. For the numeric values of the underlying Windows access rights, see [Synchronization Object Security and Access Rights (Windows)](http://go.microsoft.com/fwlink/p/?LinkId=243073) in the MSDN Library. @@ -39,10 +39,10 @@ ## Examples - The following code example demonstrates the use of values when creating and using objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + The following code example demonstrates the use of values when creating and using objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to an object; see , method, and . +> This example does not attach the security object to an object; see , method, and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.AccessControl/SemaphoreSecurity.xml b/xml/System.Security.AccessControl/SemaphoreSecurity.xml index 86c702a3ebfba..0789be65e8099 100644 --- a/xml/System.Security.AccessControl/SemaphoreSecurity.xml +++ b/xml/System.Security.AccessControl/SemaphoreSecurity.xml @@ -54,12 +54,12 @@ - Adding or removing access control entries in ways that do not maintain the canonical ordering. - To modify Windows access control security for a named semaphore, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. + To modify Windows access control security for a named semaphore, use the method to get the object. Modify the security object by adding and removing rules, and then use the method to reattach it. > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. +> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. - To copy access control security from one semaphore to another, use the method to get a object representing the access and audit rules for the first semaphore, then use the method, or a constructor that accepts a object, to assign those rules to the second semaphore. + To copy access control security from one semaphore to another, use the method to get a object representing the access and audit rules for the first semaphore, then use the method, or a constructor that accepts a object, to assign those rules to the second semaphore. Users with an investment in the security descriptor definition language (SDDL) can use the method to set access rules for a named semaphore, and the method to obtain a string that represents the access rules in SDDL format. This is not recommended for new development. @@ -72,7 +72,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/VB/source.vb#1)] @@ -302,7 +302,7 @@ The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.AddAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.AddAccessRule/VB/source.vb#1)] @@ -479,7 +479,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user. The rights allowed include , , and . The example then creates a new rule for the current user, including and rights, and uses that rule with the method to remove from the rule in the object. The extraneous right in `rule` is ignored. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.RemoveAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.RemoveAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.RemoveAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.RemoveAccessRule/VB/source.vb#1)] @@ -528,7 +528,7 @@ The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the rule. The example then creates a new rule that allows the current user to take ownership, and uses that rule to remove the rule from the object. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.RemoveAccessRuleAll#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.RemoveAccessRuleAll/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.RemoveAccessRuleAll#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.RemoveAccessRuleAll/VB/source.vb#1)] @@ -580,7 +580,7 @@ The example creates a object, adds rules that allow and deny various rights for the current user, and then merges additional rights into the access rule. The example then passes the original rule to the method, and displays the results, showing that nothing is deleted. The example then constructs a rule that matches the rule in the object, and successfully uses the method to remove the rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.RemoveAccessRuleSpecific#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.RemoveAccessRuleSpecific/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.RemoveAccessRuleSpecific#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.RemoveAccessRuleSpecific/VB/source.vb#1)] @@ -745,7 +745,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace both of the existing rules with the new rule. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.ResetAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.ResetAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.ResetAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.ResetAccessRule/VB/source.vb#1)] @@ -796,7 +796,7 @@ The example creates a object and adds rules that allow and deny various rights for the current user. The example then creates a new rule that allows the current user full control, and uses the method to replace the existing Allow rule with the new rule. The rule that denies access is not affected. > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . [!code-csharp[System.Security.AccessControl.SemaphoreSecurity.SetAccessRule#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.SetAccessRule/CS/source.cs#1)] [!code-vb[System.Security.AccessControl.SemaphoreSecurity.SetAccessRule#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.AccessControl.SemaphoreSecurity.SetAccessRule/VB/source.vb#1)] diff --git a/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml b/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml index 4ec14115c39e9..601b45c769fda 100644 --- a/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml +++ b/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml @@ -114,7 +114,7 @@ interface for the class. + This constructor implements the interface for the class. The method can be used to serialize an object. This serialized object can then be used with to construct a new object. diff --git a/xml/System.Security.Authentication/CipherAlgorithmType.xml b/xml/System.Security.Authentication/CipherAlgorithmType.xml index 1d94caedf9b22..a263de2bce2fb 100644 --- a/xml/System.Security.Authentication/CipherAlgorithmType.xml +++ b/xml/System.Security.Authentication/CipherAlgorithmType.xml @@ -25,7 +25,7 @@ property. + This enumeration specifies valid values for the property. diff --git a/xml/System.Security.Authentication/ExchangeAlgorithmType.xml b/xml/System.Security.Authentication/ExchangeAlgorithmType.xml index 4fa2b6a444bdc..9669fe2607451 100644 --- a/xml/System.Security.Authentication/ExchangeAlgorithmType.xml +++ b/xml/System.Security.Authentication/ExchangeAlgorithmType.xml @@ -25,7 +25,7 @@ property. + This enumeration specifies valid values for the property. diff --git a/xml/System.Security.Authentication/HashAlgorithmType.xml b/xml/System.Security.Authentication/HashAlgorithmType.xml index 3be41ff2df2a3..e9a86ce9cb315 100644 --- a/xml/System.Security.Authentication/HashAlgorithmType.xml +++ b/xml/System.Security.Authentication/HashAlgorithmType.xml @@ -25,7 +25,7 @@ property. + This enumeration specifies valid values for the property. diff --git a/xml/System.Security.Claims/AuthorizationContext.xml b/xml/System.Security.Claims/AuthorizationContext.xml index 6d843efa9e07a..2819fa6b01eb2 100644 --- a/xml/System.Security.Claims/AuthorizationContext.xml +++ b/xml/System.Security.Claims/AuthorizationContext.xml @@ -121,7 +121,7 @@ property is initialized to contain a name claim () that has the value specified by the `action` parameter. The property is initialized to contain a name claim that has the value specified by the `resource` parameter. + The property is initialized to contain a name claim () that has the value specified by the `action` parameter. The property is initialized to contain a name claim that has the value specified by the `resource` parameter. ]]> diff --git a/xml/System.Security.Claims/Claim.xml b/xml/System.Security.Claims/Claim.xml index 55d1034ffff27..6b712808b72c9 100644 --- a/xml/System.Security.Claims/Claim.xml +++ b/xml/System.Security.Claims/Claim.xml @@ -225,7 +225,7 @@ if (null != principal) property is set to `null`. The and properties are set to . The property is set to + The property is set to `null`. The and properties are set to . The property is set to ]]> diff --git a/xml/System.Security.Claims/ClaimsAuthorizationManager.xml b/xml/System.Security.Claims/ClaimsAuthorizationManager.xml index 7a0dc325e23b1..191f9e7d451f2 100644 --- a/xml/System.Security.Claims/ClaimsAuthorizationManager.xml +++ b/xml/System.Security.Claims/ClaimsAuthorizationManager.xml @@ -31,7 +31,7 @@ The use of a claims authorization manager is optional. You can configure your application to use a claims authorization manager either programmatically by using the class or declaratively, by specifying the [<claimsAuthorizationManager>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager.md) element, which is a child element of the [<identityConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) element in your application configuration file. If your application is a web site or a web application hosted in Internet Information Services (IIS), you must also add the in the ASP.NET HTTP Modules collection. > [!IMPORTANT] -> When you use the class or the class, the claims authorization manager that is used to perform the access check is the one that is specified in the identity configuration under the property. In a configuration file, it is the `` section that is referenced from the default `` element. This is true even for Windows Communication Foundation (WCF) services and desktop applications. +> When you use the class or the class, the claims authorization manager that is used to perform the access check is the one that is specified in the identity configuration under the property. In a configuration file, it is the `` section that is referenced from the default `` element. This is true even for Windows Communication Foundation (WCF) services and desktop applications. The base class does not take any additional configuration; however, you can override the in derived classes to provide initialization of your claims authorization manager from child elements of the ``. The typical scenario is to use these child elements to specify authorization policies which determine which claim types and values are required in order to gain access to which resource. This is not a hard requirement, though you are free to define whatever usage and syntax make sense for your implementation. diff --git a/xml/System.Security.Claims/ClaimsIdentity.xml b/xml/System.Security.Claims/ClaimsIdentity.xml index c37d91ef8f503..fcfa3d7494c2f 100644 --- a/xml/System.Security.Claims/ClaimsIdentity.xml +++ b/xml/System.Security.Claims/ClaimsIdentity.xml @@ -37,15 +37,15 @@ ## Remarks The class is a concrete implementation of a claims-based identity; that is, an identity described by a collection of claims. A claim is a statement about an entity made by an issuer that describes a property, right, or some other quality of that entity. Such an entity is said to be the subject of the claim. A claim is represented by the class. The claims contained in a describe the entity that the corresponding identity represents, and can be used to make authorization and authentication decisions. A claims-based access model has many advantages over more traditional access models that rely exclusively on roles. For example, claims can provide much richer information about the identity they represent and can be evaluated for authorization or authentication in a far more specific manner. - Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent an identity in the .NET Framework now derive from and describe their properties through a collection of claims. This is different from previous versions of the .NET Framework, in which, these classes implemented the interface directly. The collection of claims that describe the identity can be accessed through the property. The class provides several methods for finding and modifying claims and fully supports language integrated queries (LINQ). In application code, objects are typically accessed through objects; for example, the principal returned by . + Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent an identity in the .NET Framework now derive from and describe their properties through a collection of claims. This is different from previous versions of the .NET Framework, in which, these classes implemented the interface directly. The collection of claims that describe the identity can be accessed through the property. The class provides several methods for finding and modifying claims and fully supports language integrated queries (LINQ). In application code, objects are typically accessed through objects; for example, the principal returned by . > [!NOTE] -> The class has a property as well. In the majority of cases you should access the user’s claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. +> The class has a property as well. In the majority of cases you should access the user’s claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. > [!IMPORTANT] > To add or remove claims from the collection, a caller must have full trust. - In the claims-based model, the property and the method are implemented by evaluating the claims contained by an identity. The base implementations in the claims-based model are provided by the property and the method. The and properties enable you to specify a claim type that should be used to evaluate the claims contained by the identity when performing these operations. + In the claims-based model, the property and the method are implemented by evaluating the claims contained by an identity. The base implementations in the claims-based model are provided by the property and the method. The and properties enable you to specify a claim type that should be used to evaluate the claims contained by the identity when performing these operations. Delegation scenarios are supported through the and properties. @@ -297,12 +297,12 @@ |Property|Value| |--------------|-----------| ||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The value of the `identity.AuthenticationType` () property is used.| +||The value of the `identity.AuthenticationType` () property is used.| ||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| ||If `identity` is assignable from , the claims from `identity` are added to the new instance; otherwise, an empty collection.| ||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| ||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| @@ -480,12 +480,12 @@ |Property|Value| |--------------|-----------| ||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| +||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| ||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| ||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| ||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| ||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| @@ -639,12 +639,12 @@ |Property|Value| |--------------|-----------| ||If `identity` is assignable from , the value of the `identity.Actor` property; otherwise, `null`.| -||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| +||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| ||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| ||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| ||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| ||The value of the `nameType` parameter. However, if the value of the `nameType` parameter is `null` or an empty string and `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||The value of the `roleClaimType` parameter. However, if the value of the `roleClaimType` parameter is `null` or an empty string and identity is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| @@ -725,7 +725,7 @@ method is invoked with this claims identity as the parameter to create a new claim with the correct subject. + The claim is examined and if the subject is different than this claims identity, the method is invoked with this claims identity as the parameter to create a new claim with the correct subject. This method has the `SecurityCritical` attribute applied to control which entities can add claims to the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. @@ -773,7 +773,7 @@ method is invoked with this claims identity as the parameter to create a new claim with the correct subject. + Each claim is examined and if the subject is different than this claims identity, the method is invoked with this claims identity as the parameter to create a new claim with the correct subject. This method has the `SecurityCritical` attribute applied to control which entities can add claims to the identity. Further down the pipe, authorization decisions are made based on the claims that are present in the collection. @@ -853,11 +853,11 @@ class. + The underlying object is an instance of the class. Set the `saveBootstrapContext` attribute on either the [<identityConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration.md) or the [<securityTokenHandlerConfiguration>](~/docs/framework/configure-apps/file-schema/windows-identity-foundation/securitytokenhandlerconfiguration.md) element in a configuration file to specify whether the token used to generate the should be preserved in the property. - If the property is not `null`, applications can access the original token and the claims it produced through the properties and methods of the class. + If the property is not `null`, applications can access the original token and the claims it produced through the properties and methods of the class. ]]> @@ -898,7 +898,7 @@ The claims contained in the collection essentially describe the entity that is represented by the . The claims describe the properties and rights possessed by the entity and can be examined by applications to make decisions about authentication and authorization. > [!NOTE] -> The class has a property as well. In the majority of cases you should access the user’s claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. +> The class has a property as well. In the majority of cases you should access the user’s claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. ]]> @@ -1482,7 +1482,7 @@ property specifies the claim type () that is used to provide the name for this identity. The name is accessed through the property. + The property specifies the claim type () that is used to provide the name for this identity. The name is accessed through the property. This property is set by the constructor. @@ -1568,7 +1568,7 @@ ) that is used when evaluating this identity for the method. The method is called to determine whether the current principal is in a specified role. The claims-based model extends this check to use claims presented by the principal. A object can contain one or more objects and each identity object can contain multiple objects. The property specifies the claim type of the claim that should be used to provide the value for the role when evaluating this object. The property is set by the constructor. A common value is . + The role claim type is the claim type () that is used when evaluating this identity for the method. The method is called to determine whether the current principal is in a specified role. The claims-based model extends this check to use claims presented by the principal. A object can contain one or more objects and each identity object can contain multiple objects. The property specifies the claim type of the claim that should be used to provide the value for the role when evaluating this object. The property is set by the constructor. A common value is . ]]> diff --git a/xml/System.Security.Claims/ClaimsPrincipal.xml b/xml/System.Security.Claims/ClaimsPrincipal.xml index 349dc25df3874..60e211491f6c2 100644 --- a/xml/System.Security.Claims/ClaimsPrincipal.xml +++ b/xml/System.Security.Claims/ClaimsPrincipal.xml @@ -49,14 +49,14 @@ - Inline claims-based code access checks can be performed by configuring your application with a custom claims authorization manager and using either the class to perform imperative access checks or the to perform declarative access checks. Claims-based code access checks are performed inline, outside of the processing pipeline, and so are available to all applications as long as a claims authorization manager is configured. - You can obtain a instance for the principal associated with a request in an RP application (or the principal under which a thread is executing) by casting the property to . The claims associated with an object are available through its property. The property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the contains multiple instances, you can use the property or you can access the primary identity by using the property. provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the or methods. + You can obtain a instance for the principal associated with a request in an RP application (or the principal under which a thread is executing) by casting the property to . The claims associated with an object are available through its property. The property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the contains multiple instances, you can use the property or you can access the primary identity by using the property. provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the or methods. > [!NOTE] > To add identities to the , a caller must have full trust. By default, WIF prioritizes objects when selecting the primary identity to return through the property. You can modify this behavior by supplying a delegate through the property to perform the selection. The property provides similar functionality for the property. - In the claim-based model, whether a principal is in a specified role is determined by the claims presented by its underlying identities. The method essentially examines each identity associated with the principal to determine whether it possesses a claim with the specified role value. The type of the claim (represented by its property) used to determine which claims should be examined during role checks is specified on an identity through its property. Thus, the claims examined during role checks can be of a different type for different identities associated with the principal. + In the claim-based model, whether a principal is in a specified role is determined by the claims presented by its underlying identities. The method essentially examines each identity associated with the principal to determine whether it possesses a claim with the specified role value. The type of the claim (represented by its property) used to determine which claims should be examined during role checks is specified on an identity through its property. Thus, the claims examined during role checks can be of a different type for different identities associated with the principal. @@ -251,7 +251,7 @@ if (null != principal) , all of its identities are added to the collection. If the specified principal is not assignable from , a new is created from the in its property and added to the collection. + If the specified principal is assignable from , all of its identities are added to the collection. If the specified principal is not assignable from , a new is created from the in its property and added to the collection. ]]> @@ -559,7 +559,7 @@ if (null != principal) is returned. You can change this behavior by setting the property to specify a delegate to be called to determine the current principal. + By default, is returned. You can change this behavior by setting the property to specify a delegate to be called to determine the current principal. ]]> @@ -979,10 +979,10 @@ if (null != principal) method checks whether an identity that this claims principal possesses contains a claim of type where the value of the claim is equal to the value specified by the `role` parameter. + The method checks whether an identity that this claims principal possesses contains a claim of type where the value of the claim is equal to the value specified by the `role` parameter. > [!NOTE] -> Each has its own definition of the claim type that represents a role. This claim type can be accessed and set through the property. +> Each has its own definition of the claim type that represents a role. This claim type can be accessed and set through the property. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml index 9500e2e5a14ba..4252b059e3e7e 100644 --- a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml +++ b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml @@ -35,7 +35,7 @@ |Property|Default value| |--------------|-------------------| -||| +||| ||1.3.14.3.2.26 (szOID_OIWSEC_sha1)| || if is ,

otherwise| @@ -62,7 +62,7 @@ . An exception to those values when this constructor is used is that is set to . + For the default property values used with this constructor, see . An exception to those values when this constructor is used is that is set to . ]]> @@ -107,7 +107,7 @@ ## Remarks For the default property values used with this constructor, see . - The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. + The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. ]]> @@ -134,7 +134,7 @@ method. + The signing certificate specified by the `certificate` parameter is not checked for validity on input. To validate the certificate prior to supplying it to this constructor, use the method. ]]> @@ -272,7 +272,7 @@ ## Remarks An example of a signed attribute that might be included in the collection retrieved by the property is the signing time attribute. - A object and a object will be automatically generated and placed in the property for the corresponding signer whenever the property is not empty. + A object and a object will be automatically generated and placed in the property for the corresponding signer whenever the property is not empty. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml index 8b9a6a6288fe3..c2aaca2fe9bd8 100644 --- a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml @@ -304,7 +304,7 @@ or any other EnvelopedCms.Decrypt method. + This method should be called before or any other EnvelopedCms.Decrypt method. ]]> @@ -336,16 +336,16 @@ should be called before or any other method. + should be called before or any other method. The method does not search the computer My store if it is inaccessible. ## .NET Framework Security The following permissions are required to access the decryption key: -- +- -- +- ]]> @@ -385,9 +385,9 @@ ## .NET Framework Security The following permissions are required to access the decryption key: -- +- -- +- ]]> @@ -428,9 +428,9 @@ ## .NET Framework Security The following permissions are required to access the decryption key: -- +- -- +- ]]> @@ -473,9 +473,9 @@ ## .NET Framework Security The following permissions are required to access the decryption key: -- +- -- +- ]]> @@ -512,9 +512,9 @@ or another method must be called before this method. + or another method must be called before this method. - The method does not cause the property to be populated. + The method does not cause the property to be populated. ]]> @@ -541,16 +541,16 @@ property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. + This method displays a user interface in which you choose the recipients for whom to encrypt the message. This requires that the current process is running in *user interactive mode*, meaning that the property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. The user interface will only present certificates that are within their validity period and that have key encipherment or key agreement included in their key usage. - The method does not cause the property to be populated. + The method does not cause the property to be populated. ## .NET Framework Security The following permissions are required to display the user interface: -- +- ]]> @@ -585,7 +585,7 @@ method does not cause the property to be populated. + The method does not cause the property to be populated. ]]> @@ -621,7 +621,7 @@ method does not cause the property to be populated. + The method does not cause the property to be populated. ]]> @@ -656,7 +656,7 @@ ## Remarks Although this property is read-only, a modification to the objects in the can be done by using their properties. - The property is not populated as a result of calling the method nor any of the overloaded EnvelopedCms.Encrypt methods. + The property is not populated as a result of calling the method nor any of the overloaded EnvelopedCms.Encrypt methods. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/KeyAgreeRecipientInfo.xml b/xml/System.Security.Cryptography.Pkcs/KeyAgreeRecipientInfo.xml index 93771e68f1a22..5847e070a6607 100644 --- a/xml/System.Security.Cryptography.Pkcs/KeyAgreeRecipientInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/KeyAgreeRecipientInfo.xml @@ -22,7 +22,7 @@ property. + This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/KeyTransRecipientInfo.xml b/xml/System.Security.Cryptography.Pkcs/KeyTransRecipientInfo.xml index 8df6f91c02a6c..19338a89f2ae5 100644 --- a/xml/System.Security.Cryptography.Pkcs/KeyTransRecipientInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/KeyTransRecipientInfo.xml @@ -22,7 +22,7 @@ property. + This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs9ContentType.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs9ContentType.xml index bb16b6b2b8ffa..122cb18dbd3ba 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs9ContentType.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs9ContentType.xml @@ -22,7 +22,7 @@ object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. + A object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs9MessageDigest.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs9MessageDigest.xml index 44eeaa5b37021..3358a45b3d6a5 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs9MessageDigest.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs9MessageDigest.xml @@ -22,7 +22,7 @@ object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. + A object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/RecipientInfoCollection.xml b/xml/System.Security.Cryptography.Pkcs/RecipientInfoCollection.xml index 8b15d306c1dbe..de2fd579f4473 100644 --- a/xml/System.Security.Cryptography.Pkcs/RecipientInfoCollection.xml +++ b/xml/System.Security.Cryptography.Pkcs/RecipientInfoCollection.xml @@ -26,7 +26,7 @@ property. + This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/SignedCms.xml b/xml/System.Security.Cryptography.Pkcs/SignedCms.xml index 0a69bf090f349..527a3efe0d34c 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignedCms.xml @@ -366,7 +366,7 @@ property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. + This method displays a user interface in which you choose signers for this message. This requires that the current process is running in *user interactive mode*, meaning that the property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. Signers whose certificates meet the following conditions will be displayed in the list: @@ -381,13 +381,13 @@ ## .NET Framework Security The following permissions are required to display the user interface: -- +- The following permissions are required to access the signature key: -- +- -- +- @@ -434,9 +434,9 @@ ## .NET Framework Security The following permissions are required to access the signature key: -- +- -- +- @@ -486,13 +486,13 @@ ## .NET Framework Security The following permissions are required to display the user interface: -- +- The following permissions are required to access the signature key: -- +- -- +- ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml b/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml index 761cae5fa3329..5a1a275230d8e 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml @@ -20,7 +20,7 @@ This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. - This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. + This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. ]]> @@ -45,7 +45,7 @@ property, then the certificate will not be returned. + If the signing certificate is not included at signing time by using the property, then the certificate will not be returned. ]]> @@ -166,7 +166,7 @@ ## Remarks This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. - This method displays a user interface in which you choose signers for this message. This requires that the current process is running in *user interactive mode*, meaning that the property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. + This method displays a user interface in which you choose signers for this message. This requires that the current process is running in *user interactive mode*, meaning that the property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. Signers whose certificates meet the following conditions will be displayed in the list: @@ -181,13 +181,13 @@ ## .NET Framework Security The following permissions are required to display the user interface: -- +- The following permissions are required to access the signature key: -- +- -- +- ]]> @@ -222,9 +222,9 @@ ## .NET Framework Security The following permissions are required to access the signature key: -- +- -- +- ]]> @@ -344,7 +344,7 @@ Signed attributes are signed along with the rest of the message content. This means that a party that successfully verifies the signature can have confidence that the contents of these attributes are authentic and have not been altered. - A object and a object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. + A object and a object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/SignerInfoCollection.xml b/xml/System.Security.Cryptography.Pkcs/SignerInfoCollection.xml index e6ccb230a5db8..b95f519873ce1 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignerInfoCollection.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignerInfoCollection.xml @@ -20,7 +20,7 @@ property or the property. + This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property or the property. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml index 9fa1acb849a66..27241cb79a919 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml @@ -373,7 +373,7 @@ ## Remarks This method performs a linear search; therefore, the average execution time is proportional to the property. That is, this method is an O(`n`) operation, where `n` is . - This method determines equality by calling the method. + This method determines equality by calling the method. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2UI.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2UI.xml index 148cd2d9a4c53..163cc3c7a9be1 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2UI.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2UI.xml @@ -131,7 +131,7 @@ method. + Use this method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. ]]> @@ -166,7 +166,7 @@ method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. + Use the method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. @@ -215,7 +215,7 @@ method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. + Use the method if you require users to manually select X.509 certificates using a dialog box. If no user interaction is required, use the method. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509SelectionFlag.xml b/xml/System.Security.Cryptography.X509Certificates/X509SelectionFlag.xml index 6e4599df60632..5d7b7ed4c2dd8 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509SelectionFlag.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509SelectionFlag.xml @@ -15,12 +15,12 @@ method. + This flag represents either a single or multiple certificate selection using the method. ## Examples - The following code example demonstrates how to use the selection flag with the method. This code example is part of a larger example provided for the class. The larger example opens the current user's personal certificate store, allows the user to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate the user selects. + The following code example demonstrates how to use the selection flag with the method. This code example is part of a larger example provided for the class. The larger example opens the current user's personal certificate store, allows the user to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate the user selects. [!code-cpp[x509chaintest#2](~/samples/snippets/cpp/VS_Snippets_CLR/x509chaintest/CPP/x509chaintest.cpp#2)] [!code-csharp[x509chaintest#2](~/samples/snippets/csharp/VS_Snippets_CLR/x509chaintest/CS/x509chaintest.cs#2)] diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml index 1b455169aa60d..d7940b6864618 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml @@ -49,7 +49,7 @@ This example tries to open each standard store in each standard location on the current computer. It prints a summary that shows whether each store exists and, if so, the number of certificates it contains. - The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. + The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. [!code-csharp[x509store2#2](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/storenames1.cs#2)] [!code-vb[x509store2#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/storenames1.vb#2)] @@ -579,7 +579,7 @@ This example tries to open each standard store in each standard location on the current computer. It prints a summary that shows whether each store exists and, if so, the number of certificates it contains. - The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. + The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. [!code-csharp[x509store2#2](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/storenames1.cs#2)] [!code-vb[x509store2#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/storenames1.vb#2)] @@ -739,7 +739,7 @@ This example tries to open each standard store in each standard location on the current computer. It prints a summary that shows whether each store exists and, if so, the number of certificates it contains. - The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. + The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. [!code-csharp[x509store2#2](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/storenames1.cs#2)] [!code-vb[x509store2#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/storenames1.vb#2)] @@ -799,7 +799,7 @@ This example tries to open each standard store in each standard location on the current computer. It prints a summary that shows whether each store exists and, if so, the number of certificates it contains. - The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. + The example creates an object for each combination of standard name and standard location. It calls the method with the flag, which opens the physical store only if it already exists. If the physical store exists, the example uses the , , and properties to display the number of certificates in the store. [!code-csharp[x509store2#2](~/samples/snippets/csharp/VS_Snippets_CLR/x509store2/CS/storenames1.cs#2)] [!code-vb[x509store2#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/x509store2/vb/storenames1.vb#2)] diff --git a/xml/System.Security.Cryptography.Xml/SignedXml.xml b/xml/System.Security.Cryptography.Xml/SignedXml.xml index 2f7cd2bf7d902..34bfa17ba65ea 100644 --- a/xml/System.Security.Cryptography.Xml/SignedXml.xml +++ b/xml/System.Security.Cryptography.Xml/SignedXml.xml @@ -59,7 +59,7 @@ The main parts of this structure are: The <`CanonicalizationMethod`> element - Specifies the rules for rewriting the `Signature` element from XML/text into bytes for signature validation. The default value in the .NET Framework is http://www.w3.org/TR/2001/REC-xml-c14n-20010315, which identifies a trustworthy algorithm. This element is represented by the property. + Specifies the rules for rewriting the `Signature` element from XML/text into bytes for signature validation. The default value in the .NET Framework is http://www.w3.org/TR/2001/REC-xml-c14n-20010315, which identifies a trustworthy algorithm. This element is represented by the property. The <`SignatureMethod`> element Specifies the algorithm used for signature generation and validation, which was applied to the <`Signature`> element to produce the value in <`SignatureValue`>. In the example above, the value http://www.w3.org/2000/09/xmldsig#rsa-sha1 identifies an RSA PKCS1 SHA-1 signature. This element is represented by the property. @@ -68,9 +68,9 @@ Specifies the cryptographic signature for the <`Signature`> element. If this signature does not verify, then some portion of the <`Signature`> block was tampered with, and the document is considered invalid. As long as the <`CanonicalizationMethod`> value is trustworthy, this value is highly resistant to tampering. This element is represented by the property. The `URI` attribute of the <`Reference`> element - Specifies a data object using a URI reference. This attribute is represented by the property. + Specifies a data object using a URI reference. This attribute is represented by the property. -- Not specifying the `URI` attribute, that is, setting the property to `null`, means that the receiving application is expected to know the identity of the object. In most cases, a `null` URI will result in an exception being thrown. Do not use a `null` URI, unless your application is interoperating with a protocol which requires it. +- Not specifying the `URI` attribute, that is, setting the property to `null`, means that the receiving application is expected to know the identity of the object. In most cases, a `null` URI will result in an exception being thrown. Do not use a `null` URI, unless your application is interoperating with a protocol which requires it. - Setting the `URI` attribute to an empty string indicates that the root element of the document is being signed, a form of enveloped signature. @@ -90,7 +90,7 @@ - A value of http://www.w3.org/2000/09/xmldsig#enveloped-signature for the transform algorithm encodes a rule which is interpreted as remove the <`Signature`> element from the document. Otherwise, a verifier of an enveloped signature will digest the document, including the signature, but the signer would have digested the document before the signature was applied, leading to different answers. The <`DigestMethod`> element - Identifies the digest (cryptographic hash) method to apply on the transformed content identified by the `URI` attribute of the <`Reference`> element. This is represented by the property. + Identifies the digest (cryptographic hash) method to apply on the transformed content identified by the `URI` attribute of the <`Reference`> element. This is represented by the property. ## Choosing a canonicalization method Unless interoperating with a specification which requires the use of a different value, we recommend that you use the default canonicalization method in the .NET Framework which is the XML-C14N 1.0 algorithm, whose value is http://www.w3.org/TR/2001/REC-xml-c14n-20010315. The XML-C14N 1.0 algorithm is required to be supported by all implementations of XMLDSIG, particularly as it is an implicit final transform to apply. diff --git a/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml b/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml index 77c4970da7ed4..d0db394d16ada 100644 --- a/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml @@ -140,7 +140,7 @@ method to decrypt an encrypted message. This code example is part of a larger example provided for the class. + The following example shows how to use the method to decrypt an encrypted message. This code example is part of a larger example provided for the class. [!code-csharp[AesCryptoServProvider#3](~/samples/snippets/csharp/VS_Snippets_CLR/aescryptoservprovider/cs/program.cs#3)] [!code-vb[AesCryptoServProvider#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/aescryptoservprovider/vb/program.vb#3)] @@ -220,7 +220,7 @@ ## Examples - The following example shows how to use the method to encrypt a message. This code example is part of a larger example provided for the class. + The following example shows how to use the method to encrypt a message. This code example is part of a larger example provided for the class. [!code-csharp[AesCryptoServProvider#2](~/samples/snippets/csharp/VS_Snippets_CLR/aescryptoservprovider/cs/program.cs#2)] [!code-vb[AesCryptoServProvider#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/aescryptoservprovider/vb/program.vb#2)] diff --git a/xml/System.Security.Cryptography/AesManaged.xml b/xml/System.Security.Cryptography/AesManaged.xml index 9974e6186ebc6..13660cbe7604a 100644 --- a/xml/System.Security.Cryptography/AesManaged.xml +++ b/xml/System.Security.Cryptography/AesManaged.xml @@ -148,7 +148,7 @@ method to decrypt an encrypted message. This code example is part of a larger example provided for the class. + The following example shows how to use the method to decrypt an encrypted message. This code example is part of a larger example provided for the class. [!code-csharp[AesManaged#3](~/samples/snippets/csharp/VS_Snippets_CLR/aesmanaged/cs/program.cs#3)] [!code-vb[AesManaged#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/aesmanaged/vb/program.vb#3)] diff --git a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml index 3dca9ccb3a712..97e368328636d 100644 --- a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml @@ -133,7 +133,7 @@ method. + This method is a simple call to the method. Calling `Dispose` allows the resources used by the class to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md). diff --git a/xml/System.Security.Cryptography/CngKey.xml b/xml/System.Security.Cryptography/CngKey.xml index dc852b048a517..616f05c1601c6 100644 --- a/xml/System.Security.Cryptography/CngKey.xml +++ b/xml/System.Security.Cryptography/CngKey.xml @@ -1073,7 +1073,7 @@ - Key storage provider (KSP): . Use the overload if you want to specify another KSP. -- Key open options: . +- Key open options: . ]]> diff --git a/xml/System.Security.Cryptography/CngKeyCreationParameters.xml b/xml/System.Security.Cryptography/CngKeyCreationParameters.xml index be012782735de..858e48c53b371 100644 --- a/xml/System.Security.Cryptography/CngKeyCreationParameters.xml +++ b/xml/System.Security.Cryptography/CngKeyCreationParameters.xml @@ -127,7 +127,7 @@ object defines options that are used when you create a new object. These options determine whether the key is created in the user or machine key store, and whether a new key should overwrite an existing key. By default, if is not specified, the key is created in the user store. + The returned object defines options that are used when you create a new object. These options determine whether the key is created in the user or machine key store, and whether a new key should overwrite an existing key. By default, if is not specified, the key is created in the user store. ]]> diff --git a/xml/System.Security.Cryptography/CngProperty.xml b/xml/System.Security.Cryptography/CngProperty.xml index f658e49377b0f..b3c680fa7f4cb 100644 --- a/xml/System.Security.Cryptography/CngProperty.xml +++ b/xml/System.Security.Cryptography/CngProperty.xml @@ -300,7 +300,7 @@ ## Remarks objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> @@ -342,7 +342,7 @@ ## Remarks objects are considered equal if their names, values, and options are equivalent. Name comparison is performed in a case-sensitive manner. - The equivalent method for this operator is .]]> + The equivalent method for this operator is .]]> diff --git a/xml/System.Security.Cryptography/CryptoAPITransform.xml b/xml/System.Security.Cryptography/CryptoAPITransform.xml index cc1a340f36712..e30b79eede8c2 100644 --- a/xml/System.Security.Cryptography/CryptoAPITransform.xml +++ b/xml/System.Security.Cryptography/CryptoAPITransform.xml @@ -117,7 +117,7 @@ . + This method is a simple call to . Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md). diff --git a/xml/System.Security.Cryptography/CryptoStream.xml b/xml/System.Security.Cryptography/CryptoStream.xml index 571e4864880a3..428f7014f3e7e 100644 --- a/xml/System.Security.Cryptography/CryptoStream.xml +++ b/xml/System.Security.Cryptography/CryptoStream.xml @@ -237,7 +237,7 @@ implementation. + This method wraps a call to the type's implementation. Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md) diff --git a/xml/System.Security.Cryptography/DSACng.xml b/xml/System.Security.Cryptography/DSACng.xml index d50bc1ea1578a..54a1dc55b49c5 100644 --- a/xml/System.Security.Cryptography/DSACng.xml +++ b/xml/System.Security.Cryptography/DSACng.xml @@ -97,7 +97,7 @@ of `key` must be . + The of `key` must be . This constructor creates a copy of the key. Even if `key` is disposed, the copy of this key object in DSA remains alive. @@ -303,7 +303,7 @@ object is disposed if the key is reset, for instance by changing the property, by using the method to create a new key, or by disposing the parent object. Therefore, you should ensure that the key object is no longer used in these cases. + The object is disposed if the key is reset, for instance by changing the property, by using the method to create a new key, or by disposing the parent object. Therefore, you should ensure that the key object is no longer used in these cases. This object is not the same as the object passed to the constructor, if that constructor was used. However, it will point to the same CNG key. diff --git a/xml/System.Security.Cryptography/DpapiDataProtector.xml b/xml/System.Security.Cryptography/DpapiDataProtector.xml index 7751a56f12e57..b7903e1f61dd7 100644 --- a/xml/System.Security.Cryptography/DpapiDataProtector.xml +++ b/xml/System.Security.Cryptography/DpapiDataProtector.xml @@ -16,7 +16,7 @@ class provides a structured way to protect data by using the class. The class constructor has purpose parameters that serve like a password to identify the protected data. All three parameters are hashed and included as part of the encrypted data string. You must know the purpose parameters to unprotect the data. The method that is called to encrypt the data has an `optionalEntropy` parameter that allows you to add qualifying information to encrypt the data more securely. The hash of the purpose parameters is used for optional entropy. Because you do not need a key to decrypt the data, carefully choosing the purpose data adds another level of security to data protection. + The class provides a structured way to protect data by using the class. The class constructor has purpose parameters that serve like a password to identify the protected data. All three parameters are hashed and included as part of the encrypted data string. You must know the purpose parameters to unprotect the data. The method that is called to encrypt the data has an `optionalEntropy` parameter that allows you to add qualifying information to encrypt the data more securely. The hash of the purpose parameters is used for optional entropy. Because you do not need a key to decrypt the data, carefully choosing the purpose data adds another level of security to data protection. If you use a setting of , only a user with logon credentials that match those of the user who encrypted the data can decrypt the data. In addition, decryption usually can be done only on the computer where the data was encrypted. The Windows function that encrypts the data creates a session key to perform the encryption. The session key is derived again when the data is to be decrypted. For a detailed description of how data is protected by using session keys, see [Windows Data Protection](http://go.microsoft.com/fwlink/?LinkId=224686). diff --git a/xml/System.Security.Cryptography/ECCurve.xml b/xml/System.Security.Cryptography/ECCurve.xml index 390e178d01088..bd80203d0f722 100644 --- a/xml/System.Security.Cryptography/ECCurve.xml +++ b/xml/System.Security.Cryptography/ECCurve.xml @@ -441,7 +441,7 @@ ## Remarks You cannot set a value for the property directly. Instead, to create a named curve, use the , the , or the methods. - On some systems, the property is the primary referenced identifier, while on others it's the property. Manually creating an object with mismatched values may produce undesirable results. + On some systems, the property is the primary referenced identifier, while on others it's the property. Manually creating an object with mismatched values may produce undesirable results. ]]> diff --git a/xml/System.Security.Cryptography/ECDiffieHellman.xml b/xml/System.Security.Cryptography/ECDiffieHellman.xml index 20ec196ecbe61..e83c6a2a19574 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellman.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellman.xml @@ -86,7 +86,7 @@ method. + curve must validate (that is, it must return true when passed to the method. Characteristic-2 curves are not supported on Windows. @@ -119,7 +119,7 @@ method. Parameters over implicit curves are not supported. + `parameters` must validate (that is, it must return `true`) when passed to the method. Parameters over implicit curves are not supported. Characteristic-2 curves are not supported on Windows. @@ -428,7 +428,7 @@ method) and must not be implicit. + `curve` must validate (that is, it must return `true`) when passed to the method) and must not be implicit. Characteristic-2 curves are not supported on Windows. @@ -461,7 +461,7 @@ method. Parameters over implicit curves are not supported. + `parameters` must validate (that is, it must return `true`) when passed to the method. Parameters over implicit curves are not supported. Characteristic-2 curves are not supported on Windows. diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml index 4c6e47ce3c348..4bb4353ace1b1 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml @@ -145,7 +145,7 @@ method and must be either a named or explicit prime. + `curve` must validate (that is, it must return `true`) when passed to the method and must be either a named or explicit prime. ]]> @@ -524,7 +524,7 @@ field contains named curve parameters; otherwise, it contains explicit parameters. + If the key was created as a named curve, the field contains named curve parameters; otherwise, it contains explicit parameters. ]]> @@ -612,7 +612,7 @@ method) and must not be implicit. + `curve` must validate (that is, it must return true when passed to the method) and must not be implicit. Characteristic-2 curves are not supported on Windows. diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml b/xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml index 91567af3fd68c..93284eb6c5751 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanCngPublicKey.xml @@ -102,7 +102,7 @@ field contains named curve parameters; otherwise, it contains explicit parameters. + If the key was created as a named curve, the field contains named curve parameters; otherwise, it contains explicit parameters. ]]> @@ -222,7 +222,7 @@ for information about the XML format that this method uses. + See for information about the XML format that this method uses. ]]> diff --git a/xml/System.Security.Cryptography/ECDsaCng.xml b/xml/System.Security.Cryptography/ECDsaCng.xml index 5accf73b591de..75fb97afcc07f 100644 --- a/xml/System.Security.Cryptography/ECDsaCng.xml +++ b/xml/System.Security.Cryptography/ECDsaCng.xml @@ -178,7 +178,7 @@ method and must be either a named or explicit prime. + `curve` must validate (that is, it must return `true`) when passed to the method and must be either a named or explicit prime. ]]> @@ -628,7 +628,7 @@ ## Remarks This method generates a signature for the specified data by hashing the input data using the property, and then signing the result. - The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. + The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. ]]> @@ -672,7 +672,7 @@ ## Remarks This method generates a signature for the specified data stream by hashing the input data using the property, and then signing the result. - The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. + The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. ]]> @@ -720,7 +720,7 @@ ## Remarks This method generates a signature for the specified data by hashing the input data using the property, and then signing the result - The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. + The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. ]]> @@ -765,7 +765,7 @@ flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. + The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. ]]> diff --git a/xml/System.Security.Cryptography/FromBase64Transform.xml b/xml/System.Security.Cryptography/FromBase64Transform.xml index ee96b9693d000..4ed75d791298d 100644 --- a/xml/System.Security.Cryptography/FromBase64Transform.xml +++ b/xml/System.Security.Cryptography/FromBase64Transform.xml @@ -207,7 +207,7 @@ . + This method is a simple call to . Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md). diff --git a/xml/System.Security.Cryptography/FromBase64TransformMode.xml b/xml/System.Security.Cryptography/FromBase64TransformMode.xml index be75abf729f51..ced74825b81fa 100644 --- a/xml/System.Security.Cryptography/FromBase64TransformMode.xml +++ b/xml/System.Security.Cryptography/FromBase64TransformMode.xml @@ -29,7 +29,7 @@ method. + White space includes the space character as well as tab characters, newline characters, and so on. Characters that constitute white space are those identified by the method. ]]> diff --git a/xml/System.Security.Cryptography/HashAlgorithm.xml b/xml/System.Security.Cryptography/HashAlgorithm.xml index e7f2492999da1..4d8191a1d2773 100644 --- a/xml/System.Security.Cryptography/HashAlgorithm.xml +++ b/xml/System.Security.Cryptography/HashAlgorithm.xml @@ -170,7 +170,7 @@ method. + This method is a simple call to the method. Calling `Dispose` allows the resources used by the class to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md). diff --git a/xml/System.Security.Cryptography/HashAlgorithmName.xml b/xml/System.Security.Cryptography/HashAlgorithmName.xml index f5a72dfeffdbc..ba2ea0d1e30f6 100644 --- a/xml/System.Security.Cryptography/HashAlgorithmName.xml +++ b/xml/System.Security.Cryptography/HashAlgorithmName.xml @@ -456,7 +456,7 @@ method returns the property, if it has been assigned. Otherwise, it returns . + The method returns the property, if it has been assigned. Otherwise, it returns . ]]> diff --git a/xml/System.Security.Cryptography/RSA.xml b/xml/System.Security.Cryptography/RSA.xml index df5c425192e97..dde97789f68c8 100644 --- a/xml/System.Security.Cryptography/RSA.xml +++ b/xml/System.Security.Cryptography/RSA.xml @@ -252,7 +252,7 @@ , also threw a exception. + In the [!INCLUDE[net_v452](~/includes/net-v452-md.md)] and earlier versions of the .NET Framework, this method was `abstract`. However, the only implementation by a derived class, , also threw a exception. ]]> @@ -328,7 +328,7 @@ , also threw a exception. + In the [!INCLUDE[net_v452](~/includes/net-v452-md.md)] and earlier versions of the .NET Framework, this method was `abstract`. However, the only implementation by a derived class, , also threw a exception. ]]> diff --git a/xml/System.Security.Cryptography/RSACng.xml b/xml/System.Security.Cryptography/RSACng.xml index 5ff83fb40f1c8..dd29566a391af 100644 --- a/xml/System.Security.Cryptography/RSACng.xml +++ b/xml/System.Security.Cryptography/RSACng.xml @@ -35,7 +35,7 @@ - performs such operations as signing and verifying signatures by using properties of the object, just as uses its object properties to control signing and verification operations. > [!NOTE] -> The class is an implementation of the RSA algorithm using the Windows CNG libraries and isn't available on operating systems other than Windows. For applications which aren't doing Windows interop, you're encouraged to use instead of referencing this type directly. +> The class is an implementation of the RSA algorithm using the Windows CNG libraries and isn't available on operating systems other than Windows. For applications which aren't doing Windows interop, you're encouraged to use instead of referencing this type directly. ]]> @@ -132,7 +132,7 @@ of `key` must be . + The of `key` must be . This constructor creates a copy of the key. Even if `key` is disposed, the copy of this key object in RSA remains alive. @@ -495,7 +495,7 @@ object is disposed if the key is reset, for instance by changing the property, by using the to create a new key, or by disposing of the parent object. Therefore, you should ensure that the key object is no longer used in these cases. + The returned object is disposed if the key is reset, for instance by changing the property, by using the to create a new key, or by disposing of the parent object. Therefore, you should ensure that the key object is no longer used in these cases. This object is not the same as the object passed to the constructor, if that constructor was used. However, it will point to the same CNG key. diff --git a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml index 4ac7b811ac433..20015e1976cf5 100644 --- a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml @@ -46,7 +46,7 @@ If you do not compensate for the reverse ordering when interoperating between APIs, the class throws a . - To interoperate with CAPI, you must manually reverse the order of encrypted bytes before the encrypted data interoperates with another API. You can easily reverse the order of a managed byte array by calling the method. + To interoperate with CAPI, you must manually reverse the order of encrypted bytes before the encrypted data interoperates with another API. You can easily reverse the order of a managed byte array by calling the method. @@ -425,7 +425,7 @@ or . + `padding` must be either or . ]]> @@ -606,7 +606,7 @@ or . + `padding` must be either or . ]]> diff --git a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml index e55bdfed71879..a2e3f13cbecb7 100644 --- a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml +++ b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml @@ -192,7 +192,7 @@ ## Examples - The following example shows how to use the method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class + The following example shows how to use the method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class [!code-csharp[System.Security.Cryptography.RSAPKCS1KeyExchangeFormatter2#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.security.cryptography.rsapkcs1keyexchangeformatter2/cs/program.cs#2)] [!code-vb[System.Security.Cryptography.RSAPKCS1KeyExchangeFormatter2#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.security.cryptography.rsapkcs1keyexchangeformatter2/vb/program.vb#2)] diff --git a/xml/System.Security.Cryptography/RSAOpenSsl.xml b/xml/System.Security.Cryptography/RSAOpenSsl.xml index 231dd9105e0a6..b888df82aad24 100644 --- a/xml/System.Security.Cryptography/RSAOpenSsl.xml +++ b/xml/System.Security.Cryptography/RSAOpenSsl.xml @@ -18,7 +18,7 @@ ## Remarks > [!NOTE] -> The class is an implementation of the RSA algorithm using OpenSSL. It isn't available on Windows and is only available on other operating systems when OpenSSL is installed. For applications which aren't doing OpenSSL-specific interop, you're encouraged to use instead of referencing this type directly. +> The class is an implementation of the RSA algorithm using OpenSSL. It isn't available on Windows and is only available on other operating systems when OpenSSL is installed. For applications which aren't doing OpenSSL-specific interop, you're encouraged to use instead of referencing this type directly. ]]> diff --git a/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml b/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml index 5ddda582d6596..491155483752b 100644 --- a/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml +++ b/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml @@ -189,7 +189,7 @@ ## Examples - The following example shows how to use the method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class. + The following example shows how to use the method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class. [!code-csharp[System.Security.Cryptography.RSAPKCS1KeyExchangeFormatter2#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.security.cryptography.rsapkcs1keyexchangeformatter2/cs/program.cs#2)] [!code-vb[System.Security.Cryptography.RSAPKCS1KeyExchangeFormatter2#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.security.cryptography.rsapkcs1keyexchangeformatter2/vb/program.vb#2)] diff --git a/xml/System.Security.Cryptography/RijndaelManagedTransform.xml b/xml/System.Security.Cryptography/RijndaelManagedTransform.xml index 74d464946e35d..df30b45eb65d6 100644 --- a/xml/System.Security.Cryptography/RijndaelManagedTransform.xml +++ b/xml/System.Security.Cryptography/RijndaelManagedTransform.xml @@ -114,7 +114,7 @@ class. + This method is a simple call to class. Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md). diff --git a/xml/System.Security.Cryptography/ToBase64Transform.xml b/xml/System.Security.Cryptography/ToBase64Transform.xml index 40960ba6a77fa..5ef6856eae16c 100644 --- a/xml/System.Security.Cryptography/ToBase64Transform.xml +++ b/xml/System.Security.Cryptography/ToBase64Transform.xml @@ -182,7 +182,7 @@ . + This method is a simple call to . Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md). diff --git a/xml/System.Security.Permissions/DataProtectionPermissionAttribute.xml b/xml/System.Security.Permissions/DataProtectionPermissionAttribute.xml index abbe53d9bc17b..660d267875ac2 100644 --- a/xml/System.Security.Permissions/DataProtectionPermissionAttribute.xml +++ b/xml/System.Security.Permissions/DataProtectionPermissionAttribute.xml @@ -113,7 +113,7 @@ occurs when the method is called. + If the value is `false`, a occurs when the method is called. ]]> @@ -139,7 +139,7 @@ occurs when the method is called. + If the value is `false`, a occurs when the method is called. ]]> @@ -165,7 +165,7 @@ occurs when the method is called. + If this value is `false`, a occurs when the method is called. ]]> @@ -191,7 +191,7 @@ occurs when the method is called. + If this value is `false`, a occurs when the method is called. ]]> diff --git a/xml/System.Security.Permissions/EnvironmentPermission.xml b/xml/System.Security.Permissions/EnvironmentPermission.xml index c2e9d975b11e5..3c643bc7ba2f6 100644 --- a/xml/System.Security.Permissions/EnvironmentPermission.xml +++ b/xml/System.Security.Permissions/EnvironmentPermission.xml @@ -33,7 +33,7 @@ Environment variable names are designated by one or more case-insensitive name lists separated by semicolons, with separate lists for read and write access to the named variables. Write access includes the ability to create and delete environment variables as well as to change existing values. > [!NOTE] -> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). +> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). ]]> diff --git a/xml/System.Security.Permissions/FileIOPermission.xml b/xml/System.Security.Permissions/FileIOPermission.xml index 77504af1ee03c..fe44852e36893 100644 --- a/xml/System.Security.Permissions/FileIOPermission.xml +++ b/xml/System.Security.Permissions/FileIOPermission.xml @@ -52,7 +52,7 @@ Access to a folder implies access to all the files it contains, as well as access to all the files and folders in its subfolders. For example, `Read` access to C:\folder1\ implies `Read` access to C:\folder1\file1.txt, C:\folder1\folder2\\, C:\folder1\folder2\file2.txt, and so on. > [!NOTE] -> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). +> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). @@ -144,7 +144,7 @@ ## Examples - The following code example shows the use of the constructor to create a new instance of the class, which provides complete access to the C:\test_r file. + The following code example shows the use of the constructor to create a new instance of the class, which provides complete access to the C:\test_r file. [!code-cpp[Classic FileIOPermission Example#2](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic FileIOPermission Example/CPP/source.cpp#2)] [!code-csharp[Classic FileIOPermission Example#2](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic FileIOPermission Example/CS/source.cs#2)] @@ -326,7 +326,7 @@ ## Examples - The following code example shows the use of the method. + The following code example shows the use of the method. [!code-cpp[Classic FileIOPermission Example#2](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic FileIOPermission Example/CPP/source.cpp#2)] [!code-csharp[Classic FileIOPermission Example#2](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic FileIOPermission Example/CS/source.cs#2)] @@ -809,7 +809,7 @@ ## Examples - The following code example shows the use of the method. + The following code example shows the use of the method. [!code-cpp[System.Security.Permissions.FileIOPermission#7](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.FileIOPermission/CPP/fileiopermission.cpp#7)] [!code-csharp[System.Security.Permissions.FileIOPermission#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.FileIOPermission/CS/fileiopermission.cs#7)] diff --git a/xml/System.Security.Permissions/GacIdentityPermission.xml b/xml/System.Security.Permissions/GacIdentityPermission.xml index 9128ea31eb6c2..dd707b493cefd 100644 --- a/xml/System.Security.Permissions/GacIdentityPermission.xml +++ b/xml/System.Security.Permissions/GacIdentityPermission.xml @@ -104,7 +104,7 @@ ## Examples - The following code example shows the use of the constructor. + The following code example shows the use of the constructor. [!code-cpp[System.Security.Permissions.GacIdentityPermission#7](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.GacIdentityPermission/CPP/gacidentitypermission.cpp#7)] [!code-csharp[System.Security.Permissions.GacIdentityPermission#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.GacIdentityPermission/CS/gacidentitypermission.cs#7)] diff --git a/xml/System.Security.Permissions/KeyContainerPermission.xml b/xml/System.Security.Permissions/KeyContainerPermission.xml index 2bbbfca80ac6c..8c1d7dd08d856 100644 --- a/xml/System.Security.Permissions/KeyContainerPermission.xml +++ b/xml/System.Security.Permissions/KeyContainerPermission.xml @@ -60,7 +60,7 @@ constructor. + The following code example shows the use of the constructor. [!code-cpp[System.Security.Permissions.KeyContainerPermission#20](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.KeyContainerPermission/CPP/keycontainerpermission.cpp#20)] [!code-csharp[System.Security.Permissions.KeyContainerPermission#20](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.KeyContainerPermission/CS/keycontainerpermission.cs#20)] @@ -130,7 +130,7 @@ constructor. + The following code example shows the use of the constructor. [!code-cpp[System.Security.Permissions.KeyContainerPermission#13](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.KeyContainerPermission/CPP/keycontainerpermission.cpp#13)] [!code-csharp[System.Security.Permissions.KeyContainerPermission#13](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.KeyContainerPermission/CS/keycontainerpermission.cs#13)] diff --git a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml index a920fdca3e331..a31d59e4cd48b 100644 --- a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml +++ b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml @@ -307,7 +307,7 @@ property and always returns `false`. + This property implements the property and always returns `false`. ]]> @@ -412,7 +412,7 @@ ## Remarks The object returned in this implementation is the object itself. - For more information on the property, see the property of the interface. + For more information on the property, see the property of the interface. ]]> diff --git a/xml/System.Security.Permissions/PublisherIdentityPermission.xml b/xml/System.Security.Permissions/PublisherIdentityPermission.xml index 2e524429967ea..60d0fc7e8b277 100644 --- a/xml/System.Security.Permissions/PublisherIdentityPermission.xml +++ b/xml/System.Security.Permissions/PublisherIdentityPermission.xml @@ -107,7 +107,7 @@ ## Examples - The following example shows how to use the constructor. + The following example shows how to use the constructor. [!code-cpp[System.Security.Permissions.PublisherIdentityPermission#7](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.PublisherIdentityPermission/CPP/publisheridentitypermission.cpp#7)] [!code-csharp[System.Security.Permissions.PublisherIdentityPermission#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.PublisherIdentityPermission/CS/publisheridentitypermission.cs#7)] diff --git a/xml/System.Security.Permissions/ReflectionPermission.xml b/xml/System.Security.Permissions/ReflectionPermission.xml index 777281b5d02ef..8ad9d8404211e 100644 --- a/xml/System.Security.Permissions/ReflectionPermission.xml +++ b/xml/System.Security.Permissions/ReflectionPermission.xml @@ -33,9 +33,9 @@ Without , code can use reflection to access only the public members of objects. Code with and the appropriate flags can access the `protected` and `private` members of objects. > [!CAUTION] -> Because can provide access to non-public types and members, we recommend that you do not grant to Internet code, except with the flag. allows access to non-public members, with the restriction that the grant set of the non-public members must be equal to, or a subset of, the grant set of the code that accesses the non-public members. +> Because can provide access to non-public types and members, we recommend that you do not grant to Internet code, except with the flag. allows access to non-public members, with the restriction that the grant set of the non-public members must be equal to, or a subset of, the grant set of the code that accesses the non-public members. - Certain features of reflection emit, such as emitting debug symbols, require with the flag. + Certain features of reflection emit, such as emitting debug symbols, require with the flag. For more information, see the enumeration. @@ -72,7 +72,7 @@ ## Examples - The following code example shows the use of the constructor. This example is part of a larger example provided for the class. + The following code example shows the use of the constructor. This example is part of a larger example provided for the class. [!code-csharp[System.Security.Permissions.ReflectionPermission#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.ReflectionPermission/CS/reflectionpermission.cs#7)] [!code-vb[System.Security.Permissions.ReflectionPermission#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.ReflectionPermission/VB/reflectionpermission.vb#7)] @@ -106,7 +106,7 @@ constructor. This example is part of a larger example provided for the class. + The following code example shows the use of the constructor. This example is part of a larger example provided for the class. [!code-csharp[System.Security.Permissions.ReflectionPermission#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.ReflectionPermission/CS/reflectionpermission.cs#8)] [!code-vb[System.Security.Permissions.ReflectionPermission#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.ReflectionPermission/VB/reflectionpermission.vb#8)] diff --git a/xml/System.Security.Permissions/ReflectionPermissionAttribute.xml b/xml/System.Security.Permissions/ReflectionPermissionAttribute.xml index fcf754047275b..c5f06ce91b090 100644 --- a/xml/System.Security.Permissions/ReflectionPermissionAttribute.xml +++ b/xml/System.Security.Permissions/ReflectionPermissionAttribute.xml @@ -173,7 +173,7 @@ ## Remarks > [!NOTE] -> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], emitting code no longer requires with the flag. Some features of reflection emit, such as emitting debug symbols, still require the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) +> Starting with the [!INCLUDE[net_v20sp1_long](~/includes/net-v20sp1-long-md.md)], emitting code no longer requires with the flag. Some features of reflection emit, such as emitting debug symbols, still require the flag. (See [Security Issues in Reflection Emit](~/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md).) > > To use this functionality, your application should target the [!INCLUDE[net_v35_long](~/includes/net-v35-long-md.md)] or later. diff --git a/xml/System.Security.Permissions/RegistryPermission.xml b/xml/System.Security.Permissions/RegistryPermission.xml index 9b9b0e09995c9..4543fe83144a5 100644 --- a/xml/System.Security.Permissions/RegistryPermission.xml +++ b/xml/System.Security.Permissions/RegistryPermission.xml @@ -37,7 +37,7 @@ Registry permission is defined in terms of canonical absolute paths; checks should always be made with canonical pathnames. Key access implies access to all values it contains and all variables under it. > [!NOTE] -> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). +> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). ]]> diff --git a/xml/System.Security.Permissions/SiteIdentityPermission.xml b/xml/System.Security.Permissions/SiteIdentityPermission.xml index fb364be6a574d..1dcf8cc02a094 100644 --- a/xml/System.Security.Permissions/SiteIdentityPermission.xml +++ b/xml/System.Security.Permissions/SiteIdentityPermission.xml @@ -36,7 +36,7 @@ > In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. Starting with the .NET Framework version 2.0, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. > [!NOTE] -> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). +> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). > [!NOTE] > In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. diff --git a/xml/System.Security.Permissions/StorePermissionAttribute.xml b/xml/System.Security.Permissions/StorePermissionAttribute.xml index 6d0ebd5179654..29b278df4c50b 100644 --- a/xml/System.Security.Permissions/StorePermissionAttribute.xml +++ b/xml/System.Security.Permissions/StorePermissionAttribute.xml @@ -141,7 +141,7 @@ method. + New stores are created by calling the method. ]]> diff --git a/xml/System.Security.Permissions/StorePermissionFlags.xml b/xml/System.Security.Permissions/StorePermissionFlags.xml index 985e5c2877e74..4d920a5a7bcd1 100644 --- a/xml/System.Security.Permissions/StorePermissionFlags.xml +++ b/xml/System.Security.Permissions/StorePermissionFlags.xml @@ -109,7 +109,7 @@ method. + New stores are created by calling the method. ]]> diff --git a/xml/System.Security.Permissions/UIPermission.xml b/xml/System.Security.Permissions/UIPermission.xml index 2f40f22132c98..df5c1aa202660 100644 --- a/xml/System.Security.Permissions/UIPermission.xml +++ b/xml/System.Security.Permissions/UIPermission.xml @@ -109,7 +109,7 @@ ## Examples - The following code example shows the use of the constructor. This example is part of a larger example provided for the class. + The following code example shows the use of the constructor. This example is part of a larger example provided for the class. [!code-cpp[System.Security.Permissions.UIPermission#9](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.UIPermission/CPP/uipermission.cpp#9)] [!code-csharp[System.Security.Permissions.UIPermission#9](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.UIPermission/CS/uipermission.cs#9)] @@ -149,7 +149,7 @@ ## Examples - The following code example shows the use of the constructor. This example is part of a larger example provided for the class. + The following code example shows the use of the constructor. This example is part of a larger example provided for the class. [!code-cpp[System.Security.Permissions.UIPermission#8](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.UIPermission/CPP/uipermission.cpp#8)] [!code-csharp[System.Security.Permissions.UIPermission#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.UIPermission/CS/uipermission.cs#8)] @@ -186,7 +186,7 @@ constructor. This example is part of a larger example provided for the class. + The following code example shows the use of the constructor. This example is part of a larger example provided for the class. [!code-cpp[System.Security.Permissions.UIPermission#10](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.UIPermission/CPP/uipermission.cpp#10)] [!code-csharp[System.Security.Permissions.UIPermission#10](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.UIPermission/CS/uipermission.cs#10)] diff --git a/xml/System.Security.Permissions/UrlIdentityPermission.xml b/xml/System.Security.Permissions/UrlIdentityPermission.xml index 4c439d90da7e0..3b49758d9d057 100644 --- a/xml/System.Security.Permissions/UrlIdentityPermission.xml +++ b/xml/System.Security.Permissions/UrlIdentityPermission.xml @@ -38,7 +38,7 @@ In the .NET Framework versions 1.0 and 1.1, demands on the identity permissions are effective, even when the calling assembly is fully trusted. That is, although the calling assembly has full trust, a demand for an identity permission fails if the assembly does not meet the demanded criteria. Starting with the .NET Framework version 2.0, demands for identity permissions are ineffective if the calling assembly has full trust. This assures consistency for all permissions, eliminating the treatment of identity permissions as a special case. > [!NOTE] -> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). +> In versions of the .NET Framework before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you could use the method to prevent inadvertent access to system resources by trusted code. is now obsolete, and access to resources is now determined solely by the granted permission set for an assembly. To limit access to files, you must run partially trusted code in a sandbox and assign it permissions only to resources that the code is allowed to access. For information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). > [!NOTE] > In the .NET Framework versions 1.0 and 1.1, identity permissions cannot have an permission state value. Starting with the .NET Framework version 2.0, identity permissions can have any permission state value. This means that in 2.0 and later versions, identity permissions have the same behavior as permissions that implement the interface. @@ -81,7 +81,7 @@ ## Examples - The following example shows the use of the constructor. + The following example shows the use of the constructor. [!code-cpp[System.Security.Permissions.UrlIdentityPermission#7](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.UrlIdentityPermission/CPP/urlidentity.cpp#7)] [!code-csharp[System.Security.Permissions.UrlIdentityPermission#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.UrlIdentityPermission/CS/urlidentity.cs#7)] @@ -126,7 +126,7 @@ ## Examples - The following example shows the use of the constructor. + The following example shows the use of the constructor. [!code-cpp[System.Security.Permissions.UrlIdentityPermission#8](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Permissions.UrlIdentityPermission/CPP/urlidentity.cpp#8)] [!code-csharp[System.Security.Permissions.UrlIdentityPermission#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.UrlIdentityPermission/CS/urlidentity.cs#8)] diff --git a/xml/System.Security.Permissions/ZoneIdentityPermission.xml b/xml/System.Security.Permissions/ZoneIdentityPermission.xml index bbf1f6585ac20..382f03361b78e 100644 --- a/xml/System.Security.Permissions/ZoneIdentityPermission.xml +++ b/xml/System.Security.Permissions/ZoneIdentityPermission.xml @@ -81,7 +81,7 @@ ## Examples - The following example shows the use of the constructor. + The following example shows the use of the constructor. [!code-csharp[System.Security.Permissions.ZoneIdentityPermission#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.ZoneIdentityPermission/CS/zoneidentity.cs#7)] [!code-vb[System.Security.Permissions.ZoneIdentityPermission#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.ZoneIdentityPermission/VB/zoneidentity.vb#7)] @@ -115,7 +115,7 @@ constructor. + The following example shows the use of the constructor. [!code-csharp[System.Security.Permissions.ZoneIdentityPermission#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Permissions.ZoneIdentityPermission/CS/zoneidentity.cs#8)] [!code-vb[System.Security.Permissions.ZoneIdentityPermission#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Permissions.ZoneIdentityPermission/VB/zoneidentity.vb#8)] diff --git a/xml/System.Security.Policy/ApplicationTrust.xml b/xml/System.Security.Policy/ApplicationTrust.xml index 3ce4aee3bf456..1bb276f8c046c 100644 --- a/xml/System.Security.Policy/ApplicationTrust.xml +++ b/xml/System.Security.Policy/ApplicationTrust.xml @@ -119,7 +119,7 @@ that are to be granted full trust. This constructor is called by the method to create an that will be used as a sandbox. For more information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). + `fullTrustAssemblies` identifies strong-named assemblies within the that are to be granted full trust. This constructor is called by the method to create an that will be used as a sandbox. For more information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](~/docs/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox.md). ]]> diff --git a/xml/System.Security.Policy/ApplicationTrustCollection.xml b/xml/System.Security.Policy/ApplicationTrustCollection.xml index dc575958611ae..21f69097376e4 100644 --- a/xml/System.Security.Policy/ApplicationTrustCollection.xml +++ b/xml/System.Security.Policy/ApplicationTrustCollection.xml @@ -314,16 +314,16 @@ implements the interface that allows you to move within a collection. + The implements the interface that allows you to move within a collection. - Use the property to get the item currently pointed to in the collection. + Use the property to get the item currently pointed to in the collection. - Use the method to move to the next item in the collection. + Use the method to move to the next item in the collection. - Use the method to move the enumerator to its initial position. + Use the method to move the enumerator to its initial position. > [!NOTE] -> After you create the enumerator, or use the method to reposition the enumerator to the start of the collection, you must then call the method to position the enumerator to the first item. Otherwise, the item represented by the property is undefined. +> After you create the enumerator, or use the method to reposition the enumerator to the start of the collection, you must then call the method to position the enumerator to the first item. Otherwise, the item represented by the property is undefined. ]]> diff --git a/xml/System.Security.Policy/EvidenceBase.xml b/xml/System.Security.Policy/EvidenceBase.xml index 64be84e02c1a6..8e432ff769d16 100644 --- a/xml/System.Security.Policy/EvidenceBase.xml +++ b/xml/System.Security.Policy/EvidenceBase.xml @@ -21,7 +21,7 @@ objects as evidence. The common language runtime (CLR) considered evidence objects as references, and did not apply any type safety to them. + Before the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], almost any object could be used as an evidence object if the hosting code wanted to apply it as evidence. For example, some .NET Framework code recognized objects as evidence. The common language runtime (CLR) considered evidence objects as references, and did not apply any type safety to them. This presented a problem because there were implicit restrictions on which types could be used as evidence objects. Specifically, any object used as evidence had to be serializable and could not be `null`. If these requirements were not met, the CLR threw an exception whenever an operation that required one of these assumptions was performed. diff --git a/xml/System.Security.Policy/IApplicationTrustManager.xml b/xml/System.Security.Policy/IApplicationTrustManager.xml index 4d859f0ab963d..95ff6c3ac33a0 100644 --- a/xml/System.Security.Policy/IApplicationTrustManager.xml +++ b/xml/System.Security.Policy/IApplicationTrustManager.xml @@ -23,7 +23,7 @@ interface. The host calls the method to determine whether an application should be executed and which permissions should be granted to the application. + Trust managers must implement the interface. The host calls the method to determine whether an application should be executed and which permissions should be granted to the application. In the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)] and later, there is only one trust manager, which can be a custom implementation of the interface. The default trust manager implementation prompts the user for permission to install the application and to elevate the permissions granted to the application. Other trust manager implementations might provide different user experiences. For example, an implementation might check an enterprise list for trusted applications instead of prompting the user for that information. diff --git a/xml/System.Security.Policy/NetCodeGroup.xml b/xml/System.Security.Policy/NetCodeGroup.xml index 4ecc875063411..990d53bfeb812 100644 --- a/xml/System.Security.Policy/NetCodeGroup.xml +++ b/xml/System.Security.Policy/NetCodeGroup.xml @@ -368,7 +368,7 @@ property value is the origin scheme, and the property value is the array of associated objects. If there are no associated objects, returns an empty array. + In each dictionary entry, the property value is the origin scheme, and the property value is the array of associated objects. If there are no associated objects, returns an empty array. diff --git a/xml/System.Security.Policy/PolicyLevel.xml b/xml/System.Security.Policy/PolicyLevel.xml index 2e7d6afe889f5..d1bc2a6ece667 100644 --- a/xml/System.Security.Policy/PolicyLevel.xml +++ b/xml/System.Security.Policy/PolicyLevel.xml @@ -42,7 +42,7 @@ A policy level consists of a set of code groups organized into a single rooted tree (see ), a set of named permission sets that are referenced by the code groups to specify permissions to be granted to code belonging to the code group, and a list of fully-trusted assemblies. - Use to enumerate the policy levels. + Use to enumerate the policy levels. ]]> diff --git a/xml/System.Security.Principal/IdentityReference.xml b/xml/System.Security.Principal/IdentityReference.xml index c243bba667fdf..3d2b7da0da5b5 100644 --- a/xml/System.Security.Principal/IdentityReference.xml +++ b/xml/System.Security.Principal/IdentityReference.xml @@ -140,7 +140,7 @@ if and are equal; otherwise, . - .]]> + .]]> @@ -173,7 +173,7 @@ if and are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Security.Principal/WindowsPrincipal.xml b/xml/System.Security.Principal/WindowsPrincipal.xml index fe925dac0d892..a4cd49bf3009b 100644 --- a/xml/System.Security.Principal/WindowsPrincipal.xml +++ b/xml/System.Security.Principal/WindowsPrincipal.xml @@ -27,7 +27,7 @@ class is primarily used to check the role of a Windows user. The method overloads let you check the user role by using different role contexts. + The class is primarily used to check the role of a Windows user. The method overloads let you check the user role by using different role contexts. @@ -280,7 +280,7 @@ ## Examples - The following code example demonstrates the use of the method. The enumeration value is used to determine whether the current principal is an administrator. For the full code example, see the method. + The following code example demonstrates the use of the method. The enumeration value is used to determine whether the current principal is an administrator. For the full code example, see the method. [!code-csharp[System.Security.Principal.WindowsBuiltInRole Example#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CS/source.cs#5)] [!code-vb[System.Security.Principal.WindowsBuiltInRole Example#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/VB/source.vb#5)] @@ -332,7 +332,7 @@ ## Examples - The following example uses the enumeration is used to determine whether the current principal is an . For the full code example, see the method. + The following example uses the enumeration is used to determine whether the current principal is an . For the full code example, see the method. [!code-csharp[System.Security.Principal.WindowsBuiltInRole Example#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CS/source.cs#4)] [!code-vb[System.Security.Principal.WindowsBuiltInRole Example#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/VB/source.vb#4)] @@ -406,9 +406,9 @@ ## Examples - The following code example demonstrates the use of the method. + The following code example demonstrates the use of the method. - The strings `BUILTIN\Administrators` and `BUILTIN\Users` are used to determine whether the current principal is an administrator or a user. For the full code example, see the method. + The strings `BUILTIN\Administrators` and `BUILTIN\Users` are used to determine whether the current principal is an administrator or a user. For the full code example, see the method. [!code-csharp[System.Security.Principal.WindowsBuiltInRole Example#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CS/source.cs#3)] [!code-vb[System.Security.Principal.WindowsBuiltInRole Example#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/VB/source.vb#3)] diff --git a/xml/System.Security/AllowPartiallyTrustedCallersAttribute.xml b/xml/System.Security/AllowPartiallyTrustedCallersAttribute.xml index 919717f82674c..f6cd712fa71d3 100644 --- a/xml/System.Security/AllowPartiallyTrustedCallersAttribute.xml +++ b/xml/System.Security/AllowPartiallyTrustedCallersAttribute.xml @@ -50,7 +50,7 @@ When the APTCA attribute is present, all other security checks function as intended, including any class-level or method-level declarative security attributes that are present. This attribute blocks only the implicit, fully trusted caller demand. - This is not a declarative security attribute, but a regular attribute (it derives from , not from ). + This is not a declarative security attribute, but a regular attribute (it derives from , not from ). For more information, see [Using Libraries from Partially Trusted Code](~/docs/framework/misc/using-libraries-from-partially-trusted-code.md). @@ -159,7 +159,7 @@ [assembly: AllowPartiallyTrustedCallers(PartialTrustVisibilityLevel=NotVisibleByDefault)] ``` - The assembly has been audited for partial trust, but it is not visible to partial-trust code by default. To make the assembly visible to partial-trust code, add it to the property. + The assembly has been audited for partial trust, but it is not visible to partial-trust code by default. To make the assembly visible to partial-trust code, add it to the property. ]]> diff --git a/xml/System.Security/CodeAccessPermission.xml b/xml/System.Security/CodeAccessPermission.xml index f2479315653b4..857f29a02f7a9 100644 --- a/xml/System.Security/CodeAccessPermission.xml +++ b/xml/System.Security/CodeAccessPermission.xml @@ -33,7 +33,7 @@ . + Code access permissions use a stack walk to ensure that all callers of the code have been granted a permission. If a permission object is `null`, it is handled the same as a permission object with the state . The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. diff --git a/xml/System.Security/HostProtectionException.xml b/xml/System.Security/HostProtectionException.xml index b29175a1fee8b..f7b40b4bb9791 100644 --- a/xml/System.Security/HostProtectionException.xml +++ b/xml/System.Security/HostProtectionException.xml @@ -60,8 +60,8 @@ |Property|Value| |--------------|-----------| -||| -||| +||| +||| ]]> @@ -191,7 +191,7 @@ attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised with a `demandedResources` property value of . + The `demandedResources` parameter specifies the demanded host protection categories that caused the exception to be thrown. For example, suppose that a method has a attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised with a `demandedResources` property value of . ]]> @@ -221,7 +221,7 @@ attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised, and the value of the property is . + This property returns the demanded host protection categories that caused the exception to be thrown. For example, suppose that a method has a attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised, and the value of the property is . ]]> diff --git a/xml/System.Security/HostSecurityManager.xml b/xml/System.Security/HostSecurityManager.xml index b22a3ed5913ac..83ddddd74e49f 100644 --- a/xml/System.Security/HostSecurityManager.xml +++ b/xml/System.Security/HostSecurityManager.xml @@ -237,7 +237,7 @@ ## Remarks This method can be overridden by a derived class. The base implementation returns `null`. - The common language runtime calls this method when evidence of the specified type is needed for the current . The returned value is used as host-supplied evidence, and is stored in the collection of the property. You can use the method to obtain the generated evidence from the collection. + The common language runtime calls this method when evidence of the specified type is needed for the current . The returned value is used as host-supplied evidence, and is stored in the collection of the property. You can use the method to obtain the generated evidence from the collection. To get a callback to this method, hosts must specify the flag in the property. @@ -290,7 +290,7 @@ ## Remarks This method can be overridden by a derived class. The base implementation returns `null`. - The common language runtime calls this method when evidence of the specified type is needed for the current assembly. The returned value is used as host-supplied evidence, and is stored in the property. You can use the method to obtain the generated evidence from the property. + The common language runtime calls this method when evidence of the specified type is needed for the current assembly. The returned value is used as host-supplied evidence, and is stored in the property. You can use the method to obtain the generated evidence from the property. To get a callback to this method, hosts must specify the flag in the property. diff --git a/xml/System.Security/IPermission.xml b/xml/System.Security/IPermission.xml index c8748fb4e91ab..cff8d51f92cf9 100644 --- a/xml/System.Security/IPermission.xml +++ b/xml/System.Security/IPermission.xml @@ -134,7 +134,7 @@ ## Remarks This method is typically used by secure libraries to ensure that callers have permission to access a resource. For example, a file class in a secure class library calls for the necessary before performing a file operation requested by the caller. - Although the majority of the classes that implement this interface method satisfy the security criteria by performing a full stack walk, a stack walk is not necessarily performed. An example of an implementation that does not perform a stack walk is . + Although the majority of the classes that implement this interface method satisfy the security criteria by performing a full stack walk, a stack walk is not necessarily performed. An example of an implementation that does not perform a stack walk is . When a stack walk is performed, the permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. succeeds only if no is raised. diff --git a/xml/System.Security/PartialTrustVisibilityLevel.xml b/xml/System.Security/PartialTrustVisibilityLevel.xml index 59328083a9881..fac6dd28754f0 100644 --- a/xml/System.Security/PartialTrustVisibilityLevel.xml +++ b/xml/System.Security/PartialTrustVisibilityLevel.xml @@ -24,7 +24,7 @@ is passed as a property setting parameter to the constructor. If no parameter is passed to the constructor, the default is VisibleToAllHosts. + is passed as a property setting parameter to the constructor. If no parameter is passed to the constructor, the default is VisibleToAllHosts. You enable partially trusted assemblies that are identified as NotVisibleByDefault by adding them to the property of their application domain. If you enable an assembly that references (directly or indirectly) other partially trusted assemblies that are NotVisibleByDefault, those other assemblies should be enabled as well. diff --git a/xml/System.Security/PermissionSet.xml b/xml/System.Security/PermissionSet.xml index 3a6ba8d1fddf9..db2d067f7f6ec 100644 --- a/xml/System.Security/PermissionSet.xml +++ b/xml/System.Security/PermissionSet.xml @@ -237,7 +237,7 @@ can be active on a frame. is only effective for granted permissions. Call the or method to cancel an active . + This is the only way to assert multiple permissions at the same time within a frame because only one can be active on a frame. is only effective for granted permissions. Call the or method to cancel an active . > [!CAUTION] > Because calling the method removes the requirement that all code in the call chain must be granted permission to access the specified resource, it can open up security vulnerabilities if used incorrectly or inappropriately. Therefore, it should be used with great caution. @@ -551,7 +551,7 @@ ## Remarks Equality is determined by the permissions contained in the permission set specified by `obj`. `obj` can be either a object or a object. If `obj` is a , the name and description are ignored. - For more information, see . + For more information, see . ]]> diff --git a/xml/System.Security/ReadOnlyPermissionSet.xml b/xml/System.Security/ReadOnlyPermissionSet.xml index 93a255ea0bac3..e3a223e8e8a3d 100644 --- a/xml/System.Security/ReadOnlyPermissionSet.xml +++ b/xml/System.Security/ReadOnlyPermissionSet.xml @@ -107,7 +107,7 @@ is intended to be called by the base class when it is deserializing the permission set. An exception is thrown if you attempt to call directly. You cannot modify a read-only permission set with a call. + This override of is intended to be called by the base class when it is deserializing the permission set. An exception is thrown if you attempt to call directly. You cannot modify a read-only permission set with a call. ]]> diff --git a/xml/System.Security/SecureString.xml b/xml/System.Security/SecureString.xml index c40b0bd312ad7..9752dfce2acbb 100644 --- a/xml/System.Security/SecureString.xml +++ b/xml/System.Security/SecureString.xml @@ -51,7 +51,7 @@ ## String versus SecureString - An instance of the class is both immutable and, when no longer needed, cannot be programmatically scheduled for garbage collection; that is, the instance is read-only after it is created, and it is not possible to predict when the instance will be deleted from computer memory. Because instances are immutable, operations that appear to modify an existing instance actually create a copy of it to manipulate. Consequently, if a object contains sensitive information such as a password, credit card number, or personal data, there is a risk the information could be revealed after it is used because your application cannot delete the data from computer memory. + An instance of the class is both immutable and, when no longer needed, cannot be programmatically scheduled for garbage collection; that is, the instance is read-only after it is created, and it is not possible to predict when the instance will be deleted from computer memory. Because instances are immutable, operations that appear to modify an existing instance actually create a copy of it to manipulate. Consequently, if a object contains sensitive information such as a password, credit card number, or personal data, there is a risk the information could be revealed after it is used because your application cannot delete the data from computer memory. A object is similar to a object in that it has a text value. However, the value of a object is pinned in memory, may use a protection mechanism, such as encryption, provided by the underlying operating system, can be modified until your application marks it as read-only, and can be deleted from computer memory either by your application calling the method or by the .NET Framework garbage collector. @@ -70,7 +70,7 @@ You can add a single character at a time to a object by calling its or method. > [!IMPORTANT] -> A object should never be constructed from a , because the sensitive data is already subject to the memory persistence consequences of the immutable class. The best way to construct a object is from a character-at-a-time unmanaged source, such as the method. +> A object should never be constructed from a , because the sensitive data is already subject to the memory persistence consequences of the immutable class. The best way to construct a object is from a character-at-a-time unmanaged source, such as the method. Remove characters from a object You can replace an individual character by calling the method, remove an individual character by calling the method, or remove all characters from the instance by calling the method. @@ -84,15 +84,15 @@ Release the memory allocated to the instance Because implements the interface, you release its memory by calling the method. - The class has no members that inspect, compare, or convert the value of a . The absence of such members helps protect the value of the instance from accidental or malicious exposure. Use appropriate members of the class, such as the method, to manipulate the value of a object. + The class has no members that inspect, compare, or convert the value of a . The absence of such members helps protect the value of the instance from accidental or malicious exposure. Use appropriate members of the class, such as the method, to manipulate the value of a object. The .NET Framework Class Library commonly uses instances in the following ways: -- To provide password information to a process by using the structure or by calling an overload of the method that has a parameter of type . +- To provide password information to a process by using the structure or by calling an overload of the method that has a parameter of type . -- To provide network password information by calling a class constructor that has a parameter of type or by using the property. +- To provide network password information by calling a class constructor that has a parameter of type or by using the property. -- To provide password information for SQL Server Authentication by calling the constructor or retrieving the value of the property. +- To provide password information for SQL Server Authentication by calling the constructor or retrieving the value of the property. - To pass a string to unmanaged code. For more information, see the [SecureString and interop](#interop) section. @@ -102,21 +102,21 @@ ## SecureString and interop Because the operating system does not directly support , you must convert the value of the object to the required string type before passing the string to a native method. The class has five methods that do this: -- , which converts the string value to a binary string (BSTR) recognized by COM. +- , which converts the string value to a binary string (BSTR) recognized by COM. -- and , which copy the string value to an ANSI string in unmanaged memory. +- and , which copy the string value to an ANSI string in unmanaged memory. -- and , which copy the string value to a Unicode string in unmanaged memory. +- and , which copy the string value to a Unicode string in unmanaged memory. Each of these methods creates a clear-text string in unmanaged memory. It is the responsibility of the developer to zero out and free that memory as soon as it is no longer needed. Each of the string conversion and memory allocation methods has a corresponding method to zero out and free the allocated memory: |Allocation and conversion method|Zero and free method| |--------------------------------------|--------------------------| -||| -||| -||| -||| -||| +||| +||| +||| +||| +||| [Back to top](#top) diff --git a/xml/System.Security/SecurityContext.xml b/xml/System.Security/SecurityContext.xml index 6b733cfa1eaa8..2f69e454bbb21 100644 --- a/xml/System.Security/SecurityContext.xml +++ b/xml/System.Security/SecurityContext.xml @@ -225,7 +225,7 @@ method is called by the method to reverse the effect of a prior method call. + The method is called by the method to reverse the effect of a prior method call. ]]> @@ -319,7 +319,7 @@ Use the method on the returned structure to return the object to its previous state. - This method is protected with a for permission. A fully trusted component can call this method to suppress the flow of the information during asynchronous calls. When the flow is suppressed, the method returns `null`. + This method is protected with a for permission. A fully trusted component can call this method to suppress the flow of the information during asynchronous calls. When the flow is suppressed, the method returns `null`. ]]> diff --git a/xml/System.Security/SecurityCriticalAttribute.xml b/xml/System.Security/SecurityCriticalAttribute.xml index 85162c11087e0..a1cc4f8b18ae4 100644 --- a/xml/System.Security/SecurityCriticalAttribute.xml +++ b/xml/System.Security/SecurityCriticalAttribute.xml @@ -39,7 +39,7 @@ > [!NOTE] > The is equivalent to a link demand for full trust. A type or member marked with the can be called only by fully trusted code; it does not have to demand specific permissions. It cannot be called by partially trusted code. - Applying the at the assembly level identifies the assembly as a security-critical assembly. The entire assembly can be identified as critical by setting the scope parameter . + Applying the at the assembly level identifies the assembly as a security-critical assembly. The entire assembly can be identified as critical by setting the scope parameter . ]]> diff --git a/xml/System.Security/SecurityException.xml b/xml/System.Security/SecurityException.xml index f0bd3f44c772d..b1a61ad03aeba 100644 --- a/xml/System.Security/SecurityException.xml +++ b/xml/System.Security/SecurityException.xml @@ -35,7 +35,7 @@ exception is thrown when a caller does not have the permissions required to access a resource. The following example instantiates a object that includes a object to allow access to UI objects and the Clipboard and a object to prevent registry access. The call to the method means that these permissions will apply regardless of the permissions assigned to the caller. As a result, the attempt to create a registry key throws a . + A exception is thrown when a caller does not have the permissions required to access a resource. The following example instantiates a object that includes a object to allow access to UI objects and the Clipboard and a object to prevent registry access. The call to the method means that these permissions will apply regardless of the permissions assigned to the caller. As a result, the attempt to create a registry key throws a . [!code-csharp[System.SecurityException.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.securityexception.class/cs/se_ex1.cs#1)] [!code-vb[System.SecurityException.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.securityexception.class/vb/se_ex1.vb#1)] @@ -919,7 +919,7 @@ property represents the permitted permission, permission set, or permission set collection contained in the stack frame that caused the security exception. For instance, when a security exception occurs because of a failure, the permitted permission appears in this property and the demanded is contained in the property. + The property represents the permitted permission, permission set, or permission set collection contained in the stack frame that caused the security exception. For instance, when a security exception occurs because of a failure, the permitted permission appears in this property and the demanded is contained in the property. This property is of type because permissions, permission sets, or permission set collections can all be demanded and is their common base class. To test the run-time type of this property, you can use the method or a specific language operator, such as the operator in C# or the operator in Visual Basic. diff --git a/xml/System.Security/SecurityManager.xml b/xml/System.Security/SecurityManager.xml index b6c361cf6315e..19869e56426b3 100644 --- a/xml/System.Security/SecurityManager.xml +++ b/xml/System.Security/SecurityManager.xml @@ -142,7 +142,7 @@ ## Remarks > [!NOTE] -> In the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], the host evidence in `evidence` must contain evidence. +> In the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], the host evidence in `evidence` must contain evidence. > > The following table shows the permission sets that are returned for each zone. diff --git a/xml/System.Security/SecurityState.xml b/xml/System.Security/SecurityState.xml index e60237e5122fb..7b945cffc02fd 100644 --- a/xml/System.Security/SecurityState.xml +++ b/xml/System.Security/SecurityState.xml @@ -21,7 +21,7 @@ object that is instantiated from the derived class is passed to the method to determine whether the host allows that action to be performed. The default implementation of the method always returns `false`. The method must be overridden to detect the actions that are allowed. + You must inherit from this class to provide a class that includes a property that specifies the security-sensitive action to be performed. The object that is instantiated from the derived class is passed to the method to determine whether the host allows that action to be performed. The default implementation of the method always returns `false`. The method must be overridden to detect the actions that are allowed. For example, if you want to access a Web camera in your library code, you would create a `WebcamSecurityState` object and call the method to determine whether the host allows Web camera access, as shown in the following example. (You can find the code for `WebcamSecurityState` in the "Example" section.) @@ -39,7 +39,7 @@ catch (ApplicationException e) } ``` - To process the call the must be made aware of `WebcamSecurityState` through an override of the method, as shown in the following example. + To process the call the must be made aware of `WebcamSecurityState` through an override of the method, as shown in the following example. ``` [SecurityCritical] @@ -192,7 +192,7 @@ public override void EnsureState() calls the method to determine whether the state that is represented by this class is available on the host. + calls the method to determine whether the state that is represented by this class is available on the host. See the class for an example implementation of the method. diff --git a/xml/System.ServiceModel.Channels/ContextMessageProperty.xml b/xml/System.ServiceModel.Channels/ContextMessageProperty.xml index be8773e8ca417..d540455790bcf 100644 --- a/xml/System.ServiceModel.Channels/ContextMessageProperty.xml +++ b/xml/System.ServiceModel.Channels/ContextMessageProperty.xml @@ -92,7 +92,7 @@ method overwrites the value of the `ContextMessageProperty` property if a value is already set. + The method overwrites the value of the `ContextMessageProperty` property if a value is already set. ]]> diff --git a/xml/System.ServiceModel.Channels/LocalClientSecuritySettings.xml b/xml/System.ServiceModel.Channels/LocalClientSecuritySettings.xml index 2eb64e1bdd79b..917b2cc127e17 100644 --- a/xml/System.ServiceModel.Channels/LocalClientSecuritySettings.xml +++ b/xml/System.ServiceModel.Channels/LocalClientSecuritySettings.xml @@ -427,7 +427,7 @@ - If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is enabled. -- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. +- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. Session settings such as this one are not applicable under any of the following conditions: @@ -477,7 +477,7 @@ - If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is enabled. -- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. +- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. Session settings such as this one are not applicable under any of the following conditions: diff --git a/xml/System.ServiceModel.Channels/LocalServiceSecuritySettings.xml b/xml/System.ServiceModel.Channels/LocalServiceSecuritySettings.xml index ed3380b6b6c5e..35bf5110435e8 100644 --- a/xml/System.ServiceModel.Channels/LocalServiceSecuritySettings.xml +++ b/xml/System.ServiceModel.Channels/LocalServiceSecuritySettings.xml @@ -140,7 +140,7 @@ - If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is enabled. -- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. +- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. Session settings such as this one are not applicable under any of the following conditions: @@ -509,7 +509,7 @@ - If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is enabled. -- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. +- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. Session settings such as this one are not applicable under any of the following conditions: @@ -559,7 +559,7 @@ - If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is enabled. -- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. +- If [\ element](http://msdn.microsoft.com/en-us/9c93818a-7dfa-43d5-b3a1-1aafccf3a00b) is not enabled, on with = `true` or = `true`. Session settings such as this one are not applicable under any of the following conditions: diff --git a/xml/System.ServiceModel.Channels/MessageEncoderFactory.xml b/xml/System.ServiceModel.Channels/MessageEncoderFactory.xml index 80d8c087dc579..24ec525edef1a 100644 --- a/xml/System.ServiceModel.Channels/MessageEncoderFactory.xml +++ b/xml/System.ServiceModel.Channels/MessageEncoderFactory.xml @@ -132,7 +132,7 @@ property. is limited to using certain versions of SOAP and WS-Addressing and is not extensible. So if these versions are not to be used, this property should be overridden to return . + The message version can be set using the property. is limited to using certain versions of SOAP and WS-Addressing and is not extensible. So if these versions are not to be used, this property should be overridden to return . diff --git a/xml/System.ServiceModel.Channels/ReliableSessionBindingElementImporter.xml b/xml/System.ServiceModel.Channels/ReliableSessionBindingElementImporter.xml index f940c37cd86f3..f5482d9648bd6 100644 --- a/xml/System.ServiceModel.Channels/ReliableSessionBindingElementImporter.xml +++ b/xml/System.ServiceModel.Channels/ReliableSessionBindingElementImporter.xml @@ -26,7 +26,7 @@ - Implement the interface to search WSDL information exposed by a particular endpoint for custom policy assertions about endpoint capabilities or requirements. -- Implement the interface on a object to write statements about endpoint capabilities or requirements into the WSDL information exposed by a particular endpoint. +- Implement the interface on a object to write statements about endpoint capabilities or requirements into the WSDL information exposed by a particular endpoint. ]]> diff --git a/xml/System.ServiceModel.Description/CallbackDebugBehavior.xml b/xml/System.ServiceModel.Description/CallbackDebugBehavior.xml index 6ae472d3fc143..6df67943c6bcd 100644 --- a/xml/System.ServiceModel.Description/CallbackDebugBehavior.xml +++ b/xml/System.ServiceModel.Description/CallbackDebugBehavior.xml @@ -172,7 +172,7 @@ property to the property. + Assigns the value of the property to the property. ]]> @@ -202,7 +202,7 @@ ; this behavior can only be used in a client application. + Throws an ; this behavior can only be used in a client application. ]]> diff --git a/xml/System.ServiceModel.Description/DurableServiceAttribute.xml b/xml/System.ServiceModel.Description/DurableServiceAttribute.xml index 9bb48f8312227..8f880b6bf368e 100644 --- a/xml/System.ServiceModel.Description/DurableServiceAttribute.xml +++ b/xml/System.ServiceModel.Description/DurableServiceAttribute.xml @@ -42,7 +42,7 @@ - If the contract permits or allows sessions then all operations for which is set to `true` must be request/response operations, that is cannot be set to `true`. -- If is set to `true`, then all operations on the service must either be marked with set to `true` or marked with . Additionally, must be set to Single. +- If is set to `true`, then all operations on the service must either be marked with set to `true` or marked with . Additionally, must be set to Single. ]]> @@ -133,7 +133,7 @@ is set to `true`, then all operations on the service must either be marked with set to `true` or marked with . Additionally, must be set to Single. + If is set to `true`, then all operations on the service must either be marked with set to `true` or marked with . Additionally, must be set to Single. Setting to `true` makes the service state transactional with the operation transaction. This means that if the operation's transaction rolls back, the service state also rolls back. diff --git a/xml/System.ServiceModel.Description/FaultDescription.xml b/xml/System.ServiceModel.Description/FaultDescription.xml index 6080bf034127e..5970880aa0503 100644 --- a/xml/System.ServiceModel.Description/FaultDescription.xml +++ b/xml/System.ServiceModel.Description/FaultDescription.xml @@ -100,7 +100,7 @@ . + The detail type must be serializable. For details, see . ]]> diff --git a/xml/System.ServiceModel.Description/IContractBehavior.xml b/xml/System.ServiceModel.Description/IContractBehavior.xml index 05310bf2bd0c0..04fc2e82d498a 100644 --- a/xml/System.ServiceModel.Description/IContractBehavior.xml +++ b/xml/System.ServiceModel.Description/IContractBehavior.xml @@ -29,11 +29,11 @@ objects can make use of any of these methods, but often only one is important; in such cases, the unused methods can return without any value. > [!NOTE] -> All of the methods pass and as parameters. These parameters are for examination; if you modify the objects the execution behavior is undefined. +> All of the methods pass and as parameters. These parameters are for examination; if you modify the objects the execution behavior is undefined. - types can be used on either the service or the client, or both. To perform a customization task on the service, the object must be added to the property prior to the construction of the service runtime, which occurs when the method is called on the object. There are two ways to do this. + types can be used on either the service or the client, or both. To perform a customization task on the service, the object must be added to the property prior to the construction of the service runtime, which occurs when the method is called on the object. There are two ways to do this. - The first method is to programmatically add the custom contract behavior to the property prior to the point when the method is called on the object. When applied this way, the behavior is applied for all messages flowing through that contract on any endpoint. + The first method is to programmatically add the custom contract behavior to the property prior to the point when the method is called on the object. When applied this way, the behavior is applied for all messages flowing through that contract on any endpoint. > [!NOTE] > The behavior is applied to all contracts of the same type. For example, if you programmatically add the same contract type to more than one endpoint, the behavior modifies all endpoints that refer to the same contract object. @@ -46,17 +46,17 @@ - A callback class. In this case, the behavior is applied to the duplex client's endpoint. - The behavior of the second approach varies slightly if the custom attribute also implements . In this case, the behavior is as follows: + The behavior of the second approach varies slightly if the custom attribute also implements . In this case, the behavior is as follows: -- A contract interface. In this case, the behavior is applied to all contracts of that type in any endpoint and [!INCLUDE[indigo1](~/includes/indigo1-md.md)] ignores the value of the property. +- A contract interface. In this case, the behavior is applied to all contracts of that type in any endpoint and [!INCLUDE[indigo1](~/includes/indigo1-md.md)] ignores the value of the property. -- A service class. In this case, the behavior is applied only to endpoints the contract of which is the value of the property. +- A service class. In this case, the behavior is applied only to endpoints the contract of which is the value of the property. -- A callback class. In this case, the behavior is applied to the duplex client's endpoint and [!INCLUDE[indigo2](~/includes/indigo2-md.md)] ignores the value of the property. +- A callback class. In this case, the behavior is applied to the duplex client's endpoint and [!INCLUDE[indigo2](~/includes/indigo2-md.md)] ignores the value of the property. - To perform the customization task on the client for which it is intended, the object must be added to the property prior to the construction of the client runtime, which occurs when is called. There are two ways to do this: + To perform the customization task on the client for which it is intended, the object must be added to the property prior to the construction of the client runtime, which occurs when is called. There are two ways to do this: -- Programmatically add the custom contract behavior to the property prior to the point when the is called. +- Programmatically add the custom contract behavior to the property prior to the point when the is called. - Create a custom attribute that also implements . diff --git a/xml/System.ServiceModel.Description/IContractBehaviorAttribute.xml b/xml/System.ServiceModel.Description/IContractBehaviorAttribute.xml index 6da9e732b3088..377333b7f52b9 100644 --- a/xml/System.ServiceModel.Description/IContractBehaviorAttribute.xml +++ b/xml/System.ServiceModel.Description/IContractBehaviorAttribute.xml @@ -13,18 +13,18 @@ interface on an attribute that is also an object to enable the use of that contract behavior attribute on a service type but restrict its application to the contract specified in the property. + Implement the interface on an attribute that is also an object to enable the use of that contract behavior attribute on a service type but restrict its application to the contract specified in the property. There is no requirement to implement on custom contract behavior attributes, and if the attribute is applied either to a contract interface or to a duplex callback class the value of the property is ignored. - For more information, see . + For more information, see . ## Examples - The following code example assumes a custom implementation called `ObjectProviderBehavior` that provides a "singleton" behavior; it always returns the same service instance and does not recycle it. + The following code example assumes a custom implementation called `ObjectProviderBehavior` that provides a "singleton" behavior; it always returns the same service instance and does not recycle it. - To insert the instance provider customization, the example shows how to implement a custom attribute (`SingletonBehaviorAttribute`) that implements to insert the custom service instance provider. It also implements , which binds its application to the `ISampleService` contract. + To insert the instance provider customization, the example shows how to implement a custom attribute (`SingletonBehaviorAttribute`) that implements to insert the custom service instance provider. It also implements , which binds its application to the `ISampleService` contract. [!code-csharp[IContractBehavior#2](~/samples/snippets/csharp/VS_Snippets_CFX/icontractbehavior/cs/objectproviderbehavior.cs#2)] [!code-vb[IContractBehavior#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/icontractbehavior/vb/objectproviderbehavior.vb#2)] @@ -52,14 +52,14 @@ property to specify the contract to which the contract behavior is applied when the implementing attribute is applied to a service class. + Implement the property to specify the contract to which the contract behavior is applied when the implementing attribute is applied to a service class. ## Examples - The following code example assumes a custom implementation called `ObjectProviderBehavior` that provides a "singleton" behavior; it always returns the same service instance and does not recycle it. + The following code example assumes a custom implementation called `ObjectProviderBehavior` that provides a "singleton" behavior; it always returns the same service instance and does not recycle it. - To insert the instance provider customization, the example shows how to implement a custom attribute (`SingletonBehaviorAttribute`) that implements to insert the custom service instance provider. It also implements , which binds its application to the `ISampleService` contract. + To insert the instance provider customization, the example shows how to implement a custom attribute (`SingletonBehaviorAttribute`) that implements to insert the custom service instance provider. It also implements , which binds its application to the `ISampleService` contract. [!code-csharp[IContractBehavior#2](~/samples/snippets/csharp/VS_Snippets_CFX/icontractbehavior/cs/objectproviderbehavior.cs#2)] [!code-vb[IContractBehavior#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/icontractbehavior/vb/objectproviderbehavior.vb#2)] diff --git a/xml/System.ServiceModel.Description/IEndpointBehavior.xml b/xml/System.ServiceModel.Description/IEndpointBehavior.xml index ad55f4707146d..cc49c0fc05eae 100644 --- a/xml/System.ServiceModel.Description/IEndpointBehavior.xml +++ b/xml/System.ServiceModel.Description/IEndpointBehavior.xml @@ -29,7 +29,7 @@ > [!NOTE] > All of the methods pass a object as a parameter. This parameter is for examination only; if you modify the object the execution behavior is undefined. - objects are typically used to access the various properties of the , , , and objects in a service application and the and in a client application. In addition, you can access the properties of duplex clients and services using the and properties, respectively. + objects are typically used to access the various properties of the , , , and objects in a service application and the and in a client application. In addition, you can access the properties of duplex clients and services using the and properties, respectively. For a description of the various properties and customizations available, see [Extending ServiceHost and the Service Model Layer](~/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md). @@ -41,22 +41,22 @@ - Configure the behavior using an application configuration file. For details, see [<behaviorExtensions>](~/docs/framework/configure-apps/file-schema/wcf/behaviorextensions.md). - To perform the service customization task for which it is intended, the object must be added to the property prior to the construction of the service runtime, which occurs when method is called on . To perform a client customization task, the object must be added to the property before calling the method or the method on . + To perform the service customization task for which it is intended, the object must be added to the property prior to the construction of the service runtime, which occurs when method is called on . To perform a client customization task, the object must be added to the property before calling the method or the method on . ## Examples - The following code example shows the implementation of an endpoint behavior that adds an object in a service application. In this case, the `EndpointBehaviorMessageInspector` class implements to inspect the inbound and outbound message, the interface to insert the inspector class into the inspection system for all endpoints to which the behavior applies, and the to enable the message inspector behavior using an application configuration file. + The following code example shows the implementation of an endpoint behavior that adds an object in a service application. In this case, the `EndpointBehaviorMessageInspector` class implements to inspect the inbound and outbound message, the interface to insert the inspector class into the inspection system for all endpoints to which the behavior applies, and the to enable the message inspector behavior using an application configuration file. The first step is to implement the message inspector. [!code-csharp[IEndpointBehavior#2](~/samples/snippets/csharp/VS_Snippets_CFX/iendpointbehavior/cs/iendpointbehaviormessageinspector.cs#2)] - The next code example shows the use of the method to add the message inspector to the property. + The next code example shows the use of the method to add the message inspector to the property. [!code-csharp[IEndpointBehavior#4](~/samples/snippets/csharp/VS_Snippets_CFX/iendpointbehavior/cs/iendpointbehaviormessageinspector.cs#4)] - The following code example shows the implementation of in order to enable use of the message inspector behavior from a configuration file. + The following code example shows the implementation of in order to enable use of the message inspector behavior from a configuration file. [!code-csharp[IEndpointBehavior#3](~/samples/snippets/csharp/VS_Snippets_CFX/iendpointbehavior/cs/iendpointbehaviormessageinspector.cs#3)] @@ -159,28 +159,28 @@ method to view, modify, or extend the service runtime across all messages or for specific operations in an endpoint. For details about what customizations you can do in a service application, see and . + Implement the method to view, modify, or extend the service runtime across all messages or for specific operations in an endpoint. For details about what customizations you can do in a service application, see and . It is recommended that the method throw a exception if the behavior is only intended for use in a client application. - Note that there can be two operations with the same name in the description when using a callback contract (one operation in each direction). If you are iterating through operations, you must correlate the message direction between the endpoint and what is returned by the property. + Note that there can be two operations with the same name in the description when using a callback contract (one operation in each direction). If you are iterating through operations, you must correlate the message direction between the endpoint and what is returned by the property. - In addition, because other behaviors may have already added or removed some operations from the runtime, there is no guarantee that there are the same number of operations in description as there are objects in the property. + In addition, because other behaviors may have already added or removed some operations from the runtime, there is no guarantee that there are the same number of operations in description as there are objects in the property. ## Examples - The following code example shows the implementation of an endpoint behavior that adds an object in a service application. In this case, the `EndpointBehaviorMessageInspector` class implements to inspect the inbound and outbound message, the interface to insert the inspector class into the inspection system for all endpoints to which the behavior applies, and the to enable the message inspector behavior using an application configuration file. + The following code example shows the implementation of an endpoint behavior that adds an object in a service application. In this case, the `EndpointBehaviorMessageInspector` class implements to inspect the inbound and outbound message, the interface to insert the inspector class into the inspection system for all endpoints to which the behavior applies, and the to enable the message inspector behavior using an application configuration file. The first step is to implement the message inspector. [!code-csharp[IEndpointBehavior#2](~/samples/snippets/csharp/VS_Snippets_CFX/iendpointbehavior/cs/iendpointbehaviormessageinspector.cs#2)] - The next code example shows the use of the method to add the message inspector to the property. + The next code example shows the use of the method to add the message inspector to the property. [!code-csharp[IEndpointBehavior#4](~/samples/snippets/csharp/VS_Snippets_CFX/iendpointbehavior/cs/iendpointbehaviormessageinspector.cs#4)] - The following code example shows the implementation of in order to enable use of the message inspector behavior from a configuration file. + The following code example shows the implementation of in order to enable use of the message inspector behavior from a configuration file. [!code-csharp[IEndpointBehavior#3](~/samples/snippets/csharp/VS_Snippets_CFX/iendpointbehavior/cs/iendpointbehaviormessageinspector.cs#3)] diff --git a/xml/System.ServiceModel.Description/IOperationBehavior.xml b/xml/System.ServiceModel.Description/IOperationBehavior.xml index 5ef27375997c5..2af9ed6443992 100644 --- a/xml/System.ServiceModel.Description/IOperationBehavior.xml +++ b/xml/System.ServiceModel.Description/IOperationBehavior.xml @@ -29,26 +29,26 @@ > [!NOTE] > All of the methods pass an object as a parameter. This parameter is for examination only; if you modify the object the execution behavior is undefined. - objects are typically used to access the various properties of the object in a service application and the object in a client application. + objects are typically used to access the various properties of the object in a service application and the object in a client application. - Typically, the developer first reviews the extensibility points to determine which customization option suits the application scenario and then implements the customization at the appropriate scope. For example, objects can insert customizations for all messages in an entire service and objects can insert customizations for all messages across a specific contract, and so on. For a description of the various properties and customizations available, see [Extending ServiceHost and the Service Model Layer](~/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md). + Typically, the developer first reviews the extensibility points to determine which customization option suits the application scenario and then implements the customization at the appropriate scope. For example, objects can insert customizations for all messages in an entire service and objects can insert customizations for all messages across a specific contract, and so on. For a description of the various properties and customizations available, see [Extending ServiceHost and the Service Model Layer](~/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md). Once a customization has been decided upon (and the customization interface implemented if necessary) and the is the appropriate scope of customization, the customization must be inserted into the [!INCLUDE[indigo1](~/includes/indigo1-md.md)] runtime by implementing and adding the operation behavior to the runtime. There are two ways to add the to the runtime: -- Programmatically add the custom operation behavior to the property prior to the opening of the service host (in a service application) or the channel factory (in a client application). +- Programmatically add the custom operation behavior to the property prior to the opening of the service host (in a service application) or the channel factory (in a client application). - Add the behavior using a custom attribute. - To perform the service customization task for which it is intended, the object must be added to the property prior to the construction of the service runtime, which occurs when method is called on . To perform a client customization task, the object must be added to the property before calling the method or the method on . + To perform the service customization task for which it is intended, the object must be added to the property prior to the construction of the service runtime, which occurs when method is called on . To perform a client customization task, the object must be added to the property before calling the method or the method on . Although the operation behavior is designed for easy access to the runtime at the scope of an individual operation, you can access the runtime at a larger scope by accessing the parent runtime object. ## Examples - The following code example shows an implementation of that writes to the console when the inspector is invoked on an operation. This customization can only be attached to the or and is therefore usually inserted by an operation behavior. + The following code example shows an implementation of that writes to the console when the inspector is invoked on an operation. This customization can only be attached to the or and is therefore usually inserted by an operation behavior. [!code-csharp[Interceptors#4](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#4)] [!code-vb[Interceptors#4](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#4)] @@ -125,7 +125,7 @@ ## Examples - The following code example shows an implementation of that writes to the console when the inspector is invoked on an operation. This customization can only be attached to the or and is therefore usually inserted by an operation behavior. + The following code example shows an implementation of that writes to the console when the inspector is invoked on an operation. This customization can only be attached to the or and is therefore usually inserted by an operation behavior. [!code-csharp[Interceptors#4](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#4)] [!code-vb[Interceptors#4](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#4)] @@ -164,14 +164,14 @@ method to view, modify, or extend the service runtime across all messages or for a specific operation. For details about what customizations you can do in a service application, see and . + Implement the method to view, modify, or extend the service runtime across all messages or for a specific operation. For details about what customizations you can do in a service application, see and . It is recommended that the method throw a exception if the behavior is only intended for use in a client application. ## Examples - The following code example shows an implementation of that writes to the console when the inspector is invoked on an operation. This customization can only be attached to the or and is therefore usually inserted by an operation behavior. + The following code example shows an implementation of that writes to the console when the inspector is invoked on an operation. This customization can only be attached to the or and is therefore usually inserted by an operation behavior. [!code-csharp[Interceptors#4](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#4)] [!code-vb[Interceptors#4](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#4)] diff --git a/xml/System.ServiceModel.Description/IOperationContractGenerationExtension.xml b/xml/System.ServiceModel.Description/IOperationContractGenerationExtension.xml index 9048240aa90bc..bd7b401da7f4d 100644 --- a/xml/System.ServiceModel.Description/IOperationContractGenerationExtension.xml +++ b/xml/System.ServiceModel.Description/IOperationContractGenerationExtension.xml @@ -13,16 +13,16 @@ interface on an operation behavior (a type) to enable you to modify the code generated when a contract or endpoint is compiled into code. Typically, a custom inserts a custom operation behavior into the collection during the call to or . + Implement the interface on an operation behavior (a type) to enable you to modify the code generated when a contract or endpoint is compiled into code. Typically, a custom inserts a custom operation behavior into the collection during the call to or . ## Examples - The following code example shows the implementation of the method that adds a string to the comments section of the operation using the namespace. + The following code example shows the implementation of the method that adds a string to the comments section of the operation using the namespace. - The following code example shows how the operation behavior that implements is inserted into the collection during the call to . + The following code example shows how the operation behavior that implements is inserted into the collection during the call to . [!code-csharp[C_CustomWSDLExtensions#4](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#4)] @@ -57,18 +57,18 @@ inserts a custom operation behavior into the collection during the call to or . + Typically, a custom inserts a custom operation behavior into the collection during the call to or . The method is called once for each contract. ## Examples - The following code example shows the implementation of the method that adds a string to the comments section of the operation using the namespace. + The following code example shows the implementation of the method that adds a string to the comments section of the operation using the namespace. - The following code example shows how the operation behavior that implements is inserted into the collection during the call to . + The following code example shows how the operation behavior that implements is inserted into the collection during the call to . [!code-csharp[C_CustomWSDLExtensions#4](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#4)] diff --git a/xml/System.ServiceModel.Description/IPolicyExportExtension.xml b/xml/System.ServiceModel.Description/IPolicyExportExtension.xml index 9877e3f63bf69..817015f8aa30b 100644 --- a/xml/System.ServiceModel.Description/IPolicyExportExtension.xml +++ b/xml/System.ServiceModel.Description/IPolicyExportExtension.xml @@ -14,7 +14,7 @@ interface on a object to write statements about endpoint capabilities or requirements into the WSDL information exposed by a particular endpoint. Typically the binding element is one that implements some feature, but this is not required. To load your policy exporter from a configuration file, implement a that returns the policy exporter object. + Implement the interface on a object to write statements about endpoint capabilities or requirements into the WSDL information exposed by a particular endpoint. Typically the binding element is one that implements some feature, but this is not required. To load your policy exporter from a configuration file, implement a that returns the policy exporter object. The policy exporter is used by [!INCLUDE[indigo1](~/includes/indigo1-md.md)] to use policy assertions to communicate to clients the existence of that custom binding requirement or endpoint capability. @@ -34,7 +34,7 @@ [!code-csharp[CustomPolicySample#14](~/samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyexporter.cs#14)] [!code-vb[CustomPolicySample#14](~/samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyexporter.vb#14)] - The following code example shows a implementation that enables the preceding policy exporter to be loaded from an application configuration file. + The following code example shows a implementation that enables the preceding policy exporter to be loaded from an application configuration file. [!code-csharp[CustomPolicySample#15](~/samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyexporter.cs#15)] [!code-vb[CustomPolicySample#15](~/samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyexporter.vb#15)] @@ -85,7 +85,7 @@ [!code-csharp[CustomPolicySample#14](~/samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyexporter.cs#14)] [!code-vb[CustomPolicySample#14](~/samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyexporter.vb#14)] - The following code example shows a implementation that enables the preceding policy exporter to be loaded from an application configuration file. + The following code example shows a implementation that enables the preceding policy exporter to be loaded from an application configuration file. [!code-csharp[CustomPolicySample#15](~/samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyexporter.cs#15)] [!code-vb[CustomPolicySample#15](~/samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyexporter.vb#15)] diff --git a/xml/System.ServiceModel.Description/IPolicyImportExtension.xml b/xml/System.ServiceModel.Description/IPolicyImportExtension.xml index d29d37e136a5f..d36bc6b027796 100644 --- a/xml/System.ServiceModel.Description/IPolicyImportExtension.xml +++ b/xml/System.ServiceModel.Description/IPolicyImportExtension.xml @@ -16,7 +16,7 @@ ## Remarks Implement the interface to search WSDL information exposed by a particular endpoint for custom policy assertions about endpoint capabilities or requirements. Typically, a policy importer searches for a specific assertion and either inserts a binding element, configures a binding element, or modifies the contract to support the requirements of the assertion. - Unlike its counterpart, , does not require implementation by a object; you can load it using the client configuration section shown in the Examples section or programmatically by adding it to the constructor. + Unlike its counterpart, , does not require implementation by a object; you can load it using the client configuration section shown in the Examples section or programmatically by adding it to the constructor. [!INCLUDE[indigo1](~/includes/indigo1-md.md)] passes two objects to the method, a and a . Typically the object already contains the policy assertions for each binding scope. @@ -24,9 +24,9 @@ 1. Locates the custom policy assertion for which it is responsible by calling either the , , or methods, depending upon the scope. -2. Removes the policy assertion from the assertion collection. The method locates, returns, and removes the assertion in one step. +2. Removes the policy assertion from the assertion collection. The method locates, returns, and removes the assertion in one step. -3. Modify the binding stack or the contract by either adding a required custom to the property or by modifying the property. +3. Modify the binding stack or the contract by either adding a required custom to the property or by modifying the property. Step 2 is important. After all policy importers have been called, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] checks for the existence of any policy assertions that remain. If one exists, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] assumes that the policy import was unsuccessful and does not import the associated binding. @@ -35,7 +35,7 @@ Custom implementations must implement their own object to extract the policy assertions attached to the custom metadata format. - If you want to export and import custom WSDL elements that are not policy assertions, see and . + If you want to export and import custom WSDL elements that are not policy assertions, see and . > [!NOTE] > You can use custom policy importers and exporters with the [ServiceModel Metadata Utility Tool (Svcutil.exe)](~/docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) by using the same configuration elements in a configuration file and the `/svcutilConfig:` option. @@ -43,12 +43,12 @@ ## Examples - The following code example shows the use of the method to locate, return, and remove the assertion in one step. + The following code example shows the use of the method to locate, return, and remove the assertion in one step. [!code-csharp[CustomPolicySample#1](~/samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyimporter.cs#1)] [!code-vb[CustomPolicySample#1](~/samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyimporter.vb#1)] - The following code example shows the client application configuration file to load the custom policy importer when the is invoked. + The following code example shows the client application configuration file to load the custom policy importer when the is invoked. [!code-xml[CustomPolicySample#7](~/samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/client.exe.config#7)] @@ -93,21 +93,21 @@ 1. Locates the custom policy assertion for which it is responsible by calling either the , , or methods, depending upon the scope. -2. Removes the policy assertion from the assertion collection. The method locates, returns, and removes the assertion in one step. +2. Removes the policy assertion from the assertion collection. The method locates, returns, and removes the assertion in one step. -3. Modifies the binding stack or the contract by either adding a required custom to the property or by modifying the property. +3. Modifies the binding stack or the contract by either adding a required custom to the property or by modifying the property. Step 2 is important. After all policy importers have been called, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] checks for the existence of any policy assertions that remain. If one exists, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] assumes that the policy import was unsuccessful and does not import the associated binding. ## Examples - The following code example shows the use of the method to locate, return, and remove the assertion in one step. + The following code example shows the use of the method to locate, return, and remove the assertion in one step. [!code-csharp[CustomPolicySample#1](~/samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/policyimporter.cs#1)] [!code-vb[CustomPolicySample#1](~/samples/snippets/visualbasic/VS_Snippets_CFX/custompolicysample/vb/policyimporter.vb#1)] - The following code example shows the client application configuration file to load the custom policy importer when the is invoked. + The following code example shows the client application configuration file to load the custom policy importer when the is invoked. [!code-xml[CustomPolicySample#7](~/samples/snippets/csharp/VS_Snippets_CFX/custompolicysample/cs/client.exe.config#7)] diff --git a/xml/System.ServiceModel.Description/IServiceBehavior.xml b/xml/System.ServiceModel.Description/IServiceBehavior.xml index cb23c0730d8ee..a77048fc18530 100644 --- a/xml/System.ServiceModel.Description/IServiceBehavior.xml +++ b/xml/System.ServiceModel.Description/IServiceBehavior.xml @@ -24,29 +24,29 @@ objects can make use of any of these methods, but often only one is important; in such cases the unused methods can return without a value. > [!NOTE] -> All of the methods pass and objects as a parameters. The parameter is for examination only; if you modify these objects the execution behavior is undefined. +> All of the methods pass and objects as a parameters. The parameter is for examination only; if you modify these objects the execution behavior is undefined. To perform the customization task for which it is intended, the object must be added to the property prior to the construction of the service runtime. There are three ways to do this: -- Programmatically add the custom service behavior to the property prior to the point where the method is called on the object. +- Programmatically add the custom service behavior to the property prior to the point where the method is called on the object. - Create a custom attribute that implements and use it to mark service classes that are to be modified. When a object is constructed, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] uses reflection to discover the attributes on the service type. If any attributes implement , they are added to the behaviors collection on . -- Extend the class to support the specification of the behavior in an application or machine configuration file. See the Example section for more information. +- Extend the class to support the specification of the behavior in an application or machine configuration file. See the Example section for more information. - Examples of service behaviors in [!INCLUDE[indigo2](~/includes/indigo2-md.md)] include the attribute, the , the and the behavior. + Examples of service behaviors in [!INCLUDE[indigo2](~/includes/indigo2-md.md)] include the attribute, the , the and the behavior. ## Examples The following code example shows the use of a service behavior specified in a configuration file to insert a custom error handler in a service application. In this example, the error handler catches all exceptions and converts them into a custom `GreetingFault` SOAP fault that is then returned to the client. - The following implementation adds no binding parameter objects, adds the custom object to each property, and validates that each operation of the service to which the service behavior is applied and has a of type `GreetingFault`. + The following implementation adds no binding parameter objects, adds the custom object to each property, and validates that each operation of the service to which the service behavior is applied and has a of type `GreetingFault`. [!code-csharp[IErrorHandler#7](~/samples/snippets/csharp/VS_Snippets_CFX/ierrorhandler/cs/ierrorhandler.cs#7)] [!code-vb[IErrorHandler#7](~/samples/snippets/visualbasic/VS_Snippets_CFX/ierrorhandler/vb/ierrorhandler.vb#7)] - In this example, the behavior class also implements , which enables the service behavior to be inserted by using it in an application configuration file, as the following code example demonstrates. + In this example, the behavior class also implements , which enables the service behavior to be inserted by using it in an application configuration file, as the following code example demonstrates. [!code-xml[IErrorHandler#4](~/samples/snippets/csharp/VS_Snippets_CFX/ierrorhandler/cs/hostapplication.exe.config#4)] @@ -84,10 +84,10 @@ ## Remarks Use the method to add custom data objects to the `parameters` collection that binding elements can use to acquire extra information to enable them to support the contract. - This method is called once for each listen URI. For example, if a service has four endpoints, and two of them have the same listen URI, then this method gets called three times. The reason is that the `bindingParameters` target each channel stack and there is one channel stack for each listen URI. Because each call receives those endpoints at that listen URI, two calls each get a single , and one call gets a collection of two objects. + This method is called once for each listen URI. For example, if a service has four endpoints, and two of them have the same listen URI, then this method gets called three times. The reason is that the `bindingParameters` target each channel stack and there is one channel stack for each listen URI. Because each call receives those endpoints at that listen URI, two calls each get a single , and one call gets a collection of two objects. > [!NOTE] -> All of the methods pass and objects as a parameters. The parameter is for examination and insertion of customizations only; if you otherwise modify these objects the execution behavior is undefined. +> All of the methods pass and objects as a parameters. The parameter is for examination and insertion of customizations only; if you otherwise modify these objects the execution behavior is undefined. ]]> @@ -120,19 +120,19 @@ Implement the method to inspect or modify the object that is being constructed in order to support some custom execution scenario. > [!NOTE] -> All of the methods pass and objects as a parameters. The parameter is for examination and insertion of customizations only; if you otherwise modify these objects the execution behavior is undefined. +> All of the methods pass and objects as a parameters. The parameter is for examination and insertion of customizations only; if you otherwise modify these objects the execution behavior is undefined. ## Examples The following code example shows the use of a service behavior specified in a configuration file to insert a custom error handler in a service application. In this example, the error handler catches all exceptions and converts them into a custom `GreetingFault` SOAP fault that is then returned to the client. - The following implementation adds no binding parameter objects, adds the custom object to each property, and validates that each operation of the service to which the service behavior is applied and has a of type `GreetingFault`. + The following implementation adds no binding parameter objects, adds the custom object to each property, and validates that each operation of the service to which the service behavior is applied and has a of type `GreetingFault`. [!code-csharp[IErrorHandler#7](~/samples/snippets/csharp/VS_Snippets_CFX/ierrorhandler/cs/ierrorhandler.cs#7)] [!code-vb[IErrorHandler#7](~/samples/snippets/visualbasic/VS_Snippets_CFX/ierrorhandler/vb/ierrorhandler.vb#7)] - In this example, the behavior class also implements , which enables the service behavior to be inserted by using it in an application configuration file, as the following code example demonstrates. + In this example, the behavior class also implements , which enables the service behavior to be inserted by using it in an application configuration file, as the following code example demonstrates. [!code-xml[IErrorHandler#4](~/samples/snippets/csharp/VS_Snippets_CFX/ierrorhandler/cs/hostapplication.exe.config#4)] @@ -167,19 +167,19 @@ Use the method to confirm whether the current service can execute properly according to your scenario. > [!NOTE] -> All of the methods pass and objects as a parameters. The parameter is for examination and insertion of customizations only; if you otherwise modify these objects the execution behavior is undefined. +> All of the methods pass and objects as a parameters. The parameter is for examination and insertion of customizations only; if you otherwise modify these objects the execution behavior is undefined. ## Examples The following code example shows the use of a service behavior specified in a configuration file to insert a custom error handler in a service application. In this example, the error handler catches all exceptions and converts them into a custom `GreetingFault` SOAP fault that is then returned to the client. - The following implementation adds no binding parameter objects, adds the custom object to each property, and validates that each operation of the service to which the service behavior is applied and has a of type `GreetingFault`. + The following implementation adds no binding parameter objects, adds the custom object to each property, and validates that each operation of the service to which the service behavior is applied and has a of type `GreetingFault`. [!code-csharp[IErrorHandler#7](~/samples/snippets/csharp/VS_Snippets_CFX/ierrorhandler/cs/ierrorhandler.cs#7)] [!code-vb[IErrorHandler#7](~/samples/snippets/visualbasic/VS_Snippets_CFX/ierrorhandler/vb/ierrorhandler.vb#7)] - In this example, the behavior class also implements , which enables the service behavior to be inserted by using it in an application configuration file, as the following code example demonstrates. + In this example, the behavior class also implements , which enables the service behavior to be inserted by using it in an application configuration file, as the following code example demonstrates. [!code-xml[IErrorHandler#4](~/samples/snippets/csharp/VS_Snippets_CFX/ierrorhandler/cs/hostapplication.exe.config#4)] diff --git a/xml/System.ServiceModel.Description/IServiceContractGenerationExtension.xml b/xml/System.ServiceModel.Description/IServiceContractGenerationExtension.xml index 66bc25682c295..e80034707271a 100644 --- a/xml/System.ServiceModel.Description/IServiceContractGenerationExtension.xml +++ b/xml/System.ServiceModel.Description/IServiceContractGenerationExtension.xml @@ -13,14 +13,14 @@ interface on a contract behavior (a type) to enable you to modify the code generated when a contract or endpoint is compiled into code. + Implement the interface on a contract behavior (a type) to enable you to modify the code generated when a contract or endpoint is compiled into code. - Typically, a custom inserts a custom contract behavior into the collection during the call to or . + Typically, a custom inserts a custom contract behavior into the collection during the call to or . ## Examples - The following code example shows how to add an to the property during the call to . + The following code example shows how to add an to the property during the call to . [!code-csharp[C_CustomWSDLExtensions#4](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#4)] @@ -59,12 +59,12 @@ to modify the contract, operations, or the prior to code generation. + Use the to modify the contract, operations, or the prior to code generation. ## Examples - The following code example shows how to add an to the property during the call to . + The following code example shows how to add an to the property during the call to . [!code-csharp[C_CustomWSDLExtensions#4](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#4)] diff --git a/xml/System.ServiceModel.Description/IWsdlExportExtension.xml b/xml/System.ServiceModel.Description/IWsdlExportExtension.xml index bef00c41b0620..9124031d9e338 100644 --- a/xml/System.ServiceModel.Description/IWsdlExportExtension.xml +++ b/xml/System.ServiceModel.Description/IWsdlExportExtension.xml @@ -21,9 +21,9 @@ does not export custom policy assertions even though [!INCLUDE[indigo1](~/includes/indigo1-md.md)] exports custom binding policy assertions to the appropriate element inside WSDL. If you want to export custom policy assertions, implement the interface. - The metadata publication process begins by calling which in turn calls for each endpoint. + The metadata publication process begins by calling which in turn calls for each endpoint. - The endpoint is exported by first exporting its contract.When exporting a contract the calls the method on all implementations on the contract, and operation behaviors for that contract. Operations that use wildcard actions are not exported in metadata, so implementations on operation behaviors for these operations are not exported. + The endpoint is exported by first exporting its contract.When exporting a contract the calls the method on all implementations on the contract, and operation behaviors for that contract. Operations that use wildcard actions are not exported in metadata, so implementations on operation behaviors for these operations are not exported. After exporting the contract, the port and binding are exported and exported policy expressions are attached. diff --git a/xml/System.ServiceModel.Description/IWsdlImportExtension.xml b/xml/System.ServiceModel.Description/IWsdlImportExtension.xml index 592c893fd39ad..6f4e77ff1660b 100644 --- a/xml/System.ServiceModel.Description/IWsdlImportExtension.xml +++ b/xml/System.ServiceModel.Description/IWsdlImportExtension.xml @@ -23,7 +23,7 @@ ## Examples - The following code example shows the use of to add an and an (the `WsdlDocumentationImporter`, in this case) to modify generated [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client code at the interface and operation level. + The following code example shows the use of to add an and an (the `WsdlDocumentationImporter`, in this case) to modify generated [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client code at the interface and operation level. [!code-csharp[C_CustomWSDLExtensions#4](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#4)] @@ -91,12 +91,12 @@ method is called when a contract is being imported. You can modify the contract or insert other exporting behaviors such as and an objects to modify the code that is generated for the contract. + The method is called when a contract is being imported. You can modify the contract or insert other exporting behaviors such as and an objects to modify the code that is generated for the contract. ## Examples - The following code example shows the use of to add an and an (the `WsdlDocumentationImporter`, in this case) to modify generated [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client code at the interface and operation level. + The following code example shows the use of to add an and an (the `WsdlDocumentationImporter`, in this case) to modify generated [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client code at the interface and operation level. [!code-csharp[C_CustomWSDLExtensions#4](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#4)] diff --git a/xml/System.ServiceModel.Description/MessageHeaderDescriptionCollection.xml b/xml/System.ServiceModel.Description/MessageHeaderDescriptionCollection.xml index 481d8f56529ba..05fd8fc68935f 100644 --- a/xml/System.ServiceModel.Description/MessageHeaderDescriptionCollection.xml +++ b/xml/System.ServiceModel.Description/MessageHeaderDescriptionCollection.xml @@ -21,7 +21,7 @@ property and enables you to find, insert, and remove various objects. + Typically this collection is returned from the property and enables you to find, insert, and remove various objects. ]]> diff --git a/xml/System.ServiceModel.Description/MessagePartDescription.xml b/xml/System.ServiceModel.Description/MessagePartDescription.xml index e60c46dde8f98..cc7dcbc4b4483 100644 --- a/xml/System.ServiceModel.Description/MessagePartDescription.xml +++ b/xml/System.ServiceModel.Description/MessagePartDescription.xml @@ -116,7 +116,7 @@ is loaded from a class marked by the , the property contains the or the from which the part was loaded. + If the is loaded from a class marked by the , the property contains the or the from which the part was loaded. ]]> diff --git a/xml/System.ServiceModel.Description/MessagePartDescriptionCollection.xml b/xml/System.ServiceModel.Description/MessagePartDescriptionCollection.xml index 8f8560dda5366..0426b47278a9a 100644 --- a/xml/System.ServiceModel.Description/MessagePartDescriptionCollection.xml +++ b/xml/System.ServiceModel.Description/MessagePartDescriptionCollection.xml @@ -21,7 +21,7 @@ objects by name and namespace. + Enables you to find objects by name and namespace. ]]> diff --git a/xml/System.ServiceModel.Description/MessagePropertyDescription.xml b/xml/System.ServiceModel.Description/MessagePropertyDescription.xml index 7ee6bda0fe7dc..99dfd9102609d 100644 --- a/xml/System.ServiceModel.Description/MessagePropertyDescription.xml +++ b/xml/System.ServiceModel.Description/MessagePropertyDescription.xml @@ -17,7 +17,7 @@ class represents message properties specified in a message contract by the use of the . Message properties are used to place information on the message that can be used by other objects further on in the message pipeline but that are not serialized with the message. + The class represents message properties specified in a message contract by the use of the . Message properties are used to place information on the message that can be used by other objects further on in the message pipeline but that are not serialized with the message. ]]> diff --git a/xml/System.ServiceModel.Description/MessagePropertyDescriptionCollection.xml b/xml/System.ServiceModel.Description/MessagePropertyDescriptionCollection.xml index 70e77421b1255..5afe44710b48c 100644 --- a/xml/System.ServiceModel.Description/MessagePropertyDescriptionCollection.xml +++ b/xml/System.ServiceModel.Description/MessagePropertyDescriptionCollection.xml @@ -21,7 +21,7 @@ objects by name. + Enables you to find objects by name. ]]> diff --git a/xml/System.ServiceModel.Description/MetadataExchangeClient.xml b/xml/System.ServiceModel.Description/MetadataExchangeClient.xml index eaa98b94551ed..25b26036808f3 100644 --- a/xml/System.ServiceModel.Description/MetadataExchangeClient.xml +++ b/xml/System.ServiceModel.Description/MetadataExchangeClient.xml @@ -16,7 +16,7 @@ to download metadata. Typically, a is configured for a metadata request and then passed to the or method for the to use to download metadata. + Use the to download metadata. Typically, a is configured for a metadata request and then passed to the or method for the to use to download metadata. However, you can use the directly to retrieve metadata as a that contains objects. @@ -68,8 +68,8 @@ |Scheme|Binding| |------------|-------------| -|http| ()| -|https| ()| +|http| ()| +|https| ()| |net.tcp| with a | |net.pipe| with a | @@ -195,7 +195,7 @@ . + Use this constructor to specify the address and whether to use an HTTP GET request or WS-Transfer Get. [!INCLUDE[crdefault](~/includes/crdefault-md.md)]. @@ -609,9 +609,9 @@ ## Remarks The method is called: -- When there is an attempt to resolve a . +- When there is an attempt to resolve a . -- When is used. +- When is used. ]]> @@ -712,7 +712,7 @@ property to `false` to prevent the resolution of references to metadata. In this case, references are returned as or objects inside the . + Set the property to `false` to prevent the resolution of references to metadata. In this case, references are returned as or objects inside the . ]]> diff --git a/xml/System.ServiceModel.Description/MetadataExchangeClientMode.xml b/xml/System.ServiceModel.Description/MetadataExchangeClientMode.xml index a3e31c28169cf..8e178474436ff 100644 --- a/xml/System.ServiceModel.Description/MetadataExchangeClientMode.xml +++ b/xml/System.ServiceModel.Description/MetadataExchangeClientMode.xml @@ -16,7 +16,7 @@ with the to specify whether metadata is downloaded using an HTTP GET or WS-Transfer Get request. + Use the with the to specify whether metadata is downloaded using an HTTP GET or WS-Transfer Get request. diff --git a/xml/System.ServiceModel.Description/MetadataExporter.xml b/xml/System.ServiceModel.Description/MetadataExporter.xml index d9773bdde7994..9f568d6136277 100644 --- a/xml/System.ServiceModel.Description/MetadataExporter.xml +++ b/xml/System.ServiceModel.Description/MetadataExporter.xml @@ -16,20 +16,20 @@ objects, use an implementation of the abstract class. A implementation generates metadata that is encapsulated in a instance. + Metadata export is the process of describing service endpoints and projecting them into a parallel, standardized representation (typically, but not necessarily XML) that applications can access to implement a client that uses the service. To export metadata from objects, use an implementation of the abstract class. A implementation generates metadata that is encapsulated in a instance. - The class provides a framework for generating policy expressions that describe the capabilities and requirements of an endpoint binding and its associated operations, messages and faults. These policy expressions are captured in a instance. A implementation can then attach these policy expressions to the metadata it generates. + The class provides a framework for generating policy expressions that describe the capabilities and requirements of an endpoint binding and its associated operations, messages and faults. These policy expressions are captured in a instance. A implementation can then attach these policy expressions to the metadata it generates. - The calls into each that implements the interface in the binding of a when generating a object for the implementation to use. You can export new policy assertions by implementing the interface on your custom implementations of the type. + The calls into each that implements the interface in the binding of a when generating a object for the implementation to use. You can export new policy assertions by implementing the interface on your custom implementations of the type. - The type is the implementation of the class included with [!INCLUDE[indigo1](~/includes/indigo1-md.md)]. The type generates WSDL metadata with attached policy expressions. + The type is the implementation of the class included with [!INCLUDE[indigo1](~/includes/indigo1-md.md)]. The type generates WSDL metadata with attached policy expressions. - To export custom WSDL metadata or WSDL extensions for endpoint behaviors, contract behaviors or binding elements in a service endpoint, you can implement the interface. The type calls into parts of a service endpoint that implement this interface when generating the WSDL document from that endpoint. + To export custom WSDL metadata or WSDL extensions for endpoint behaviors, contract behaviors or binding elements in a service endpoint, you can implement the interface. The type calls into parts of a service endpoint that implement this interface when generating the WSDL document from that endpoint. ## Examples - The following code example is an method that demonstrates how the property of the class is used to attach a custom that modifies the export of data contracts in the endpoint. + The following code example is an method that demonstrates how the property of the class is used to attach a custom that modifies the export of data contracts in the endpoint. [!code-csharp[C_CustomWSDLExtensions#6](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationattribute.cs#6)] [!code-csharp[C_CustomWSDLExtensions#5](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationattribute.cs#5)] @@ -216,7 +216,7 @@ ## Examples - The following code example is an method that demonstrates how the property of the derived class is used to attach a custom that modifies the export of data contracts in the endpoint. + The following code example is an method that demonstrates how the property of the derived class is used to attach a custom that modifies the export of data contracts in the endpoint. [!code-csharp[C_CustomWSDLExtensions#6](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationattribute.cs#6)] [!code-csharp[C_CustomWSDLExtensions#5](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationattribute.cs#5)] diff --git a/xml/System.ServiceModel.Description/MetadataImporter.xml b/xml/System.ServiceModel.Description/MetadataImporter.xml index 58ca9b4d57132..b62ee887bbf0c 100644 --- a/xml/System.ServiceModel.Description/MetadataImporter.xml +++ b/xml/System.ServiceModel.Description/MetadataImporter.xml @@ -18,13 +18,13 @@ ## Remarks Use an implementation of the abstract class to import service metadata. Types that derive from the class implement support for importing metadata formats that take advantage of the WS-Policy import logic in [!INCLUDE[indigo1](~/includes/indigo1-md.md)]. - A implementation collects the policy expressions attached to the service metadata in a object. The then processes the policies as part of importing the metadata by calling the implementations of the interface in the property. + A implementation collects the policy expressions attached to the service metadata in a object. The then processes the policies as part of importing the metadata by calling the implementations of the interface in the property. - You can add support for importing new policy assertions to a by adding your own implementation of the interface to the property on a instance. Alternatively, you can register your policy import extension in your application configuration file. + You can add support for importing new policy assertions to a by adding your own implementation of the interface to the property on a instance. Alternatively, you can register your policy import extension in your application configuration file. - The type is the implementation of the abstract class included with [!INCLUDE[indigo2](~/includes/indigo2-md.md)]. The type imports WSDL metadata with attached policies that are bundled in a object. + The type is the implementation of the abstract class included with [!INCLUDE[indigo2](~/includes/indigo2-md.md)]. The type imports WSDL metadata with attached policies that are bundled in a object. - You can add support for importing WSDL extensions by implementing the interface and then adding your implementation to the property on your instance. The can also load implementations of the interface registered in your application configuration file. + You can add support for importing WSDL extensions by implementing the interface and then adding your implementation to the property on your instance. The can also load implementations of the interface registered in your application configuration file. > [!NOTE] > Because the constructor is internal, you cannot derive from in this version. @@ -32,7 +32,7 @@ ## Examples - The following example shows the use of the derived class to import metadata using custom state, checking the property, compiling imported metadata to managed types and saving the result to a code file. + The following example shows the use of the derived class to import metadata using custom state, checking the property, compiling imported metadata to managed types and saving the result to a code file. [!code-csharp[C_CustomWSDLExtensions#8](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/client.cs#8)] @@ -104,7 +104,7 @@ method to return all endpoints in the imported metadata. Metadata that has been imported as service endpoints cannot be used to create a runtime or export metadata because the imported endpoints contain no managed type information. To use the metadata to create a client or service runtime or to generate metadata, you must first generate and compile code from the metadata and use that type information to create a new object using . + Implement the method to return all endpoints in the imported metadata. Metadata that has been imported as service endpoints cannot be used to create a runtime or export metadata because the imported endpoints contain no managed type information. To use the metadata to create a client or service runtime or to generate metadata, you must first generate and compile code from the metadata and use that type information to create a new object using . ]]> @@ -184,7 +184,7 @@ ## Examples - The following example shows the use of the property to add a custom to import data structures in a particular way. + The following example shows the use of the property to add a custom to import data structures in a particular way. [!code-csharp[C_CustomWSDLExtensions#8](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/client.cs#8)] diff --git a/xml/System.ServiceModel.Description/MetadataResolver.xml b/xml/System.ServiceModel.Description/MetadataResolver.xml index aa6215da2aa3a..b39fe81998c96 100644 --- a/xml/System.ServiceModel.Description/MetadataResolver.xml +++ b/xml/System.ServiceModel.Description/MetadataResolver.xml @@ -16,7 +16,7 @@ class to quickly import endpoints for a service from metadata. This class downloads and converts metadata into objects. To download metadata and process that information as a , see . + Use the class to quickly import endpoints for a service from metadata. This class downloads and converts metadata into objects. To download metadata and process that information as a , see . @@ -79,9 +79,9 @@ are used to retrieve the metadata and the default is . + The default settings on the are used to retrieve the metadata and the default is . - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -122,9 +122,9 @@ are used to retrieve the metadata and the default is . + The default settings on the are used to retrieve the metadata and the default is . - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -169,9 +169,9 @@ is . + The default is . - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -214,9 +214,9 @@ are used to retrieve the metadata. + The default settings on the are used to retrieve the metadata. - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -259,9 +259,9 @@ are used to retrieve the metadata. + The default settings on the are used to retrieve the metadata. - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -304,7 +304,7 @@ objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -356,7 +356,7 @@ objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. For all synchronous and asynchronous `Resolve` methods, an empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -389,9 +389,9 @@ are used to retrieve the metadata and the default is . + The default settings on the are used to retrieve the metadata and the default is . - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -430,9 +430,9 @@ ## Remarks Use the method to specify the contract and the metadata address to use when downloading and resolving metadata. - The default settings on the are used to retrieve the metadata and the default is . + The default settings on the are used to retrieve the metadata and the default is . - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -480,9 +480,9 @@ is . + The default is . - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -521,9 +521,9 @@ are used to retrieve the metadata. + The default settings on the are used to retrieve the metadata. - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -564,9 +564,9 @@ ## Remarks Use the method to specify a contract, and address, and the download mechanism to use. - The default settings on the are used to retrieve the metadata. + The default settings on the are used to retrieve the metadata. - To download metadata but not resolve the information into objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. @@ -612,7 +612,7 @@ objects, use the directly. + To download metadata but not resolve the information into objects, use the directly. > [!NOTE] > An empty collection is returned if no endpoints were imported or if no endpoints matched the contract. If an empty collection is returned, a warning trace is written. diff --git a/xml/System.ServiceModel.Description/MetadataSection.xml b/xml/System.ServiceModel.Description/MetadataSection.xml index 14133167250c5..12d9e6b927537 100644 --- a/xml/System.ServiceModel.Description/MetadataSection.xml +++ b/xml/System.ServiceModel.Description/MetadataSection.xml @@ -32,7 +32,7 @@ ## Examples - The following code example shows how to retrieve the objects from a and iterate through them to write the and properties to the console. + The following code example shows how to retrieve the objects from a and iterate through them to write the and properties to the console. [!code-csharp[MetadataResolver#3](~/samples/snippets/csharp/VS_Snippets_CFX/metadataresolver/cs/client.cs#3)] @@ -247,7 +247,7 @@ ## Examples - The following code example shows how to retrieve the objects from a and iterate through them to write the and properties to the console. + The following code example shows how to retrieve the objects from a and iterate through them to write the and properties to the console. [!code-csharp[MetadataResolver#3](~/samples/snippets/csharp/VS_Snippets_CFX/metadataresolver/cs/client.cs#3)] @@ -284,7 +284,7 @@ ## Examples - The following code example shows how to retrieve the objects from a and iterate through them to write the and properties to the console. + The following code example shows how to retrieve the objects from a and iterate through them to write the and properties to the console. [!code-csharp[MetadataResolver#3](~/samples/snippets/csharp/VS_Snippets_CFX/metadataresolver/cs/client.cs#3)] @@ -335,11 +335,11 @@ |Type of XML metadata|Returned type| |--------------------------|-------------------| -|WSDL document|| -|XML Schema|| -|Metadata reference|| -|Metadata location|| -|Policy, and all other XML content|| +|WSDL document|| +|XML Schema|| +|Metadata reference|| +|Metadata location|| +|Policy, and all other XML content|| ]]> diff --git a/xml/System.ServiceModel.Description/MustUnderstandBehavior.xml b/xml/System.ServiceModel.Description/MustUnderstandBehavior.xml index 3d22b689b7d63..fc1e66640b32f 100644 --- a/xml/System.ServiceModel.Description/MustUnderstandBehavior.xml +++ b/xml/System.ServiceModel.Description/MustUnderstandBehavior.xml @@ -20,7 +20,7 @@ in a message for which the property is `true` but the header is not in the property for the message. + By default the [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client or service runtime throws an exception when it encounters a in a message for which the property is `true` but the header is not in the property for the message. To prevent this behavior, use the and set the property to `false`. Typically, this is used in scenarios where the message content is meant to be relayed somewhere else and not processed, such as a router service. @@ -47,7 +47,7 @@ in a message for which the property is `true` but the header is not in the property for the message. + Pass `false` as the `validate` parameter to this constructor to prevent an exception from being thrown when the runtime encounters a in a message for which the property is `true` but the header is not in the property for the message. ]]> @@ -191,7 +191,7 @@ property to `false` to prevent an exception from being thrown when the runtime encounters a in a message for which the property is `true` but the header is not in the property for the message. + Set the property to `false` to prevent an exception from being thrown when the runtime encounters a in a message for which the property is `true` but the header is not in the property for the message. ]]> diff --git a/xml/System.ServiceModel.Description/OperationContractGenerationContext.xml b/xml/System.ServiceModel.Description/OperationContractGenerationContext.xml index 492f91a737daa..040c8b0272c0a 100644 --- a/xml/System.ServiceModel.Description/OperationContractGenerationContext.xml +++ b/xml/System.ServiceModel.Description/OperationContractGenerationContext.xml @@ -16,12 +16,12 @@ object passed to the method to modify the code document object model prior to the generation of code. Typically, the interface is implemented on a custom implementation that is used to import custom WSDL elements or otherwise modify the code at the service or operation level. To modify the code at the service level, see . + Use the object passed to the method to modify the code document object model prior to the generation of code. Typically, the interface is implemented on a custom implementation that is used to import custom WSDL elements or otherwise modify the code at the service or operation level. To modify the code at the service level, see . ## Examples - The following example shows the use of the object passed to the method to add code comments extracted from custom WSDL elements. + The following example shows the use of the object passed to the method to add code comments extracted from custom WSDL elements. [!code-csharp[C_CustomWSDLExtensions#14](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#14)] @@ -362,7 +362,7 @@ ## Examples - The following example shows the use of the object passed to the method to add code comments extracted from custom WSDL elements. + The following example shows the use of the object passed to the method to add code comments extracted from custom WSDL elements. [!code-csharp[C_CustomWSDLExtensions#14](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#14)] diff --git a/xml/System.ServiceModel.Description/OperationDescription.xml b/xml/System.ServiceModel.Description/OperationDescription.xml index 7a83e5f4ecf1e..3f8b06ba9674d 100644 --- a/xml/System.ServiceModel.Description/OperationDescription.xml +++ b/xml/System.ServiceModel.Description/OperationDescription.xml @@ -218,7 +218,7 @@ The property controls whether an operation can be the first operation called when a session is created. > [!NOTE] -> The value of must be `true` and the binding used must support sessions for the property to work properly. +> The value of must be `true` and the binding used must support sessions for the property to work properly. The default is `true`, which means that an operation can be the first one called on a channel. Subsequent calls to the initiating method have no effect, other than to call the method. No other sessions are created. diff --git a/xml/System.ServiceModel.Description/ServiceContractGenerationContext.xml b/xml/System.ServiceModel.Description/ServiceContractGenerationContext.xml index 0b6823f0a8ce7..9b19f68514d72 100644 --- a/xml/System.ServiceModel.Description/ServiceContractGenerationContext.xml +++ b/xml/System.ServiceModel.Description/ServiceContractGenerationContext.xml @@ -16,12 +16,12 @@ object passed to the method to modify the code document object model prior to the generation of code. Typically, the interface is implemented on a custom implementation that is used to import custom WSDL elements or otherwise modify the code at the service or operation level. To modify the code at the operation level, see . + Use the object passed to the method to modify the code document object model prior to the generation of code. Typically, the interface is implemented on a custom implementation that is used to import custom WSDL elements or otherwise modify the code at the service or operation level. To modify the code at the operation level, see . ## Examples - The following example shows the use of the object passed to the method to add code comments extracted from custom WSDL elements. + The following example shows the use of the object passed to the method to add code comments extracted from custom WSDL elements. [!code-csharp[C_CustomWSDLExtensions#12](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#12)] @@ -99,7 +99,7 @@ property to examine the for the current contract. + Use the property to examine the for the current contract. ]]> @@ -124,12 +124,12 @@ property to examine or modify the for the current contract before the code is generated. + Use the property to examine or modify the for the current contract before the code is generated. ## Examples - The following example shows the use of the object passed to the method to add code comments extracted from custom WSDL elements. + The following example shows the use of the object passed to the method to add code comments extracted from custom WSDL elements. [!code-csharp[C_CustomWSDLExtensions#12](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationimporter.cs#12)] @@ -161,7 +161,7 @@ property to examine or modify the for the duplex callback contract on the service contract prior to generating code. + Use the property to examine or modify the for the duplex callback contract on the service contract prior to generating code. ]]> @@ -186,7 +186,7 @@ property to examine or modify the objects that represent the contract operations. + Use the property to examine or modify the objects that represent the contract operations. ]]> diff --git a/xml/System.ServiceModel.Description/ServiceContractGenerationOptions.xml b/xml/System.ServiceModel.Description/ServiceContractGenerationOptions.xml index 54e20e5c1dce7..edf7ec8454624 100644 --- a/xml/System.ServiceModel.Description/ServiceContractGenerationOptions.xml +++ b/xml/System.ServiceModel.Description/ServiceContractGenerationOptions.xml @@ -21,7 +21,7 @@ enumeration with the property to control the generated contract code. + Use the enumeration with the property to control the generated contract code. ]]> diff --git a/xml/System.ServiceModel.Description/ServiceContractGenerator.xml b/xml/System.ServiceModel.Description/ServiceContractGenerator.xml index 64440b6877d3b..eec2db8e2e2fb 100644 --- a/xml/System.ServiceModel.Description/ServiceContractGenerator.xml +++ b/xml/System.ServiceModel.Description/ServiceContractGenerator.xml @@ -16,7 +16,7 @@ to create tools or to modify the default contract generation process using an . + Use the to create tools or to modify the default contract generation process using an . @@ -200,7 +200,7 @@ property. + Other code artifacts may also get generated as specified by using the property. ]]> @@ -231,7 +231,7 @@ property. + Other code artifacts may also get generated as specified by using the property. ]]> @@ -285,7 +285,7 @@ attribute that allows a bitwise combination of its member values. + Use this property to specify various options for code generation. This enumeration has a attribute that allows a bitwise combination of its member values. ]]> diff --git a/xml/System.ServiceModel.Description/ServiceCredentials.xml b/xml/System.ServiceModel.Description/ServiceCredentials.xml index 945a0964691f3..333f3344c5f85 100644 --- a/xml/System.ServiceModel.Description/ServiceCredentials.xml +++ b/xml/System.ServiceModel.Description/ServiceCredentials.xml @@ -20,7 +20,7 @@ method, by methods of the , and is returned by the property. + This class is used as a parameter in the method, by methods of the , and is returned by the property. diff --git a/xml/System.ServiceModel.Description/ServiceDebugBehavior.xml b/xml/System.ServiceModel.Description/ServiceDebugBehavior.xml index 1f287608cbe56..9a20f23fe55db 100644 --- a/xml/System.ServiceModel.Description/ServiceDebugBehavior.xml +++ b/xml/System.ServiceModel.Description/ServiceDebugBehavior.xml @@ -54,9 +54,9 @@ ## Examples The following code example shows how to use a configuration file to enable the HTML help page feature and return exception information inside a SOAP fault back to the client for debugging purposes, in addition to enabling metadata support. This configuration file shows the following basic steps to adding support for the features: -- Because the type is an implementation, the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element that represents the service type has a behavior configuration identifier of `behaviorConfiguration="metadataAndDebug"`. +- Because the type is an implementation, the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element that represents the service type has a behavior configuration identifier of `behaviorConfiguration="metadataAndDebug"`. -- Because the type is an implementation a [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element is added to a [<serviceBehaviors>](~/docs/framework/configure-apps/file-schema/wcf/servicebehaviors.md) section. Set the `name` attribute of the [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element the value of which is the identifier of the `behaviorConfiguration` attribute of the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element. In this case, the value is `metadataAndDebug`. +- Because the type is an implementation a [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element is added to a [<serviceBehaviors>](~/docs/framework/configure-apps/file-schema/wcf/servicebehaviors.md) section. Set the `name` attribute of the [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element the value of which is the identifier of the `behaviorConfiguration` attribute of the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element. In this case, the value is `metadataAndDebug`. - Add a [<serviceDebug>](~/docs/framework/configure-apps/file-schema/wcf/servicedebug.md) element with the various attributes set to the desired configuration. In this case, the `httpHelpPageEnabled` and `includeExceptionDetailInFaults` attribute values are set to `true`. @@ -156,9 +156,9 @@ ## Examples The following code example shows how to use a configuration file to enable the HTML help page feature and return exception information inside a SOAP fault back to the client for debugging purposes. This configuration file shows the following basic steps to adding support for the features: -- Because the type is a implementation, the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element that represents the service type has a behavior configuration identifier of `behaviorConfiguration="metadataAndDebug"`. +- Because the type is a implementation, the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element that represents the service type has a behavior configuration identifier of `behaviorConfiguration="metadataAndDebug"`. -- Again, because the type is an implementation a [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element is added to a [<serviceBehaviors>](~/docs/framework/configure-apps/file-schema/wcf/servicebehaviors.md) section. The `name` attribute of the [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element the value of which is the identifier of the `behaviorConfiguration` attribute of the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element. In this case, the value is `metadataAndDebug`. +- Again, because the type is an implementation a [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element is added to a [<serviceBehaviors>](~/docs/framework/configure-apps/file-schema/wcf/servicebehaviors.md) section. The `name` attribute of the [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element the value of which is the identifier of the `behaviorConfiguration` attribute of the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element. In this case, the value is `metadataAndDebug`. - Add a [<serviceDebug>](~/docs/framework/configure-apps/file-schema/wcf/servicedebug.md) element with the various attributes set to the desired configuration. In this case, the `httpHelpPageEnabled` and `includeExceptionDetailInFaults` attribute values are set to `true`. @@ -352,9 +352,9 @@ ## Examples The following code example shows how to use a configuration file to enable the HTML help page feature and return exception information inside a SOAP fault back to the client for debugging purposes. This configuration file shows the following basic steps to adding support for the features: -- Because the type is an implementation, the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element that represents the service type has a behavior configuration identifier of `behaviorConfiguration="metadataAndDebug"`. +- Because the type is an implementation, the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element that represents the service type has a behavior configuration identifier of `behaviorConfiguration="metadataAndDebug"`. -- Again, because the type is an implementation a [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element is added to a [<serviceBehaviors>](~/docs/framework/configure-apps/file-schema/wcf/servicebehaviors.md) section. Set the `name` attribute of the [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element the value of which is the identifier of the `behaviorConfiguration` attribute of the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element. In this case, the value is `metadataAndDebug`. +- Again, because the type is an implementation a [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element is added to a [<serviceBehaviors>](~/docs/framework/configure-apps/file-schema/wcf/servicebehaviors.md) section. Set the `name` attribute of the [<behavior>](~/docs/framework/configure-apps/file-schema/wcf/behavior-of-endpointbehaviors.md) element the value of which is the identifier of the `behaviorConfiguration` attribute of the [<service>](~/docs/framework/configure-apps/file-schema/wcf/service.md) element. In this case, the value is `metadataAndDebug`. - Add a [<serviceDebug>](~/docs/framework/configure-apps/file-schema/wcf/servicedebug.md) element with the various attributes set to the desired configuration. In this case, the `httpHelpPageEnabled` and `includeExceptionDetailInFaults` attribute values are set to `true`. @@ -392,7 +392,7 @@ method. + Modifies the bindings to support the behavior. [!INCLUDE[crdefault](~/includes/crdefault-md.md)] the method. ]]> diff --git a/xml/System.ServiceModel.Description/ServiceMetadataBehavior.xml b/xml/System.ServiceModel.Description/ServiceMetadataBehavior.xml index e602345b660f3..6d1183924bd1c 100644 --- a/xml/System.ServiceModel.Description/ServiceMetadataBehavior.xml +++ b/xml/System.ServiceModel.Description/ServiceMetadataBehavior.xml @@ -20,7 +20,7 @@ object to the collection (or the [<serviceMetadata>](~/docs/framework/configure-apps/file-schema/wcf/servicemetadata.md) element in an application configuration file) to enable or disable the publication of service metadata. However, adding the behavior to a service is not sufficient to enable metadata publication: + Add a object to the collection (or the [<serviceMetadata>](~/docs/framework/configure-apps/file-schema/wcf/servicemetadata.md) element in an application configuration file) to enable or disable the publication of service metadata. However, adding the behavior to a service is not sufficient to enable metadata publication: - To enable WS-Transfer GET metadata retrieval, you must also add an endpoint to your service in which the contract is `IMetadataExchange`. For an example, see [How to: Publish Metadata for a Service Using Code](~/docs/framework/wcf/feature-details/how-to-publish-metadata-for-a-service-using-code.md). The `IMetadataExchange` endpoint can be configured as can any other endpoint. diff --git a/xml/System.ServiceModel.Description/ServiceMetadataExtension.xml b/xml/System.ServiceModel.Description/ServiceMetadataExtension.xml index 8254954b27990..4a19661baa2ef 100644 --- a/xml/System.ServiceModel.Description/ServiceMetadataExtension.xml +++ b/xml/System.ServiceModel.Description/ServiceMetadataExtension.xml @@ -20,7 +20,7 @@ is configured and used by configuring a service with the . + The is configured and used by configuring a service with the . You can also use the class to get the service's metadata at runtime by accessing the property. diff --git a/xml/System.ServiceModel.Description/ServiceThrottlingBehavior.xml b/xml/System.ServiceModel.Description/ServiceThrottlingBehavior.xml index c4ffee9a39e09..f96365f9fb5b7 100644 --- a/xml/System.ServiceModel.Description/ServiceThrottlingBehavior.xml +++ b/xml/System.ServiceModel.Description/ServiceThrottlingBehavior.xml @@ -158,7 +158,7 @@ property specifies the maximum number of sessions a object can accept. It is important to understand that sessions in this case does not mean only channels that support reliable sessions (for example, supports sessions but does not include reliable sessions). + The property specifies the maximum number of sessions a object can accept. It is important to understand that sessions in this case does not mean only channels that support reliable sessions (for example, supports sessions but does not include reliable sessions). Each listener object can have one pending channel session that does not count against the value of until [!INCLUDE[indigo2](~/includes/indigo2-md.md)] accepts the channel session and begins processing messages on it. This property is most useful in scenarios that make use of sessions. diff --git a/xml/System.ServiceModel.Description/WsdlContractConversionContext.xml b/xml/System.ServiceModel.Description/WsdlContractConversionContext.xml index 6be9aacc56aec..d071faa0b056e 100644 --- a/xml/System.ServiceModel.Description/WsdlContractConversionContext.xml +++ b/xml/System.ServiceModel.Description/WsdlContractConversionContext.xml @@ -138,7 +138,7 @@ to add custom WSDL annotations to the exported metadata using the and properties. When exporting operations, the method iterates through the operation descriptions, and locates each associated by calling the method. + The following code example shows the use of the to add custom WSDL annotations to the exported metadata using the and properties. When exporting operations, the method iterates through the operation descriptions, and locates each associated by calling the method. [!code-csharp[C_CustomWSDLExtensions#7](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/wsdldocumentationattribute.cs#7)] diff --git a/xml/System.ServiceModel.Description/WsdlEndpointConversionContext.xml b/xml/System.ServiceModel.Description/WsdlEndpointConversionContext.xml index 906d3f4ab04bc..61aeb01e23d16 100644 --- a/xml/System.ServiceModel.Description/WsdlEndpointConversionContext.xml +++ b/xml/System.ServiceModel.Description/WsdlEndpointConversionContext.xml @@ -16,11 +16,11 @@ class represents the context in which the custom WSDL for an endpoint is either exported using or imported using . The following properties enable you to retrieve the WSDL document object model for the current WSDL: + The class represents the context in which the custom WSDL for an endpoint is either exported using or imported using . The following properties enable you to retrieve the WSDL document object model for the current WSDL: -- The property gets the for the endpoint contract. +- The property gets the for the endpoint contract. -- The property gets the for the current endpoint. +- The property gets the for the current endpoint. - The property gets the binding for the current endpoint. diff --git a/xml/System.ServiceModel.Description/WsdlImporter.xml b/xml/System.ServiceModel.Description/WsdlImporter.xml index d2ccfb0666bde..c8d209e4afb19 100644 --- a/xml/System.ServiceModel.Description/WsdlImporter.xml +++ b/xml/System.ServiceModel.Description/WsdlImporter.xml @@ -35,14 +35,14 @@ > [!NOTE] > When importing WSDL port types, if the QName of the port type matches an entry in the dictionary then the port type is not imported and the known contract is used instead. - No values are returned from the properties until one of the import methods is called. Custom objects can either be loaded into the programmatically or using the client configuration [<wsdlImporters>](~/docs/framework/configure-apps/file-schema/wcf/wsdlimporters.md) element. + No values are returned from the properties until one of the import methods is called. Custom objects can either be loaded into the programmatically or using the client configuration [<wsdlImporters>](~/docs/framework/configure-apps/file-schema/wcf/wsdlimporters.md) element. - Metadata that has been imported as service endpoints cannot be used to create a runtime or export metadata because the imported endpoints contain no managed type information. To use the metadata to create a client or service runtime or to generate metadata, you must first generate and compile code from the metadata and use that type information to create a new object using . + Metadata that has been imported as service endpoints cannot be used to create a runtime or export metadata because the imported endpoints contain no managed type information. To use the metadata to create a client or service runtime or to generate metadata, you must first generate and compile code from the metadata and use that type information to create a new object using . ## Examples - The following code example shows how to use the to add a custom , import all contracts, and compile those contracts and save them to a file. + The following code example shows how to use the to add a custom , import all contracts, and compile those contracts and save them to a file. [!code-csharp[C_CustomWSDLExtensions#8](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/client.cs#8)] @@ -220,7 +220,7 @@ ## Examples - The following code example shows how to use the to add a custom , import all contracts, and compile those contracts and save them to a file. + The following code example shows how to use the to add a custom , import all contracts, and compile those contracts and save them to a file. [!code-csharp[C_CustomWSDLExtensions#8](~/samples/snippets/csharp/VS_Snippets_CFX/c_customwsdlextensions/cs/client.cs#8)] @@ -281,7 +281,7 @@ method to use a object to locate binding information in the metadata and return that binding information as a object. Check the property to determine whether there are any import errors before using the returned object. + Use the method to use a object to locate binding information in the metadata and return that binding information as a object. Check the property to determine whether there are any import errors before using the returned object. ]]> @@ -312,7 +312,7 @@ method to use a object to locate port type information in the metadata and return that information as a object. Check the property to determine whether there are any import errors before using the returned object. + Use the method to use a object to locate port type information in the metadata and return that information as a object. Check the property to determine whether there are any import errors before using the returned object. ]]> @@ -343,7 +343,7 @@ method to use a object to locate port type information in the metadata and return that information as a object. Check the property to determine whether there are any import errors before using the returned object. + Use the method to use a object to locate port type information in the metadata and return that information as a object. Check the property to determine whether there are any import errors before using the returned object. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/ClientOperation.xml b/xml/System.ServiceModel.Dispatcher/ClientOperation.xml index d29649eca7d1c..6c6fa56d21e29 100644 --- a/xml/System.ServiceModel.Dispatcher/ClientOperation.xml +++ b/xml/System.ServiceModel.Dispatcher/ClientOperation.xml @@ -55,7 +55,7 @@ ## Examples - The following code example shows an inserting a custom parameter inspector into each in the property. + The following code example shows an inserting a custom parameter inspector into each in the property. [!code-csharp[Interceptors#2](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#2)] [!code-vb[Interceptors#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#2)] @@ -132,7 +132,7 @@ . + By default this value corresponds to the value of . ]]> @@ -306,7 +306,7 @@ . + By default this value corresponds to the value of . ]]> @@ -333,7 +333,7 @@ . For issues related to one-way operations, see [One-Way Services](~/docs/framework/wcf/feature-details/one-way-services.md). + By default this value corresponds to the value of . For issues related to one-way operations, see [One-Way Services](~/docs/framework/wcf/feature-details/one-way-services.md). ]]> @@ -360,7 +360,7 @@ . + By default this value corresponds to the value of . ]]> @@ -386,7 +386,7 @@ . + By default this value corresponds to the value of . ]]> @@ -417,7 +417,7 @@ ## Examples - The following code example shows an inserting a custom parameter inspector into each in the property. + The following code example shows an inserting a custom parameter inspector into each in the property. [!code-csharp[Interceptors#2](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#2)] [!code-vb[Interceptors#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#2)] @@ -465,7 +465,7 @@ . + By default this value corresponds to the value of . ]]> diff --git a/xml/System.ServiceModel.Dispatcher/ClientRuntime.xml b/xml/System.ServiceModel.Dispatcher/ClientRuntime.xml index 5d34af2b619ef..9d6374d5122dd 100644 --- a/xml/System.ServiceModel.Dispatcher/ClientRuntime.xml +++ b/xml/System.ServiceModel.Dispatcher/ClientRuntime.xml @@ -61,7 +61,7 @@ ## Examples - In the following code example an inserts a into the client runtime by adding it to the property. + In the following code example an inserts a into the client runtime by adding it to the property. [!code-csharp[Interceptors#2](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#2)] [!code-vb[Interceptors#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#2)] @@ -361,7 +361,7 @@ ## Examples - In the following code example an inserts a into the client runtime by adding it to the property. + In the following code example an inserts a into the client runtime by adding it to the property. [!code-csharp[Interceptors#2](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#2)] [!code-vb[Interceptors#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#2)] @@ -419,7 +419,7 @@ ## Examples - In the following code example an inserts a into the client runtime by adding it to each in the property. + In the following code example an inserts a into the client runtime by adding it to each in the property. [!code-csharp[Interceptors#2](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#2)] [!code-vb[Interceptors#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#2)] @@ -522,7 +522,7 @@ ## Remarks Set the property to specify a transport address for messages when the immediate destination of messages is not the client's . This enables you to specify SOAP intermediaries and handle scenarios in which the value of the property of the client is a logical name. - It is this value that the sets from a configuration file. + It is this value that the sets from a configuration file. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/DispatchOperation.xml b/xml/System.ServiceModel.Dispatcher/DispatchOperation.xml index eaad03c67cc35..76b6ce5206446 100644 --- a/xml/System.ServiceModel.Dispatcher/DispatchOperation.xml +++ b/xml/System.ServiceModel.Dispatcher/DispatchOperation.xml @@ -147,7 +147,7 @@ parameters (input, output or reference parameters) that were created while processing a message. The default value is `true`. Set this property to `false` to prevent the system from disposing resources. In this case, you are responsible for the parameter lifetimes. See the event if you need to dispose parameters when the operation completes. + This property determines whether the service disposes all parameters (input, output or reference parameters) that were created while processing a message. The default value is `true`. Set this property to `false` to prevent the system from disposing resources. In this case, you are responsible for the parameter lifetimes. See the event if you need to dispose parameters when the operation completes. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/DispatchRuntime.xml b/xml/System.ServiceModel.Dispatcher/DispatchRuntime.xml index 5ad3c61bbf5f6..b662c5c4f2f31 100644 --- a/xml/System.ServiceModel.Dispatcher/DispatchRuntime.xml +++ b/xml/System.ServiceModel.Dispatcher/DispatchRuntime.xml @@ -312,7 +312,7 @@ object to this property to control the manner in which input sessions are closed. When a call to the method on the first returns `null`, (which indicates that the input session has been closed), the dispatcher invokes each object, passing it an object. Custom objects can use this object to perform clean-up for each channel state or to send a response message before closing the channel. + Add an object to this property to control the manner in which input sessions are closed. When a call to the method on the first returns `null`, (which indicates that the input session has been closed), the dispatcher invokes each object, passing it an object. Custom objects can use this object to perform clean-up for each channel state or to send a response message before closing the channel. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/EndpointDispatcher.xml b/xml/System.ServiceModel.Dispatcher/EndpointDispatcher.xml index 6265c2019c82d..7068ea45b9572 100644 --- a/xml/System.ServiceModel.Dispatcher/EndpointDispatcher.xml +++ b/xml/System.ServiceModel.Dispatcher/EndpointDispatcher.xml @@ -17,9 +17,9 @@ and the classes expose the runtime customization points for endpoints in a service. The can be used to control which messages it can process and some endpoint-related information. The has a large number of properties used to insert custom extensions into the endpoint-wide runtime. + The and the classes expose the runtime customization points for endpoints in a service. The can be used to control which messages it can process and some endpoint-related information. The has a large number of properties used to insert custom extensions into the endpoint-wide runtime. - The object is responsible for processing messages from a when the destination address of a message matches the property and the message action matches the property. If two objects can accept a message, the property value determines the higher priority endpoint. + The object is responsible for processing messages from a when the destination address of a message matches the property and the message action matches the property. If two objects can accept a message, the property value determines the higher priority endpoint. Use the object to configure or extend the process of receiving messages from the associated , converting from message objects to objects used as parameters, and invoking an endpoint operation as well as the reverse process. @@ -44,7 +44,7 @@ ## Examples - The following code example shows the use of to locate the for the endpoint and inserts a custom message inspector using an endpoint behavior. + The following code example shows the use of to locate the for the endpoint and inserts a custom message inspector using an endpoint behavior. [!code-csharp[IEndpointBehavior#4](~/samples/snippets/csharp/VS_Snippets_CFX/iendpointbehavior/cs/iendpointbehaviormessageinspector.cs#4)] @@ -125,7 +125,7 @@ has an for each endpoint the channel can support. The property is a object that matches the destination endpoint address of the message. The combines the value with the value to determine whether to route a message to this endpoint. + The has an for each endpoint the channel can support. The property is a object that matches the destination endpoint address of the message. The combines the value with the value to determine whether to route a message to this endpoint. In the case where two objects that match can process a message, the property is used to select an endpoint. @@ -240,12 +240,12 @@ property to obtain the object to modify run-time values or insert custom run-time extensions for the entire endpoint. From the property, you can also navigate to the collection for the endpoint. + Use the property to obtain the object to modify run-time values or insert custom run-time extensions for the entire endpoint. From the property, you can also navigate to the collection for the endpoint. ## Examples - The following code example shows the use of to locate the for the endpoint and inserts a custom message inspector using an endpoint behavior. + The following code example shows the use of to locate the for the endpoint and inserts a custom message inspector using an endpoint behavior. [!code-csharp[IEndpointBehavior#4](~/samples/snippets/csharp/VS_Snippets_CFX/iendpointbehavior/cs/iendpointbehaviormessageinspector.cs#4)] @@ -294,7 +294,7 @@ In the case where two objects that match can process a message, the property is used to select an endpoint. - If two endpoints can process a message and the value of their property matches, a is thrown. + If two endpoints can process a message and the value of their property matches, a is thrown. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/FaultContractInfo.xml b/xml/System.ServiceModel.Dispatcher/FaultContractInfo.xml index 4711348a1ad5c..67150d1322695 100644 --- a/xml/System.ServiceModel.Dispatcher/FaultContractInfo.xml +++ b/xml/System.ServiceModel.Dispatcher/FaultContractInfo.xml @@ -17,7 +17,7 @@ objects by accessing the and properties. The class exposes the action of the SOAP fault and the detail type that is serialized into the SOAP fault. + You can get a collection of objects by accessing the and properties. The class exposes the action of the SOAP fault and the detail type that is serialized into the SOAP fault. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/ICallContextInitializer.xml b/xml/System.ServiceModel.Dispatcher/ICallContextInitializer.xml index 073e460639d2b..1a6e4e8940206 100644 --- a/xml/System.ServiceModel.Dispatcher/ICallContextInitializer.xml +++ b/xml/System.ServiceModel.Dispatcher/ICallContextInitializer.xml @@ -13,7 +13,7 @@ interface and add it to the property to initialize and clean up thread-local storage for the thread that invokes user code. Typical usage is to set some value, such as impersonation or changing the . If you wanted to establish some custom context, this is the extension point to initialize the static context property, which is then available for developers in the course of the operation. + Implement the interface and add it to the property to initialize and clean up thread-local storage for the thread that invokes user code. Typical usage is to set some value, such as impersonation or changing the . If you wanted to establish some custom context, this is the extension point to initialize the static context property, which is then available for developers in the course of the operation. ]]> @@ -74,7 +74,7 @@ method to initialize and clean up thread-local storage for the thread that invokes user code. Typical usage is to set some value, such as impersonation or changing the . If you wanted to establish some custom context, this is the extension point to initialize the static context property, which is then available for developers in the course of the operation. + Implement the method to initialize and clean up thread-local storage for the thread that invokes user code. Typical usage is to set some value, such as impersonation or changing the . If you wanted to establish some custom context, this is the extension point to initialize the static context property, which is then available for developers in the course of the operation. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/IChannelInitializer.xml b/xml/System.ServiceModel.Dispatcher/IChannelInitializer.xml index ce11a96b7d21d..c30b75f561a2f 100644 --- a/xml/System.ServiceModel.Dispatcher/IChannelInitializer.xml +++ b/xml/System.ServiceModel.Dispatcher/IChannelInitializer.xml @@ -14,7 +14,7 @@ collection. Add client channel initializers to the collection. + Defines the interface used to inspect and add state to channels when they are first created. This can be used to track all outstanding sessions, for instance, so the service can send messages on them. Add service channel initializers to the collection. Add client channel initializers to the collection. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/IClientMessageInspector.xml b/xml/System.ServiceModel.Dispatcher/IClientMessageInspector.xml index 23303cbba0a98..23c96aabf7c4d 100644 --- a/xml/System.ServiceModel.Dispatcher/IClientMessageInspector.xml +++ b/xml/System.ServiceModel.Dispatcher/IClientMessageInspector.xml @@ -24,7 +24,7 @@ [!code-csharp[Interceptors#1](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#1)] [!code-vb[Interceptors#1](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#1)] - The following code example shows how to use an to insert the client message inspector in the client endpoint. + The following code example shows how to use an to insert the client message inspector in the client endpoint. [!code-csharp[Interceptors#2](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#2)] [!code-vb[Interceptors#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#2)] @@ -64,7 +64,7 @@ ## Remarks Implement to inspect or modify a reply message after it has been received by the [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client object but before it is deserialized into objects that are returned to the client application. - The `correlationState` is the object returned by the user when is called for this message. The best practice is to make this a to ensure that no two `correlationState` objects are the same. + The `correlationState` is the object returned by the user when is called for this message. The best practice is to make this a to ensure that no two `correlationState` objects are the same. @@ -74,7 +74,7 @@ [!code-csharp[Interceptors#1](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#1)] [!code-vb[Interceptors#1](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#1)] - The following code example shows how to use an to insert the client message inspector in the client endpoint. + The following code example shows how to use an to insert the client message inspector in the client endpoint. [!code-csharp[Interceptors#2](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#2)] [!code-vb[Interceptors#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#2)] @@ -125,7 +125,7 @@ [!code-csharp[Interceptors#1](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#1)] [!code-vb[Interceptors#1](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#1)] - The following code example shows how to use an to insert the client message inspector in the client endpoint. + The following code example shows how to use an to insert the client message inspector in the client endpoint. [!code-csharp[Interceptors#2](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#2)] [!code-vb[Interceptors#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#2)] diff --git a/xml/System.ServiceModel.Dispatcher/IDispatchMessageInspector.xml b/xml/System.ServiceModel.Dispatcher/IDispatchMessageInspector.xml index 4cee9fed92e0e..8945a3f12f783 100644 --- a/xml/System.ServiceModel.Dispatcher/IDispatchMessageInspector.xml +++ b/xml/System.ServiceModel.Dispatcher/IDispatchMessageInspector.xml @@ -15,7 +15,7 @@ ## Remarks Implement to inspect or modify inbound or outbound application messages either prior to dispatching a request message to an operation or before returning a reply message to a caller. There are a large number of scenarios that require intercepting messages prior to invoking the operation for which it is destined. For example, you can log incoming application messages or perform some feature based on a message header. - Typically, message inspectors are inserted by a service behavior (), an endpoint behavior (), or a contract behavior (). The behavior then adds the message inspector to the collection. For more information about extending the runtime using behaviors, see [Extending ServiceHost and the Service Model Layer](~/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md). + Typically, message inspectors are inserted by a service behavior (), an endpoint behavior (), or a contract behavior (). The behavior then adds the message inspector to the collection. For more information about extending the runtime using behaviors, see [Extending ServiceHost and the Service Model Layer](~/docs/framework/wcf/extending/extending-servicehost-and-the-service-model-layer.md). - The method enables custom behavior after receiving the message but before dispatching it to the intended operation. @@ -32,7 +32,7 @@ [!code-csharp[Interceptors#7](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#7)] [!code-vb[Interceptors#7](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#7)] - The following code example shows the implementation of an that adds the `Inspector` to the collection. + The following code example shows the implementation of an that adds the `Inspector` to the collection. [!code-csharp[Interceptors#8](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#8)] [!code-vb[Interceptors#8](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#8)] @@ -85,7 +85,7 @@ [!code-csharp[Interceptors#7](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#7)] [!code-vb[Interceptors#7](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#7)] - The following code example shows the implementation of an that adds the `Inspector` to the collection. + The following code example shows the implementation of an that adds the `Inspector` to the collection. [!code-csharp[Interceptors#8](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#8)] [!code-vb[Interceptors#8](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#8)] @@ -132,7 +132,7 @@ [!code-csharp[Interceptors#7](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#7)] [!code-vb[Interceptors#7](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#7)] - The following code example shows the implementation of an that adds the `Inspector` to the collection. + The following code example shows the implementation of an that adds the `Inspector` to the collection. [!code-csharp[Interceptors#8](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#8)] [!code-vb[Interceptors#8](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#8)] diff --git a/xml/System.ServiceModel.Dispatcher/IErrorHandler.xml b/xml/System.ServiceModel.Dispatcher/IErrorHandler.xml index 3211664de3913..f74953ebe4ff3 100644 --- a/xml/System.ServiceModel.Dispatcher/IErrorHandler.xml +++ b/xml/System.ServiceModel.Dispatcher/IErrorHandler.xml @@ -22,7 +22,7 @@ > [!NOTE] > Because the method can be called from many different places there are no guarantees made about which thread the method is called on. Do not depend on method being called on the operation thread. - All implementations are called first, prior to sending a response message. When all implementations have been called and return, and if `fault` is non-`null`, it is sent back to the client according to the operation contract. If `fault` is `null` after all implementations have been called, the response message is controlled by the property value. + All implementations are called first, prior to sending a response message. When all implementations have been called and return, and if `fault` is non-`null`, it is sent back to the client according to the operation contract. If `fault` is `null` after all implementations have been called, the response message is controlled by the property value. > [!NOTE] > Exceptions can occur after all implementations are called and a response message is handed to the channel. If a channel exception occurs (for example, difficulty serializing the message) objects are notified. In this case, you should still make sure that your development environment catches and displays such exceptions to you or makes use of tracing to discover the problem. For more information about tracing, see [Using Tracing to Troubleshoot Your Application](~/docs/framework/wcf/diagnostics/tracing/using-tracing-to-troubleshoot-your-application.md). @@ -31,7 +31,7 @@ Typically, an implementation is added to the property on the service (and the client in the case of duplex communication). - You can add the to the runtime by implementing a behavior (either an , , , or object) and use the behavior programmatically, from a configuration file or with a custom attribute to attach your . + You can add the to the runtime by implementing a behavior (either an , , , or object) and use the behavior programmatically, from a configuration file or with a custom attribute to attach your . For more information about using behaviors to modify the runtime, see [Configuring and Extending the Runtime with Behaviors](~/docs/framework/wcf/extending/configuring-and-extending-the-runtime-with-behaviors.md). @@ -89,7 +89,7 @@ Return `true` from to prevent this default behavior. If any error handler returns `true` it instructs [!INCLUDE[indigo2](~/includes/indigo2-md.md)] that it is safe to continue using state associated with the failed request. - If no error handler returns `true` from the method the exception is considered unhandled and the default response applies, potentially resulting in an aborted and channel when communicating on a session channel or the property is not set to . + If no error handler returns `true` from the method the exception is considered unhandled and the default response applies, potentially resulting in an aborted and channel when communicating on a session channel or the property is not set to . The `error` parameter is never `null` and contains the exception object that was thrown. @@ -143,7 +143,7 @@ Implement the method to create a custom fault message that is returned to the client. The method will always be called for exceptions that leave operations, except when the WCF runtime recognizes the exception as especially fatal and rethrows the exception itself. When all implementations have been called, the fault message is sent back to the client (if `fault` is non-`null`). If the `fault` parameter is `null` the default fault is sent to the client. > [!NOTE] -> The inbound message that caused the processing error is available during this method from the property. +> The inbound message that caused the processing error is available during this method from the property. > [!NOTE] > Because the method can be called from many different places there are no guarantees made about which thread the method is called on. Do not depend on method being called on the operation thread. diff --git a/xml/System.ServiceModel.Dispatcher/IInstanceContextInitializer.xml b/xml/System.ServiceModel.Dispatcher/IInstanceContextInitializer.xml index 98a06923244c8..710eaff9a1164 100644 --- a/xml/System.ServiceModel.Dispatcher/IInstanceContextInitializer.xml +++ b/xml/System.ServiceModel.Dispatcher/IInstanceContextInitializer.xml @@ -17,7 +17,7 @@ There can be any number of context initializers for a service. Typically, the is added to attach an extension to the object as a mechanism for passing data throughout an application. - If you want to participate in providing or selecting the object that processes a message, see . + If you want to participate in providing or selecting the object that processes a message, see . ]]> diff --git a/xml/System.ServiceModel.Dispatcher/IInstanceContextProvider.xml b/xml/System.ServiceModel.Dispatcher/IInstanceContextProvider.xml index a3dab34aaccf6..2a320d5de61e5 100644 --- a/xml/System.ServiceModel.Dispatcher/IInstanceContextProvider.xml +++ b/xml/System.ServiceModel.Dispatcher/IInstanceContextProvider.xml @@ -13,14 +13,14 @@ interface to provide the appropriate object to the system. Typically, this interface is implemented to support shared sessions, enable service instance pooling, control lifetimes of service instances, or to group contexts among clients. + Implement the interface to provide the appropriate object to the system. Typically, this interface is implemented to support shared sessions, enable service instance pooling, control lifetimes of service instances, or to group contexts among clients. For example, to implement sharing, insert a custom to decide which session or call from a client is associated with which object. For an example that demonstrates the sharing of instance contexts, see [InstanceContextSharing](http://msdn.microsoft.com/en-us/4a6a46d7-b7d7-4bb5-a0dd-03ffa3cbc230). > [!NOTE] -> When an is inserted into [!INCLUDE[indigo1](~/includes/indigo1-md.md)], the normal property that controls the creation of objects (the property) is no longer checked and has no effect. +> When an is inserted into [!INCLUDE[indigo1](~/includes/indigo1-md.md)], the normal property that controls the creation of objects (the property) is no longer checked and has no effect. - A more generic mechanism by which you can initialize objects when created (for example, to attach custom extensions to each ) is the . + A more generic mechanism by which you can initialize objects when created (for example, to attach custom extensions to each ) is the . ]]> @@ -53,7 +53,7 @@ ## Remarks The method is called when a message is received. Return the object that you want to process the message, or `null`. In the case of `null`, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] creates a new object for the message and then calls the method. - If you return `null`, the new object goes through the throttling system and increments the count of . + If you return `null`, the new object goes through the throttling system and increments the count of . ]]> @@ -147,7 +147,7 @@ method is called when the method returns `false` to enable you to provide [!INCLUDE[indigo2](~/includes/indigo2-md.md)] with a object that you use to inform the runtime that the has finished its work. When the object notifies the runtime that the has finished its work, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] calls once again. This cycle continues until returns `true` and the context is closed and recycled. + The method is called when the method returns `false` to enable you to provide [!INCLUDE[indigo2](~/includes/indigo2-md.md)] with a object that you use to inform the runtime that the has finished its work. When the object notifies the runtime that the has finished its work, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] calls once again. This cycle continues until returns `true` and the context is closed and recycled. ]]> diff --git a/xml/System.ServiceModel.Dispatcher/IInteractiveChannelInitializer.xml b/xml/System.ServiceModel.Dispatcher/IInteractiveChannelInitializer.xml index b5d8c74dd76b0..bce4e65bf2212 100644 --- a/xml/System.ServiceModel.Dispatcher/IInteractiveChannelInitializer.xml +++ b/xml/System.ServiceModel.Dispatcher/IInteractiveChannelInitializer.xml @@ -16,29 +16,29 @@ ## Remarks Implement the interface to enable a client application to display a user interface that enables the user of the application to create or select the credentials prior to opening a channel. - To implement , perform the following steps in : + To implement , perform the following steps in : -1. Prompt the user and obtain an appropriate . +1. Prompt the user and obtain an appropriate . -2. Add a custom channel parameter object to the collection returned by the method on the object with a type parameter of . This channel parameter object is used by the custom to establish the security tokens for the channel. +2. Add a custom channel parameter object to the collection returned by the method on the object with a type parameter of . This channel parameter object is used by the custom to establish the security tokens for the channel. 3. Return. To insert : -1. Override the method on the class. +1. Override the method on the class. -2. In that method, determine whether the endpoint requires an and if so, add the to the collection. +2. In that method, determine whether the endpoint requires an and if so, add the to the collection. - There are two ways application developers can make use of an inserted . The client application can call either or (or an asynchronous version) prior to opening the channel (the *explicit* approach) or simply call the first operation (the *implicit* approach). + There are two ways application developers can make use of an inserted . The client application can call either or (or an asynchronous version) prior to opening the channel (the *explicit* approach) or simply call the first operation (the *implicit* approach). If using the implicit approach, the application must call the first operation on an or extension. If it calls anything other than the first operation, an exception is thrown. If using the explicit approach, the application must perform the following steps in order: -1. Call either or (or an asynchronous version). +1. Call either or (or an asynchronous version). -2. When the initializers have returned, call either the method on the object or on the object returned from the property. +2. When the initializers have returned, call either the method on the object or on the object returned from the property. 3. Call operations. @@ -78,11 +78,11 @@ , perform the following steps in : + To implement , perform the following steps in : -1. Prompt the user in what way you see fit and obtain an appropriate . +1. Prompt the user in what way you see fit and obtain an appropriate . -2. Add a custom channel parameter object to the collection returned by the method on the object with a type parameter of . This channel parameter object is used by the custom to establish the security tokens for the channel. +2. Add a custom channel parameter object to the collection returned by the method on the object with a type parameter of . This channel parameter object is used by the custom to establish the security tokens for the channel. 3. Return. diff --git a/xml/System.ServiceModel.Dispatcher/IParameterInspector.xml b/xml/System.ServiceModel.Dispatcher/IParameterInspector.xml index 943b28808a6bd..096bc8b60e24a 100644 --- a/xml/System.ServiceModel.Dispatcher/IParameterInspector.xml +++ b/xml/System.ServiceModel.Dispatcher/IParameterInspector.xml @@ -20,7 +20,7 @@ On inbound calls to a service, the inspector is invoked after parameters are deserialized but before they are dispatched to the service operation. - Use the or the properties to add an implementation to the inspectors collection for a particular operation. + Use the or the properties to add an implementation to the inspectors collection for a particular operation. **Note** Developers and administrators must ensure that the interaction with other implementations is understood. @@ -36,7 +36,7 @@ [!code-csharp[Interceptors#4](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#4)] [!code-vb[Interceptors#4](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#4)] - The following code example shows how to use either , or to insert objects. + The following code example shows how to use either , or to insert objects. [!code-csharp[Interceptors#5](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#5)] [!code-vb[Interceptors#5](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#5)] @@ -90,7 +90,7 @@ [!code-csharp[Interceptors#4](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#4)] [!code-vb[Interceptors#4](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#4)] - The following code example shows how to use either , , or to insert objects. + The following code example shows how to use either , , or to insert objects. [!code-csharp[Interceptors#5](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#5)] [!code-vb[Interceptors#5](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#5)] @@ -141,7 +141,7 @@ [!code-csharp[Interceptors#4](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/interceptors.cs#4)] [!code-vb[Interceptors#4](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/interceptors.vb#4)] - The following code example shows how to use either , or to insert objects. + The following code example shows how to use either , or to insert objects. [!code-csharp[Interceptors#5](~/samples/snippets/csharp/VS_Snippets_CFX/interceptors/cs/insertingbehaviors.cs#5)] [!code-vb[Interceptors#5](~/samples/snippets/visualbasic/VS_Snippets_CFX/interceptors/vb/insertingbehaviors.vb#5)] diff --git a/xml/System.ServiceModel.Dispatcher/InstanceContextIdleCallback.xml b/xml/System.ServiceModel.Dispatcher/InstanceContextIdleCallback.xml index e9c6cd02844f3..78b4293dac0e1 100644 --- a/xml/System.ServiceModel.Dispatcher/InstanceContextIdleCallback.xml +++ b/xml/System.ServiceModel.Dispatcher/InstanceContextIdleCallback.xml @@ -22,7 +22,7 @@ to notify the [!INCLUDE[indigo1](~/includes/indigo1-md.md)] runtime that an object has finished processing. When the object notifies the runtime that the has finished its work, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] calls once again. This cycle continues until returns `true` and the context is closed and recycled. + Use an to notify the [!INCLUDE[indigo1](~/includes/indigo1-md.md)] runtime that an object has finished processing. When the object notifies the runtime that the has finished its work, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] calls once again. This cycle continues until returns `true` and the context is closed and recycled. For more information, see . diff --git a/xml/System.ServiceModel.Dispatcher/ServiceThrottle.xml b/xml/System.ServiceModel.Dispatcher/ServiceThrottle.xml index edd931f540a28..24362006142ac 100644 --- a/xml/System.ServiceModel.Dispatcher/ServiceThrottle.xml +++ b/xml/System.ServiceModel.Dispatcher/ServiceThrottle.xml @@ -134,7 +134,7 @@ For more information about sessions, see [Using Sessions](~/docs/framework/wcf/using-sessions.md). - Typically, this property is set using the property. + Typically, this property is set using the property. diff --git a/xml/System.ServiceModel.Dispatcher/XPathMessageFilter.xml b/xml/System.ServiceModel.Dispatcher/XPathMessageFilter.xml index 83a94e8b90b68..8258a2fde5376 100644 --- a/xml/System.ServiceModel.Dispatcher/XPathMessageFilter.xml +++ b/xml/System.ServiceModel.Dispatcher/XPathMessageFilter.xml @@ -311,7 +311,7 @@ method to match elements from the body. An exception is thrown by this method if the engine attempts to access the message body in order to evaluate the XPath expression. This helps to ensure that the filter engine does not access the body stream. + Use the method to match elements from the body. An exception is thrown by this method if the engine attempts to access the message body in order to evaluate the XPath expression. This helps to ensure that the filter engine does not access the body stream. ]]> diff --git a/xml/System.ServiceModel.Security/MessageProtectionOrder.xml b/xml/System.ServiceModel.Security/MessageProtectionOrder.xml index e7f1945f042f3..d829cc6c8894f 100644 --- a/xml/System.ServiceModel.Security/MessageProtectionOrder.xml +++ b/xml/System.ServiceModel.Security/MessageProtectionOrder.xml @@ -15,7 +15,7 @@ property of the and the property of the classes. + This enumeration is used with the property of the and the property of the classes. If a message is vulnerable to a digest attack (for example, if the message is short or the entropy is low), you should use the SignBeforeEncryptAndEncryptSignature or EncryptBeforeSign option. (*Entropy* is random data provided by a server, a client, or both, and is used to create a shared key for encrypting and decrypting data.) diff --git a/xml/System.ServiceModel/CallbackBehaviorAttribute.xml b/xml/System.ServiceModel/CallbackBehaviorAttribute.xml index 973f2b5fc3f97..4c8becba6b035 100644 --- a/xml/System.ServiceModel/CallbackBehaviorAttribute.xml +++ b/xml/System.ServiceModel/CallbackBehaviorAttribute.xml @@ -165,7 +165,7 @@ In addition, if the is set to and a reentrant call is blocked while waiting for the instance to be freed, the system detects the deadlock and throws an exception. - [!INCLUDE[crabout](~/includes/crabout-md.md)] concurrency, see and [Sessions, Instancing, and Concurrency](~/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). + [!INCLUDE[crabout](~/includes/crabout-md.md)] concurrency, see and [Sessions, Instancing, and Concurrency](~/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). ]]> @@ -436,7 +436,7 @@ ## Remarks Use this property to provide the user interface thread affinity that some applications require. For example, a Windows Forms application may be registered as a singleton service object. In this case, all calls into the service must run on the Windows Forms thread. The default case, in which is set to `true`, synchronizes all calls to the service to run on the user interface thread. - Note that the thread used is the current synchronization thread when or is called. In the case of an Windows Forms application, this means that these calls should occur after a call to the method. + Note that the thread used is the current synchronization thread when or is called. In the case of an Windows Forms application, this means that these calls should occur after a call to the method. diff --git a/xml/System.ServiceModel/ClientBase`1.xml b/xml/System.ServiceModel/ClientBase`1.xml index e51506751e698..69112e2881bc4 100644 --- a/xml/System.ServiceModel/ClientBase`1.xml +++ b/xml/System.ServiceModel/ClientBase`1.xml @@ -34,9 +34,9 @@ ## Remarks Extend the class to create a custom [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client object that can be used to connect to a service. Typically, the [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client base class is extended by a tool such as the [ServiceModel Metadata Utility Tool (Svcutil.exe)](~/docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) on your behalf. For an example, see the Example section. - The class can be used quickly and easily by developers who prefer objects to the use of the interfaces and the class. In all cases this class wraps or exposes the methods and functionality of the class and the interface. + The class can be used quickly and easily by developers who prefer objects to the use of the interfaces and the class. In all cases this class wraps or exposes the methods and functionality of the class and the interface. - As when using the class, you can create the class and modify the endpoint, channel factory, or security information prior to making any calls or calling . [!INCLUDE[crdefault](~/includes/crdefault-md.md)][WCF Client Overview](~/docs/framework/wcf/wcf-client-overview.md) and [Accessing Services Using a WCF Client](~/docs/framework/wcf/accessing-services-using-a-wcf-client.md). + As when using the class, you can create the class and modify the endpoint, channel factory, or security information prior to making any calls or calling . [!INCLUDE[crdefault](~/includes/crdefault-md.md)][WCF Client Overview](~/docs/framework/wcf/wcf-client-overview.md) and [Accessing Services Using a WCF Client](~/docs/framework/wcf/accessing-services-using-a-wcf-client.md). Special note for Managed C++ users deriving from this class: @@ -72,7 +72,7 @@ where the type parameter is the type of the target service contract. + Use to create a [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client object from the endpoint information in the application configuration file. The main function of the constructor is to create a where the type parameter is the type of the target service contract. ]]> @@ -434,7 +434,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -557,7 +557,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -584,7 +584,7 @@ can be expected here. + Returns the channel created by the inner channel factory. Exceptions thrown by can be expected here. ]]> @@ -610,7 +610,7 @@ method if the inner channel requires user interaction prior to constructing the channel. For example, if a user must enter a username and password to secure the channel, that custom can be invoked by calling this method. + Call the method if the inner channel requires user interaction prior to constructing the channel. For example, if a user must enter a username and password to secure the channel, that custom can be invoked by calling this method. ]]> @@ -636,7 +636,7 @@ property to obtain the object to inspect or modify prior to using the object. + Use the property to obtain the object to inspect or modify prior to using the object. ]]> @@ -686,7 +686,7 @@ property to obtain the that is used to connect to the service. + Use the property to obtain the that is used to connect to the service. ]]> @@ -749,7 +749,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -775,7 +775,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -801,7 +801,7 @@ . + Closes the client object. [!INCLUDE[crdefault](~/includes/crdefault-md.md)]. ]]> @@ -833,7 +833,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -867,7 +867,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -899,7 +899,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -933,7 +933,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -962,7 +962,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -991,7 +991,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -1020,7 +1020,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> @@ -1049,7 +1049,7 @@ . + [!INCLUDE[crdefault](~/includes/crdefault-md.md)] . ]]> diff --git a/xml/System.ServiceModel/CommunicationException.xml b/xml/System.ServiceModel/CommunicationException.xml index 5d5f34e8081f1..7e1c079e94b0c 100644 --- a/xml/System.ServiceModel/CommunicationException.xml +++ b/xml/System.ServiceModel/CommunicationException.xml @@ -24,7 +24,7 @@ objects are thrown when a listener receives a SOAP fault that is not expected or specified in the operation contract. This usually occurs when the application is being debugged and the service has the property set to `true`. > [!NOTE] -> When implementing custom channels and binding elements, it is strongly recommended that your components throw only or -derived objects. In the case where your components throw a recoverable exception that is specific to the component, wrap that exception inside a object. +> When implementing custom channels and binding elements, it is strongly recommended that your components throw only or -derived objects. In the case where your components throw a recoverable exception that is specific to the component, wrap that exception inside a object. For more details about designing and using the [!INCLUDE[indigo2](~/includes/indigo2-md.md)] fault system, see [Specifying and Handling Faults in Contracts and Services](~/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md). diff --git a/xml/System.ServiceModel/CommunicationObjectAbortedException.xml b/xml/System.ServiceModel/CommunicationObjectAbortedException.xml index 7363e4ac7594c..249f901ff489a 100644 --- a/xml/System.ServiceModel/CommunicationObjectAbortedException.xml +++ b/xml/System.ServiceModel/CommunicationObjectAbortedException.xml @@ -17,7 +17,7 @@ is a derived class of and can occur in correct applications. Because typically the code that calls the method reports the error condition that caused the call to , this exception indicates that the call failed but the most useful error information is elsewhere. + is a derived class of and can occur in correct applications. Because typically the code that calls the method reports the error condition that caused the call to , this exception indicates that the call failed but the most useful error information is elsewhere. ]]> diff --git a/xml/System.ServiceModel/CommunicationObjectFaultedException.xml b/xml/System.ServiceModel/CommunicationObjectFaultedException.xml index 0ad93ab1a2573..fefb8a54c2db3 100644 --- a/xml/System.ServiceModel/CommunicationObjectFaultedException.xml +++ b/xml/System.ServiceModel/CommunicationObjectFaultedException.xml @@ -17,7 +17,7 @@ is thrown when a call is made to a faulted communication object. is a derived class of and can occur in correct applications. Because typically the code that calls the method reports the error condition that caused the call to , this exception indicates that the call failed but the most useful error information is elsewhere. + A is thrown when a call is made to a faulted communication object. is a derived class of and can occur in correct applications. Because typically the code that calls the method reports the error condition that caused the call to , this exception indicates that the call failed but the most useful error information is elsewhere. > [!NOTE] > If an object is faulted with several pending calls, only one call throws a specific exception; the others throw . diff --git a/xml/System.ServiceModel/DuplexClientBase`1.xml b/xml/System.ServiceModel/DuplexClientBase`1.xml index 80669aade1521..1f844464facfe 100644 --- a/xml/System.ServiceModel/DuplexClientBase`1.xml +++ b/xml/System.ServiceModel/DuplexClientBase`1.xml @@ -28,7 +28,7 @@ class to create a channel to a service that specifies a callback object. The object wraps a object, which provides the connectivity for the [!INCLUDE[indigo2](~/includes/indigo2-md.md)] object. You can use either type to connect to a duplex service. For more information about duplex services, see [Duplex Services](~/docs/framework/wcf/feature-details/duplex-services.md). + Use the class to create a channel to a service that specifies a callback object. The object wraps a object, which provides the connectivity for the [!INCLUDE[indigo2](~/includes/indigo2-md.md)] object. You can use either type to connect to a duplex service. For more information about duplex services, see [Duplex Services](~/docs/framework/wcf/feature-details/duplex-services.md). Special note for Managed C++ users deriving from this class: @@ -43,7 +43,7 @@ ## Examples - The following example shows the use in the client of a duplex [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client type, the `SampleDuplexHelloClient`, to pass a new object with the callback object to listen for callbacks. + The following example shows the use in the client of a duplex [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client type, the `SampleDuplexHelloClient`, to pass a new object with the callback object to listen for callbacks. [!code-csharp[CallbackBehaviorAttribute#3](~/samples/snippets/csharp/VS_Snippets_CFX/callbackbehaviorattribute/cs/client.cs#3)] [!code-vb[CallbackBehaviorAttribute#3](~/samples/snippets/visualbasic/VS_Snippets_CFX/callbackbehaviorattribute/vb/client.vb#3)] diff --git a/xml/System.ServiceModel/EndpointAddress.xml b/xml/System.ServiceModel/EndpointAddress.xml index c31e280b3701f..3be57322ce2d4 100644 --- a/xml/System.ServiceModel/EndpointAddress.xml +++ b/xml/System.ServiceModel/EndpointAddress.xml @@ -586,7 +586,7 @@ if the endpoint addresses are equivalent; otherwise, . - . + . ## Examples [!code-csharp[EndpointAddress#5](~/samples/snippets/csharp/VS_Snippets_CFX/endpointaddress/cs/snippets.cs#5)] @@ -619,7 +619,7 @@ if the endpoint addresses are not equivalent; otherwise, . - . + . ## Examples [!code-csharp[EndpointAddress#22](~/samples/snippets/csharp/VS_Snippets_CFX/endpointaddress/cs/snippets.cs#22)] diff --git a/xml/System.ServiceModel/ExceptionDetail.xml b/xml/System.ServiceModel/ExceptionDetail.xml index effb49ec3f962..13bdedeb985e9 100644 --- a/xml/System.ServiceModel/ExceptionDetail.xml +++ b/xml/System.ServiceModel/ExceptionDetail.xml @@ -22,7 +22,7 @@ class is the type parameter used as the fault detail object when a is sent by a service as a result of setting the or the property to `true`. + The class is the type parameter used as the fault detail object when a is sent by a service as a result of setting the or the property to `true`. To send a object the type must be serializable. For more information on serialization options, see [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md). diff --git a/xml/System.ServiceModel/ExtensionCollection`1.xml b/xml/System.ServiceModel/ExtensionCollection`1.xml index 8c92617d7ff29..a130bcc820286 100644 --- a/xml/System.ServiceModel/ExtensionCollection`1.xml +++ b/xml/System.ServiceModel/ExtensionCollection`1.xml @@ -38,7 +38,7 @@ return an from the property. + Typically, implementations of return an from the property. ]]> diff --git a/xml/System.ServiceModel/FaultContractAttribute.xml b/xml/System.ServiceModel/FaultContractAttribute.xml index bff6e30500a9b..026da94d5c2d4 100644 --- a/xml/System.ServiceModel/FaultContractAttribute.xml +++ b/xml/System.ServiceModel/FaultContractAttribute.xml @@ -39,18 +39,18 @@ > [!CAUTION] > If a fault message carries information that is sensitive or can lead to security problems, it is strongly recommended that the property be set. -- If you set the explicitly to either or , then you must use a binding with security enabled using the property on the binding or an exception is thrown. +- If you set the explicitly to either or , then you must use a binding with security enabled using the property on the binding or an exception is thrown. - If you select a binding that enables security and you do not set the property anywhere on the contract, all application data will be encrypted and signed. -- If you select a binding that does not have security enabled (for example, the has security disabled by default), and the is not explicitly set, then none of the application data will be protected. +- If you select a binding that does not have security enabled (for example, the has security disabled by default), and the is not explicitly set, then none of the application data will be protected. For many scenarios setting to for fault messages is sufficient. For more details, see [Understanding Protection Level](~/docs/framework/wcf/understanding-protection-level.md). To return a specified fault from an operation marked with , throw a (where the type parameter is the serializable error information) when the managed exception occurs during the operation. [!INCLUDE[indigo2](~/includes/indigo2-md.md)] client applications surface the SOAP fault as the same type as was thrown in the client implementation -- that is, as a (where the typeparameter is the serializable error information). The can be used only to specify SOAP faults for two-way service operations and for asynchronous operation pairs; one-way operations do not support SOAP faults and therefore do not support . > [!NOTE] -> You can use any serializable type to convey error information. The only restriction in this version of [!INCLUDE[indigo2](~/includes/indigo2-md.md)] is that types specified in a must be serializable by the . For the serialization support the provides, see [Data Contract Serializer](~/docs/framework/wcf/feature-details/data-contract-serializer.md). +> You can use any serializable type to convey error information. The only restriction in this version of [!INCLUDE[indigo2](~/includes/indigo2-md.md)] is that types specified in a must be serializable by the . For the serialization support the provides, see [Data Contract Serializer](~/docs/framework/wcf/feature-details/data-contract-serializer.md). For example, to specify that clients can expect a SOAP fault that contains an , place that type parameter in the on your service method. @@ -65,19 +65,19 @@ [!code-csharp[C_FCA#2](~/samples/snippets/csharp/VS_Snippets_CFX/c_fca/cs/fcademo.cs#2)] [!code-vb[C_FCA#2](~/samples/snippets/visualbasic/VS_Snippets_CFX/c_fca/vb/fcademo.vb#2)] - The preceding example is very basic; almost any information can be passed using an code, so this detail type is not the most useful. Typically, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] applications specify SOAP faults with detail types specific to the error information requirements of the client. For a more complete example, see the Example section. + The preceding example is very basic; almost any information can be passed using an code, so this detail type is not the most useful. Typically, [!INCLUDE[indigo2](~/includes/indigo2-md.md)] applications specify SOAP faults with detail types specific to the error information requirements of the client. For a more complete example, see the Example section. > [!NOTE] -> If you specify a where the type parameter is a , the string value is assigned to the Detail property in the client application; clients cannot retrieve that string by calling the method. To have the string value returned when the client application calls , throw a exception inside the operation and pass the string to the constructor. +> If you specify a where the type parameter is a , the string value is assigned to the Detail property in the client application; clients cannot retrieve that string by calling the method. To have the string value returned when the client application calls , throw a exception inside the operation and pass the string to the constructor. - To explicitly control the behavior of the application when an exception or is thrown, implement the interface on an , or and assign it to the property. enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client. + To explicitly control the behavior of the application when an exception or is thrown, implement the interface on an , or and assign it to the property. enables you to explicitly control the SOAP fault that is generated and whether to send it back to the client. - To facilitate debugging, set the to `true` in code or you can use the in an application configuration file. When enabled, the service automatically returns exception information to the caller. These faults appear to the client as exceptions. + To facilitate debugging, set the to `true` in code or you can use the in an application configuration file. When enabled, the service automatically returns exception information to the caller. These faults appear to the client as exceptions. > [!IMPORTANT] -> Because managed exceptions can expose internal application information, setting or to `true` can permit [!INCLUDE[indigo2](~/includes/indigo2-md.md)] clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. +> Because managed exceptions can expose internal application information, setting or to `true` can permit [!INCLUDE[indigo2](~/includes/indigo2-md.md)] clients to obtain information about internal service operation exceptions, including personally identifiable or other sensitive information. > -> Therefore, setting or to `true` is only recommended as a way of temporarily debugging a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to [!INCLUDE[indigo2](~/includes/indigo2-md.md)] clients as objects) to obtain the debugging information properly. +> Therefore, setting or to `true` is only recommended as a way of temporarily debugging a service application. In addition, the WSDL for a method that returns unhandled managed exceptions in this way does not contain the contract for the of type . Clients must expect the possibility of an unknown SOAP fault (returned to [!INCLUDE[indigo2](~/includes/indigo2-md.md)] clients as objects) to obtain the debugging information properly. @@ -271,27 +271,27 @@ property to specify the degree to which the binding must encrypt, sign, or both when sending the SOAP fault. It is strongly recommended that an operation's fault explicitly decide the security protection level requirements on the contract. The default protection level is , meaning that the SOAP fault message you are defining does not require encryption or a digital signature (although your binding may provide this support if it is configured to do so). If a fault message carries information that is sensitive or can lead to security problems, it is strongly recommended that the property be set to . For more about security issues, see [Understanding Protection Level](~/docs/framework/wcf/understanding-protection-level.md). + Use the property to specify the degree to which the binding must encrypt, sign, or both when sending the SOAP fault. It is strongly recommended that an operation's fault explicitly decide the security protection level requirements on the contract. The default protection level is , meaning that the SOAP fault message you are defining does not require encryption or a digital signature (although your binding may provide this support if it is configured to do so). If a fault message carries information that is sensitive or can lead to security problems, it is strongly recommended that the property be set to . For more about security issues, see [Understanding Protection Level](~/docs/framework/wcf/understanding-protection-level.md). The protection behavior at runtime is the combination of the protection-level properties that have a hierarchical structure. Setting the outermost value establishes the default setting for all narrower scopes unless a different value for a narrower scope is explicitly set. In this case, the outer value remains the default for all narrower scopes with the exception of that specifically set. - For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed, including fault messages. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed, including fault messages. + For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed, including fault messages. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed, including fault messages. The scopes at which these values are set are: - + - + - + - + - The property on . + The property on . - The property on . + The property on . - When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies . + When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies . ]]> diff --git a/xml/System.ServiceModel/FaultException.xml b/xml/System.ServiceModel/FaultException.xml index fc9663442f85d..079e742650a89 100644 --- a/xml/System.ServiceModel/FaultException.xml +++ b/xml/System.ServiceModel/FaultException.xml @@ -30,7 +30,7 @@ - To catch SOAP faults on a client when the faults are not part of the service contract. - Throw objects when you want the string to be passed to the constructor and retrieved by the client by calling the method. If you specify a fault contract of type where the type parameter is , the string value is available as the property and not by calling . + Throw objects when you want the string to be passed to the constructor and retrieved by the client by calling the method. If you specify a fault contract of type where the type parameter is , the string value is available as the property and not by calling . For details, see [Specifying and Handling Faults in Contracts and Services](~/docs/framework/wcf/specifying-and-handling-faults-in-contracts-and-services.md). @@ -319,7 +319,7 @@ is returned where the type parameter is the matching candidate type. + The `faultDetailTypes` parameter contains candidate detail types. If any of the `faultDetailTypes` has a schema that matches the `messageFault` parameter, a is returned where the type parameter is the matching candidate type. ]]> @@ -359,7 +359,7 @@ is returned where the type parameter is the matching candidate type. + The `faultDetailTypes` parameter contains candidate detail types. If any of the `faultDetailTypes` has a schema that matches the `messageFault` parameter, a is returned where the type parameter is the matching candidate type. ]]> diff --git a/xml/System.ServiceModel/FaultException`1.xml b/xml/System.ServiceModel/FaultException`1.xml index 2265bce9ef1a8..ff03620aaf1a5 100644 --- a/xml/System.ServiceModel/FaultException`1.xml +++ b/xml/System.ServiceModel/FaultException`1.xml @@ -28,8 +28,8 @@ Because is both a and therefore a , to catch specified SOAP faults make sure you catch the types prior to the and types or handle the specified exceptions in one of those exception handlers. > [!NOTE] -> If you use to specify a where the type parameter is a , the string value is assigned to the property in the client application; clients cannot retrieve that string by calling the method. To have the string value returned when the client application calls , throw a exception inside the operation and pass the string to the constructor. -> In general, it is recommended that detail types be custom serializable types appropriate to the fault and not a . +> If you use to specify a where the type parameter is a , the string value is assigned to the property in the client application; clients cannot retrieve that string by calling the method. To have the string value returned when the client application calls , throw a exception inside the operation and pass the string to the constructor. +> In general, it is recommended that detail types be custom serializable types appropriate to the fault and not a . diff --git a/xml/System.ServiceModel/FaultReason.xml b/xml/System.ServiceModel/FaultReason.xml index b81f82a53f631..3c81f5ef66ea0 100644 --- a/xml/System.ServiceModel/FaultReason.xml +++ b/xml/System.ServiceModel/FaultReason.xml @@ -17,7 +17,7 @@ class contains a set of objects, each of which contains a description of the fault in a specific language. + The class contains a set of objects, each of which contains a description of the fault in a specific language. ]]> @@ -109,9 +109,9 @@ - If only one translation exists, it is returned. -- If there is an exact match for a , that is returned. +- If there is an exact match for a , that is returned. -- If there is a translation for a parent language of , that is returned. +- If there is a translation for a parent language of , that is returned. - Otherwise, the first translation in the set is returned. @@ -147,9 +147,9 @@ - If only one translation exists, it is returned. -- If there is an exact match for a , that is returned. +- If there is an exact match for a , that is returned. -- If there is a translation for a parent language of , that is returned. +- If there is a translation for a parent language of , that is returned. - Otherwise, the first translation in the set is returned. diff --git a/xml/System.ServiceModel/IClientChannel.xml b/xml/System.ServiceModel/IClientChannel.xml index 1684c4224ee12..1a3bf43bc9e63 100644 --- a/xml/System.ServiceModel/IClientChannel.xml +++ b/xml/System.ServiceModel/IClientChannel.xml @@ -24,7 +24,7 @@ interface defines the operations supported by all channels returned by a call to . Use the methods and properties to inspect and modify the outbound typed channel. The [ServiceModel Metadata Utility Tool (Svcutil.exe)](~/docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) exports both a class and a service contract interface by creating a contract interface that inherits from both the target service contract and , enabling you to use the extended contract as both the proxy to the service and to access the client channel. + The interface defines the operations supported by all channels returned by a call to . Use the methods and properties to inspect and modify the outbound typed channel. The [ServiceModel Metadata Utility Tool (Svcutil.exe)](~/docs/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe.md) exports both a class and a service contract interface by creating a contract interface that inherits from both the target service contract and , enabling you to use the extended contract as both the proxy to the service and to access the client channel. For more information, see [WCF Client Architecture](~/docs/framework/wcf/feature-details/client-architecture.md). For examples of its appearance in generated client code files, see [Understanding Generated Client Code](~/docs/framework/wcf/feature-details/understanding-generated-client-code.md). @@ -53,7 +53,7 @@ . + Set this to `false` if you want to throw an exception rather than display an initialization dialog. This is useful in a middle-tier scenario in which you want to guarantee that no dialog appears even if the application is configured to display one. For details, see [Accessing Services Using a WCF Client](~/docs/framework/wcf/feature-details/accessing-services-using-a-client.md) and . ]]> @@ -85,7 +85,7 @@ , so for many applications this call is optional. + Call this method to cause any interactive channel initialization (for example, CardSpace card selection) to occur. This happens automatically if the channel is used without explicitly calling , so for many applications this call is optional. However, if the user takes a long time in the selection process, the operation that automatically called this may time out. To prevent this, call or and explicitly. These operations do not time out and allow you to control exactly where in your application this dialog comes up. @@ -118,7 +118,7 @@ without calling and , these methods are called automatically. For details, see [Accessing Services Using a WCF Client](~/docs/framework/wcf/feature-details/accessing-services-using-a-client.md) and . + If operations are called on an without calling and , these methods are called automatically. For details, see [Accessing Services Using a WCF Client](~/docs/framework/wcf/feature-details/accessing-services-using-a-client.md) and . ]]> @@ -144,7 +144,7 @@ , so for many applications this call is optional. + Call this method to cause any interactive channel initialization (for example, CardSpace card selection) to occur. This happens automatically if the channel is used without explicitly calling , so for many applications this call is optional. However, if the user takes a long time in the selection process, the operation that automatically called this may time out. To prevent this, call or and explicitly. These operations do not time out and allow you to control exactly where in your application this dialog comes up. @@ -152,7 +152,7 @@ If you call this method explicitly, you must also explicitly open the channel before using it. - For details, see [Accessing Services Using a WCF Client](~/docs/framework/wcf/feature-details/accessing-services-using-a-client.md) and . + For details, see [Accessing Services Using a WCF Client](~/docs/framework/wcf/feature-details/accessing-services-using-a-client.md) and . ]]> @@ -218,7 +218,7 @@ serves as both the ultimate destination and the physical address if a is not specified. If the is specified, then that is the actual physical address to which the message is sent and through which the message must go to arrive at its destination. This value can be set from a configuration file using the . + The serves as both the ultimate destination and the physical address if a is not specified. If the is specified, then that is the actual physical address to which the message is sent and through which the message must go to arrive at its destination. This value can be set from a configuration file using the . ]]> diff --git a/xml/System.ServiceModel/IExtensibleObject`1.xml b/xml/System.ServiceModel/IExtensibleObject`1.xml index e747c911b1ca6..8e008a02a9792 100644 --- a/xml/System.ServiceModel/IExtensibleObject`1.xml +++ b/xml/System.ServiceModel/IExtensibleObject`1.xml @@ -28,13 +28,13 @@ There are four extensible objects in [!INCLUDE[indigo1](~/includes/indigo1-md.md)]: -- +- -- +- -- +- -- +- For a discussion about how to create extension to work with these objects, see [Extensible Objects](~/docs/framework/wcf/extending/extensible-objects.md). diff --git a/xml/System.ServiceModel/IExtensionCollection`1.xml b/xml/System.ServiceModel/IExtensionCollection`1.xml index 652649cbcffc8..87b17b2d4164d 100644 --- a/xml/System.ServiceModel/IExtensionCollection`1.xml +++ b/xml/System.ServiceModel/IExtensionCollection`1.xml @@ -53,7 +53,7 @@ returns an extension that implements (is or derives from) the specified type. If more than one extension implements the specified type, one is returned. The [!INCLUDE[indigo2](~/includes/indigo2-md.md)] implementation returns the most recently added, but this is not required of implementations. If no extension implements the specified type, returns null. + returns an extension that implements (is or derives from) the specified type. If more than one extension implements the specified type, one is returned. The [!INCLUDE[indigo2](~/includes/indigo2-md.md)] implementation returns the most recently added, but this is not required of implementations. If no extension implements the specified type, returns null. ]]> diff --git a/xml/System.ServiceModel/IExtension`1.xml b/xml/System.ServiceModel/IExtension`1.xml index c2e5abc04ecd7..067f30ef6099f 100644 --- a/xml/System.ServiceModel/IExtension`1.xml +++ b/xml/System.ServiceModel/IExtension`1.xml @@ -22,7 +22,7 @@ objects (the , , , and classes) by adding a new state or behavior by using its extensible object pattern. The extensible object pattern is used in [!INCLUDE[indigo2](~/includes/indigo2-md.md)] to either extend existing run-time classes with new functionality or to add new state features to an object. + [!INCLUDE[indigo2](~/includes/indigo2-md.md)] allows you to extend objects (the , , , and classes) by adding a new state or behavior by using its extensible object pattern. The extensible object pattern is used in [!INCLUDE[indigo2](~/includes/indigo2-md.md)] to either extend existing run-time classes with new functionality or to add new state features to an object. ]]> @@ -94,9 +94,9 @@ public void Attach(InstanceContext owner) method to find out when the extension has been removed. An extension can use this to unhook events on the extensible object. An extension can also throw from this method to indicate that, once added, the extension cannot be removed. + Use the method to find out when the extension has been removed. An extension can use this to unhook events on the extensible object. An extension can also throw from this method to indicate that, once added, the extension cannot be removed. - Note that this method is not called when the owner object is disposed or closed. If needed, it is up to the extension or the code adding the extension to hook the appropriate events or implement the appropriate interfaces (for ) to observe the lifecycle of the owner. + Note that this method is not called when the owner object is disposed or closed. If needed, it is up to the extension or the code adding the extension to hook the appropriate events or implement the appropriate interfaces (for ) to observe the lifecycle of the owner. ]]> diff --git a/xml/System.ServiceModel/InstanceContextMode.xml b/xml/System.ServiceModel/InstanceContextMode.xml index 73b4a2cca55bf..ab57432e52e12 100644 --- a/xml/System.ServiceModel/InstanceContextMode.xml +++ b/xml/System.ServiceModel/InstanceContextMode.xml @@ -16,7 +16,7 @@ manages the association between the channel and the user-defined service objects. Use the enumeration with the property to specify the lifetime of the object. [!INCLUDE[indigo1](~/includes/indigo1-md.md)] can create a new object for every call, every session or specify that the object is bound to a single service object. For a working example, see the [Instancing](~/docs/framework/wcf/samples/instancing.md). + The manages the association between the channel and the user-defined service objects. Use the enumeration with the property to specify the lifetime of the object. [!INCLUDE[indigo1](~/includes/indigo1-md.md)] can create a new object for every call, every session or specify that the object is bound to a single service object. For a working example, see the [Instancing](~/docs/framework/wcf/samples/instancing.md). The Single value specifies that a single object should be used for the lifetime of the service. diff --git a/xml/System.ServiceModel/InvalidMessageContractException.xml b/xml/System.ServiceModel/InvalidMessageContractException.xml index 4ed440da9fbb0..3324d785cbcbc 100644 --- a/xml/System.ServiceModel/InvalidMessageContractException.xml +++ b/xml/System.ServiceModel/InvalidMessageContractException.xml @@ -17,7 +17,7 @@ is thrown when custom attribute usage results in the generation of an invalid service description. For example, if a type has multiple parts with the same name, or a method has multiple parameters with the same name. + The is thrown when custom attribute usage results in the generation of an invalid service description. For example, if a type has multiple parts with the same name, or a method has multiple parameters with the same name. diff --git a/xml/System.ServiceModel/MessageBodyMemberAttribute.xml b/xml/System.ServiceModel/MessageBodyMemberAttribute.xml index d5eb57cc67732..a4d38c595ed08 100644 --- a/xml/System.ServiceModel/MessageBodyMemberAttribute.xml +++ b/xml/System.ServiceModel/MessageBodyMemberAttribute.xml @@ -26,9 +26,9 @@ The property is used to specify the order of body parts in cases where the default alphabetical order is not appropriate. - The other properties are inherited from the base class, . + The other properties are inherited from the base class, . - [!INCLUDE[crabout](~/includes/crabout-md.md)] controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). + [!INCLUDE[crabout](~/includes/crabout-md.md)] controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). [!INCLUDE[crdefault](~/includes/crdefault-md.md)] [Using Message Contracts](~/docs/framework/wcf/feature-details/using-message-contracts.md). diff --git a/xml/System.ServiceModel/MessageContractAttribute.xml b/xml/System.ServiceModel/MessageContractAttribute.xml index 01db451b04a1a..99c42c0ddb69c 100644 --- a/xml/System.ServiceModel/MessageContractAttribute.xml +++ b/xml/System.ServiceModel/MessageContractAttribute.xml @@ -22,7 +22,7 @@ attribute to specify the structure of the SOAP envelope for a particular message. Your service can then use the message as a parameter or return type in service operations. For information about controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). + Use the attribute to specify the structure of the SOAP envelope for a particular message. Your service can then use the message as a parameter or return type in service operations. For information about controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). > [!NOTE] > You cannot use custom message types in your service operation with regular serializable parameters. Either use custom message types or serializable parameters that are not objects. For details, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md). @@ -30,7 +30,7 @@ To implement a message contract for a type, annotate it with and annotate one or more of the class's fields or properties with , , or . > [!NOTE] -> is not a message contract attribute and cannot be used in conjunction with . +> is not a message contract attribute and cannot be used in conjunction with . Use the and properties to specify the value of the `` element in the SOAP message. diff --git a/xml/System.ServiceModel/MessageContractMemberAttribute.xml b/xml/System.ServiceModel/MessageContractMemberAttribute.xml index 6c86cc78e4551..5599011d49b52 100644 --- a/xml/System.ServiceModel/MessageContractMemberAttribute.xml +++ b/xml/System.ServiceModel/MessageContractMemberAttribute.xml @@ -19,7 +19,7 @@ ## Remarks This class contains properties common to all parts of a SOAP message. For example, all parts have a name and a namespace, and potentially a level of security applied. - For information on controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). + For information on controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). For more information about creating message contracts, see [Using Message Contracts](~/docs/framework/wcf/feature-details/using-message-contracts.md). @@ -187,7 +187,7 @@ public class BankingTransaction property in either the or attributes you must properly configure the binding and behaviors. If these security features are used without a proper configuration (for example, using with a message part without supplying security credentials) an exception is thrown at run time. + To make use of the property in either the or attributes you must properly configure the binding and behaviors. If these security features are used without a proper configuration (for example, using with a message part without supplying security credentials) an exception is thrown at run time. In addition, the protection level is determined for each header individually. However, the SOAP body has only one protection level, regardless of the number of body parts. The protection level of the body is determined by the highest property value of all the body parts. For example, consider the following class: @@ -204,29 +204,29 @@ public class PatientRecord } ``` - In this example, the `recordID` header is not protected, `patientName` is signed, and `SSN` is encrypted and signed. There is at least one body part, `medicalHistory`, with and thus the entire message body is encrypted and signed, even though the `comments` and `diagnosis` body parts specify lower protection levels. + In this example, the `recordID` header is not protected, `patientName` is signed, and `SSN` is encrypted and signed. There is at least one body part, `medicalHistory`, with and thus the entire message body is encrypted and signed, even though the `comments` and `diagnosis` body parts specify lower protection levels. The protection behavior at runtime is the combination of the protection-level values set on the following properties. These properties have a hierarchical structure. Setting the outermost value establishes the default setting for all narrower scopes unless a different value for a narrower scope is explicitly set. In this case, the outer value remains the default for all narrower scopes with the exception of that specifically set. - For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed. + For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed. For details about protection levels and their assumptions and scopes, see [Understanding Protection Level](~/docs/framework/wcf/understanding-protection-level.md). The scopes at which these values are set are: - + - + - + - + - The property on . + The property on . - The property on . + The property on . - When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies . + When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies . ]]> diff --git a/xml/System.ServiceModel/MessageHeaderArrayAttribute.xml b/xml/System.ServiceModel/MessageHeaderArrayAttribute.xml index 15ef24063134f..39db2c9fdfc39 100644 --- a/xml/System.ServiceModel/MessageHeaderArrayAttribute.xml +++ b/xml/System.ServiceModel/MessageHeaderArrayAttribute.xml @@ -26,7 +26,7 @@ can be applied only to members of an array type. If specified, the and are used as the name and namespace of the element of each array item. If not specified, the array item elements are named using the same convention used for naming non-repeating body parts. For more information, see and . - For information about controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). + For information about controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). For more information about creating message contracts, see [Using Message Contracts](~/docs/framework/wcf/feature-details/using-message-contracts.md). diff --git a/xml/System.ServiceModel/MessageHeaderAttribute.xml b/xml/System.ServiceModel/MessageHeaderAttribute.xml index e6828de0b860b..ed52fdd0a7367 100644 --- a/xml/System.ServiceModel/MessageHeaderAttribute.xml +++ b/xml/System.ServiceModel/MessageHeaderAttribute.xml @@ -24,7 +24,7 @@ ## Remarks The attribute allows you to map fields and properties of a type marked with the attribute to SOAP message headers. The field or property can be of a simple type or a composite type that can be serialized. - For information on controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). + For information on controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). For more information about creating message contracts, see [Using Message Contracts](~/docs/framework/wcf/feature-details/using-message-contracts.md). diff --git a/xml/System.ServiceModel/MessageParameterAttribute.xml b/xml/System.ServiceModel/MessageParameterAttribute.xml index bbe7838c0c7c5..3890815ed2594 100644 --- a/xml/System.ServiceModel/MessageParameterAttribute.xml +++ b/xml/System.ServiceModel/MessageParameterAttribute.xml @@ -27,7 +27,7 @@ > [!NOTE] > The value of the parameter names in the operation signature are part of the contract and are case sensitive. Use this attribute when you need to distinguish between the local parameter name and the metadata that describes the operation for client applications. - [!INCLUDE[crabout](~/includes/crabout-md.md)] controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). + [!INCLUDE[crabout](~/includes/crabout-md.md)] controlling the serialization of the contents of a SOAP body without modifying the default SOAP envelope itself, see , [Specifying Data Transfer in Service Contracts](~/docs/framework/wcf/feature-details/specifying-data-transfer-in-service-contracts.md), and [Using Data Contracts](~/docs/framework/wcf/feature-details/using-data-contracts.md). [!INCLUDE[crabout](~/includes/crabout-md.md)] creating message contracts, see [Using Message Contracts](~/docs/framework/wcf/feature-details/using-message-contracts.md). diff --git a/xml/System.ServiceModel/NetTcpBinding.xml b/xml/System.ServiceModel/NetTcpBinding.xml index 1cea10ff756ac..4844c3b3c965f 100644 --- a/xml/System.ServiceModel/NetTcpBinding.xml +++ b/xml/System.ServiceModel/NetTcpBinding.xml @@ -107,7 +107,7 @@ . + Use this constructor when you want to configure the security. If you want to configure security and enable reliable sessions, use . diff --git a/xml/System.ServiceModel/OperationBehaviorAttribute.xml b/xml/System.ServiceModel/OperationBehaviorAttribute.xml index 3a03e3ad67db9..5d7b4ea7716b8 100644 --- a/xml/System.ServiceModel/OperationBehaviorAttribute.xml +++ b/xml/System.ServiceModel/OperationBehaviorAttribute.xml @@ -131,10 +131,10 @@ property (together with a binding configuration that supports impersonation) to enable specified methods (those marked with the property set to or ) to execute under the caller's identity. For details, including how impersonation is performed when using together with the property, see [Delegation and Impersonation](~/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md) and [How to: Impersonate a Client on a Service](~/docs/framework/wcf/how-to-impersonate-a-client-on-a-service.md). + Use the property (together with a binding configuration that supports impersonation) to enable specified methods (those marked with the property set to or ) to execute under the caller's identity. For details, including how impersonation is performed when using together with the property, see [Delegation and Impersonation](~/docs/framework/wcf/feature-details/delegation-and-impersonation-with-wcf.md) and [How to: Impersonate a Client on a Service](~/docs/framework/wcf/how-to-impersonate-a-client-on-a-service.md). > [!NOTE] -> When programmatically adding a service endpoint that performs impersonation, you must either use one of the methods or the method to properly load the contract into a new object. Using a configuration file requires no extra step. +> When programmatically adding a service endpoint that performs impersonation, you must either use one of the methods or the method to properly load the contract into a new object. Using a configuration file requires no extra step. There may be specific scenarios when impersonation is not supported. [!INCLUDE[crdefault](~/includes/crdefault-md.md)][Unsupported Scenarios](~/docs/framework/wcf/feature-details/unsupported-scenarios.md). @@ -192,7 +192,7 @@ You can also use to configure a callback contract operation in a duplex client application. When used on a callback operation, the property must be or an exception is thrown at runtime. - In addition, it is important to realize that if the service is created by passing a service object to the constructor, the value of this property is treated as if it were . + In addition, it is important to realize that if the service is created by passing a service object to the constructor, the value of this property is treated as if it were . diff --git a/xml/System.ServiceModel/OperationContext.xml b/xml/System.ServiceModel/OperationContext.xml index 0e1fa936e24dd..d8a13678eeb10 100644 --- a/xml/System.ServiceModel/OperationContext.xml +++ b/xml/System.ServiceModel/OperationContext.xml @@ -31,7 +31,7 @@ - The property returns the security environment under which the method executes. -- The property gets the operation's . +- The property gets the operation's . - The property returns an extension collection for the current . @@ -459,12 +459,12 @@ event to dispose parameters or a return value if you set to `false`. Normally you set to `false` to prevent [!INCLUDE[indigo2](~/includes/indigo2-md.md)] from calling on the parameter and return value objects. However, if some parameters need to be preserved while others need to be disposed, this event is the best place to dispose those parameters. + Use the event to dispose parameters or a return value if you set to `false`. Normally you set to `false` to prevent [!INCLUDE[indigo2](~/includes/indigo2-md.md)] from calling on the parameter and return value objects. However, if some parameters need to be preserved while others need to be disposed, this event is the best place to dispose those parameters. Also, with duplex bindings, this event can be used to send a request on the callback channel after the reply for the current operation is sent. > [!NOTE] -> If a caller is listening for the event for an operation, it is possible to block when the response is received. The proper way to handle this is to schedule work on another thread when is raised and then immediately return from that event handler. +> If a caller is listening for the event for an operation, it is possible to block when the response is received. The proper way to handle this is to schedule work on another thread when is raised and then immediately return from that event handler. ]]> @@ -612,7 +612,7 @@ to `false`. Typically, services do this on some but not all operations. When is false the transaction completes automatically. Use in cases where it is not possible to determine at design-time whether an operation needs to complete the transaction. + This is only useful in operations that set to `false`. Typically, services do this on some but not all operations. When is false the transaction completes automatically. Use in cases where it is not possible to determine at design-time whether an operation needs to complete the transaction. ]]> diff --git a/xml/System.ServiceModel/OperationContextScope.xml b/xml/System.ServiceModel/OperationContextScope.xml index a7717d8f2e50f..b6903270cac36 100644 --- a/xml/System.ServiceModel/OperationContextScope.xml +++ b/xml/System.ServiceModel/OperationContextScope.xml @@ -31,7 +31,7 @@ - Access other types of contexts, such as security, instance, and request contexts. -- Access the channel associated with the object or (if the channel implements ) the associated channel's session identifier. +- Access the channel associated with the object or (if the channel implements ) the associated channel's session identifier. When an is created, the current is stored and the new becomes the one returned by the property. When the is disposed, the original is restored. @@ -72,7 +72,7 @@ ## Remarks Use the constructor to create a new for a client channel that can be used to add or modify outbound message headers, read incoming message headers, or access other run-time properties of the . - The headers added to the property of the newly created apply only to the channel that was passed to the constructor. If the user creates a new channel within its scope then the headers are not applied to messages sent on the new channel. + The headers added to the property of the newly created apply only to the channel that was passed to the constructor. If the user creates a new channel within its scope then the headers are not applied to messages sent on the new channel. diff --git a/xml/System.ServiceModel/OperationContractAttribute.xml b/xml/System.ServiceModel/OperationContractAttribute.xml index 7a78048578125..42f725d31deea 100644 --- a/xml/System.ServiceModel/OperationContractAttribute.xml +++ b/xml/System.ServiceModel/OperationContractAttribute.xml @@ -278,7 +278,7 @@ public interface IAddTwoNumbers The property controls whether an operation can be the first operation called when a session is created. > [!NOTE] -> The value of must be either or and the binding used must require or allow sessions for the property to work properly. +> The value of must be either or and the binding used must require or allow sessions for the property to work properly. The default is `true`, which means that an operation can be the first one called on a channel. Subsequent calls to the initiating method have no effect, other than to call the method. No other sessions are created. If the contract does not make use of a session, setting to `false` is ignored. @@ -287,7 +287,7 @@ public interface IAddTwoNumbers > [!NOTE] > There is an interaction between and the property. A service contract can have only one service operation with the property set to "*". Any group of service contracts hosted at the same listen URI that a service class implements can have many service operations with the property set to "\*" when the property is set to `false`. However, only one of those service methods can have the property set to "\*" and the property set to `true`. - If a service receives a message for a non-initiating operation, the service returns an ActionNotSupported SOAP fault. The client experiences this as an . If a client calls a non-initiating operation first, the client runtime throws an . + If a service receives a message for a non-initiating operation, the service returns an ActionNotSupported SOAP fault. The client experiences this as an . If a client calls a non-initiating operation first, the client runtime throws an . For more information, see [Using Sessions](~/docs/framework/wcf/using-sessions.md). @@ -363,7 +363,7 @@ public class InitializeAndTerminateService If the property is set to `false` (the default), even methods that return `void` result in a reply message. In this case, the infrastructure creates and sends an empty message to indicate to the caller that the method has returned. (Using this approach enables the infrastructure to send SOAP faults back to the client.) Setting to `true` is the only way to cancel the creation and dispatch of a response message. - One-way methods must not return a value or have `ref` or `out` parameters; otherwise a exception is thrown. + One-way methods must not return a value or have `ref` or `out` parameters; otherwise a exception is thrown. Specifying that an operation is a one-way operation means only that there is no response message. It is possible to block if a connection cannot be made, or the outbound message is very large, or if the service cannot read inbound information fast enough. If a client requires a non-blocking call, generate operations. For more information, see [One-Way Services](~/docs/framework/wcf/feature-details/one-way-services.md) and [Accessing Services Using a WCF Client](~/docs/framework/wcf/feature-details/accessing-services-using-a-client.md). @@ -436,7 +436,7 @@ public class OneAndTwoWay For more information about using this property with sessions, see [Using Sessions](~/docs/framework/wcf/using-sessions.md). > [!NOTE] -> If a caller is listening for the event for an operation, it is possible to block when the response is received. The proper way to handle this is to schedule work on another thread when is raised and then immediately return from that event handler. +> If a caller is listening for the event for an operation, it is possible to block when the response is received. The proper way to handle this is to schedule work on another thread when is raised and then immediately return from that event handler. @@ -544,25 +544,25 @@ public class InitializeAndTerminateService It is important to remember that the protection behavior at runtime is the combination of the protection-level values set on the following properties. These properties have a hierarchical structure. Setting the outermost value establishes the default setting for all narrower scopes unless a different value for a narrower scope is explicitly set. In this case, the outer value remains the default for all narrower scopes with the exception of that specifically set. - For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed. + For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed. For details about protection levels and their assumptions and scopes, see [Understanding Protection Level](~/docs/framework/wcf/understanding-protection-level.md). The scopes at which these values are set are: - + - + - + - + - The property on . + The property on . - The property on . + The property on . - When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies . + When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies . ]]> diff --git a/xml/System.ServiceModel/OperationFormatStyle.xml b/xml/System.ServiceModel/OperationFormatStyle.xml index ecabb2a532585..65b5b65f6fe96 100644 --- a/xml/System.ServiceModel/OperationFormatStyle.xml +++ b/xml/System.ServiceModel/OperationFormatStyle.xml @@ -34,7 +34,7 @@ ``` - Use the to set this value. + Use the to set this value. diff --git a/xml/System.ServiceModel/OperationFormatUse.xml b/xml/System.ServiceModel/OperationFormatUse.xml index f581125ee26c0..39c06a05d7488 100644 --- a/xml/System.ServiceModel/OperationFormatUse.xml +++ b/xml/System.ServiceModel/OperationFormatUse.xml @@ -34,7 +34,7 @@ ``` - Use the to set this value. + Use the to set this value. diff --git a/xml/System.ServiceModel/ServiceBehaviorAttribute.xml b/xml/System.ServiceModel/ServiceBehaviorAttribute.xml index d1c4c335890af..eebee999b718b 100644 --- a/xml/System.ServiceModel/ServiceBehaviorAttribute.xml +++ b/xml/System.ServiceModel/ServiceBehaviorAttribute.xml @@ -219,7 +219,7 @@ This property indicates whether an instance of a service can handle one thread or multiple threads that execute concurrently, and if single-threaded, whether reentrancy is supported. > [!NOTE] -> The property interacts with some other settings. For example, if the value is set to the result is that your service can only process one message at a time unless you also set the value to . This property also produces behavior in combination with the property. For details, see [Sessions, Instancing, and Concurrency](~/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). +> The property interacts with some other settings. For example, if the value is set to the result is that your service can only process one message at a time unless you also set the value to . This property also produces behavior in combination with the property. For details, see [Sessions, Instancing, and Concurrency](~/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). Setting to instructs the system to restrict instances of the service to one thread of execution at a time, which frees you from dealing with threading issues. A value of means that service objects can be executed by multiple threads at any one time. In this case, you must ensure thread safety. @@ -257,7 +257,7 @@ public void MyMethod() > [!NOTE] > A is thrown at runtime if is `true` when the property is set to . - Note that you must explicitly set to `false` if there is an operation with set to true and you set to . Otherwise a validation exception is thrown because the default value of is `true`. + Note that you must explicitly set to `false` if there is an operation with set to true and you set to . Otherwise a validation exception is thrown because the default value of is `true`. There is an interaction of the and other properties that can alter runtime behavior. For a complete description of these interactions, see [Sessions, Instancing, and Concurrency](~/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). @@ -489,7 +489,7 @@ public void MyMethod() indicates that each service object handles requests from one client channel. > [!NOTE] -> The property interacts with some other settings. For example, if the value is set to the result is that your service can only process one message at a time unless you also set the value to . This property also produces behavior in combination with the property. For details, see [Sessions, Instancing, and Concurrency](~/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). +> The property interacts with some other settings. For example, if the value is set to the result is that your service can only process one message at a time unless you also set the value to . This property also produces behavior in combination with the property. For details, see [Sessions, Instancing, and Concurrency](~/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). For singleton lifetime behavior (for example, if the host application calls the constructor and passes an object to use as the service), the service class must set to `Single`, or an exception is thrown at run time. @@ -614,9 +614,9 @@ public void MyMethod() to `false` if there is an operation with set to true and you set to . Otherwise a validation exception is thrown because the default value of is `true`. + Note that you must explicitly set to `false` if there is an operation with set to true and you set to . Otherwise a validation exception is thrown because the default value of is `true`. - In addition, it is important to realize that if the service is created by passing a service object to the constructor, the value of this property is treated as if it were `false`. + In addition, it is important to realize that if the service is created by passing a service object to the constructor, the value of this property is treated as if it were `false`. @@ -916,7 +916,7 @@ public void MyMethod() property. You can also set this property using the [<serviceTimeouts>](~/docs/framework/configure-apps/file-schema/wcf/servicetimeouts.md) element in an application configuration file. + This value sets the property. You can also set this property using the [<serviceTimeouts>](~/docs/framework/configure-apps/file-schema/wcf/servicetimeouts.md) element in an application configuration file. @@ -957,7 +957,7 @@ public void MyMethod() is set to `true`, synchronizes all calls to the service to run on the thread captured from the . + Use this property to provide the user interface thread affinity that some applications require. For example, a Windows Forms application may be registered as a singleton service object. In this case, all calls into the service must run on the Windows Forms thread. The default case, in which is set to `true`, synchronizes all calls to the service to run on the thread captured from the . ]]> diff --git a/xml/System.ServiceModel/ServiceContractAttribute.xml b/xml/System.ServiceModel/ServiceContractAttribute.xml index 337f915503879..d1ab88f7569bf 100644 --- a/xml/System.ServiceModel/ServiceContractAttribute.xml +++ b/xml/System.ServiceModel/ServiceContractAttribute.xml @@ -43,7 +43,7 @@ Services implement service contracts, which represent the data exchange that a service type supports. A service class can implement a service contract (by implementing an interface marked with that has methods marked with ) or it can be marked with the and apply the attribute to its own methods. (If a class implements an interface marked with , it cannot be itself marked with .) Methods on service types that are marked with the are treated as part of a default service contract specified by the service type itself. For details about service operations, see . - By default, the and properties are the name of the contract type and `http://tempuri.org`, respectively, and is . It is recommended that service contracts explicitly set their names, namespaces, and protection levels using these properties. Doing so accomplishes two goals. First, it builds a contract that is not directly connected to the managed type information, enabling you to refactor your managed code and namespaces without breaking the contract as it is expressed in WSDL. Second, explicitly requiring a certain level of protection on the contract itself enables the runtime to validate whether the binding configuration supports that level of security, preventing poor configuration from exposing sensitive information. For more information about protection levels, see [Understanding Protection Level](~/docs/framework/wcf/understanding-protection-level.md). + By default, the and properties are the name of the contract type and `http://tempuri.org`, respectively, and is . It is recommended that service contracts explicitly set their names, namespaces, and protection levels using these properties. Doing so accomplishes two goals. First, it builds a contract that is not directly connected to the managed type information, enabling you to refactor your managed code and namespaces without breaking the contract as it is expressed in WSDL. Second, explicitly requiring a certain level of protection on the contract itself enables the runtime to validate whether the binding configuration supports that level of security, preventing poor configuration from exposing sensitive information. For more information about protection levels, see [Understanding Protection Level](~/docs/framework/wcf/understanding-protection-level.md). To expose a service for use by client applications, create a host application to register your service endpoint with [!INCLUDE[indigo1](~/includes/indigo1-md.md)]. You can host [!INCLUDE[indigo2](~/includes/indigo2-md.md)] services using Windows Activation Services (WAS), in console applications, Windows Service applications, ASP.NET applications, Windows Forms applications, or any other kind of application domain. @@ -60,7 +60,7 @@ ## Examples - The following code example shows how to apply the to an interface to define a service contract with one service method, indicated by the . In this case, the protection level required of bindings for all messages is . + The following code example shows how to apply the to an interface to define a service contract with one service method, indicated by the . In this case, the protection level required of bindings for all messages is . The code example then implements that contract on the `SampleService` class. @@ -126,7 +126,7 @@ Specify an interface in the property that represents the required opposite contract in a two-way (or duplex) message exchange. This enables client applications to listen for inbound operation calls that the server-side service application can send independently of client activity. Callback contracts that have one-way operations represent calls from the service that the client can handle. > [!NOTE] -> The attribute is ignored on callback contracts. To configure runtime behavior of callback objects, use the . +> The attribute is ignored on callback contracts. To configure runtime behavior of callback objects, use the . @@ -294,25 +294,25 @@ It is important to remember that the protection behavior at runtime is the combination of the protection-level values set on the following properties. These properties have a hierarchical structure. Setting the outermost value establishes the default setting for all narrower scopes unless a different value for a narrower scope is explicitly set. In this case, the outer value remains the default for all narrower scopes with the exception of that specifically set. - For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed. + For example, if is set to and no other narrower scopes have protection level settings, all messages in an operation contract are encrypted and signed. If, however, one of those operations has the set to , then the messages for that operation are signed but all other messages in the contract are encrypted and signed. For details about protection levels and their assumptions and scopes, see [Understanding Protection Level](~/docs/framework/wcf/understanding-protection-level.md). The scopes at which these values are set are: - + - + - + - + - The property on . + The property on . - The property on . + The property on . - When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies . + When there is no protection level explicitly specified on the contract and the underlying binding supports security (whether at the transport or message level), the effective protection level for the whole contract is . If the binding does not support security (such as ), the effective is for the whole contract. The result is that depending upon the endpoint binding, clients can require different message or transport level security protection even when the contract specifies . ]]> @@ -341,20 +341,20 @@ ## Remarks Use the property to require bindings that support sessions between endpoints. A session is a way of correlating a set of messages exchanged between two or more endpoints. If your service supports channel sessions, you can then use the property to specify the relationship between instances your service contract implementation and the channel session. If a binding does not support sessions, an exception is thrown. - For example, if the property is set to and the property is set to , clients can use the same connection to make repeated calls to the same service object. + For example, if the property is set to and the property is set to , clients can use the same connection to make repeated calls to the same service object. For more information about sessions and service instances, see [Using Sessions](~/docs/framework/wcf/using-sessions.md) and [Sessions, Instancing, and Concurrency](~/docs/framework/wcf/feature-details/sessions-instancing-and-concurrency.md). > [!NOTE] > A channel that supports sessions supports the default association of a service instance with a particular session. However, different session implementations support different features in addition to session-based instancing control. [!INCLUDE[indigo2](~/includes/indigo2-md.md)] provides four types of sessions that you can use to provide sessionful application behavior; each type of session provides additional behavior specific to the type of session it is. -1. The supports security sessions, in which both ends of communication have agreed upon an encryption and/or digital signature process; all messages are correlated with that specific secure conversation. For more information, see [Securing Services](~/docs/framework/wcf/securing-services.md). For example, the , which contains support for both security sessions and reliable sessions, by default uses only a secure session which encrypts and digitally signs messages. +1. The supports security sessions, in which both ends of communication have agreed upon an encryption and/or digital signature process; all messages are correlated with that specific secure conversation. For more information, see [Securing Services](~/docs/framework/wcf/securing-services.md). For example, the , which contains support for both security sessions and reliable sessions, by default uses only a secure session which encrypts and digitally signs messages. -2. The supports the sessions exposed by the TCP/IP connections to ensure that all messages are correlated by the connection session at the socket level. +2. The supports the sessions exposed by the TCP/IP connections to ensure that all messages are correlated by the connection session at the socket level. -3. The , which implements the WS-ReliableMessaging specification, provides support for reliable sessions in which messages are delivered in order and exactly once, enabling confidence even when messages travel across multiple nodes during the conversation. For more information, see [Reliable Sessions](~/docs/framework/wcf/feature-details/reliable-sessions.md). +3. The , which implements the WS-ReliableMessaging specification, provides support for reliable sessions in which messages are delivered in order and exactly once, enabling confidence even when messages travel across multiple nodes during the conversation. For more information, see [Reliable Sessions](~/docs/framework/wcf/feature-details/reliable-sessions.md). -4. The provides MSMQ datagram sessions. For more information, see [Queues in WCF](~/docs/framework/wcf/feature-details/queues-in-wcf.md). +4. The provides MSMQ datagram sessions. For more information, see [Queues in WCF](~/docs/framework/wcf/feature-details/queues-in-wcf.md). Remember that setting the property does not specify the type of session the contract requires, only that it requires one. diff --git a/xml/System.ServiceModel/ServiceHost.xml b/xml/System.ServiceModel/ServiceHost.xml index 8367d6bd80091..3988ca41c1f28 100644 --- a/xml/System.ServiceModel/ServiceHost.xml +++ b/xml/System.ServiceModel/ServiceHost.xml @@ -83,9 +83,9 @@ when you want to provide a specific object instance for use by a singleton service. You may want to use this overload when your service implementation type is difficult to construct (for example, if it does not implement a default public constructor that has no parameters). + Use this constructor as an alternative to implementing a custom when you want to provide a specific object instance for use by a singleton service. You may want to use this overload when your service implementation type is difficult to construct (for example, if it does not implement a default public constructor that has no parameters). - Note that when an object is provided to this overload, some features related to the [!INCLUDE[indigo1](~/includes/indigo1-md.md)] instancing behavior work differently. For example, calling have no effect when a well-known object instance is provided using this constructor overload. Similarly, any other instance release mechanism is ignored. The always behaves as if the property is set to for all operations. + Note that when an object is provided to this overload, some features related to the [!INCLUDE[indigo1](~/includes/indigo1-md.md)] instancing behavior work differently. For example, calling have no effect when a well-known object instance is provided using this constructor overload. Similarly, any other instance release mechanism is ignored. The always behaves as if the property is set to for all operations. diff --git a/xml/System.ServiceModel/SessionMode.xml b/xml/System.ServiceModel/SessionMode.xml index 68362877d2fe2..18d994fe70a8c 100644 --- a/xml/System.ServiceModel/SessionMode.xml +++ b/xml/System.ServiceModel/SessionMode.xml @@ -16,21 +16,21 @@ enumeration with the property to require, allow, or prohibit bindings to use sessions between endpoints that connect to or support the service contract. A session is a way of correlating a set of messages exchanged between two or more endpoints. For more information about sessions, see [Using Sessions](~/docs/framework/wcf/using-sessions.md). + Use the enumeration with the property to require, allow, or prohibit bindings to use sessions between endpoints that connect to or support the service contract. A session is a way of correlating a set of messages exchanged between two or more endpoints. For more information about sessions, see [Using Sessions](~/docs/framework/wcf/using-sessions.md). - If your service supports sessions, you can then use the property to specify the relationship between instances of your service contract implementation and the channel session. + If your service supports sessions, you can then use the property to specify the relationship between instances of your service contract implementation and the channel session. - For example, if the property is set to Allowed and the property is set to , a client can use a binding that supports reliable sessions to make repeated calls to the same service object. + For example, if the property is set to Allowed and the property is set to , a client can use a binding that supports reliable sessions to make repeated calls to the same service object. - Because a session is a channel-level concept that the application model uses, there is an interaction between the enumeration in a contract and the property, which controls the association between channels and specific service objects. + Because a session is a channel-level concept that the application model uses, there is an interaction between the enumeration in a contract and the property, which controls the association between channels and specific service objects. - The following table shows the result of an incoming channel either supporting reliable sessions or not supporting reliable sessions given a service's combination of the values of the property and the property. + The following table shows the result of an incoming channel either supporting reliable sessions or not supporting reliable sessions given a service's combination of the values of the property and the property. |InstanceContextMode Value|Required|Allowed|NotAllowed| |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -|PerCall|- Behavior with sessionful channel: A session and for each call.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each call.
- Behavior with sessionless channel: An for each call.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each call.| -|PerSession|- Behavior with sessionful channel: A session and for each channel.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each channel.
- Behavior with sessionless channel: An for each call.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each call.| -|Single|- Behavior with sessionful channel: One session and one for all calls.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each created singleton or for the user-specified singleton.
- Behavior with sessionless channel: An for each created singleton or for the user-specified singleton.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each created singleton or for the user-specified singleton.| +|PerCall|- Behavior with sessionful channel: A session and for each call.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each call.
- Behavior with sessionless channel: An for each call.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each call.| +|PerSession|- Behavior with sessionful channel: A session and for each channel.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each channel.
- Behavior with sessionless channel: An for each call.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each call.| +|Single|- Behavior with sessionful channel: One session and one for all calls.
- Behavior with sessionless channel: An exception is thrown.|- Behavior with sessionful channel: A session and for each created singleton or for the user-specified singleton.
- Behavior with sessionless channel: An for each created singleton or for the user-specified singleton.|- Behavior with sessionful channel: An exception is thrown.
- Behavior with sessionless channel: An for each created singleton or for the user-specified singleton.| diff --git a/xml/System.ServiceModel/WSDualHttpSecurityMode.xml b/xml/System.ServiceModel/WSDualHttpSecurityMode.xml index 1e35168db6ead..53ea89a320e09 100644 --- a/xml/System.ServiceModel/WSDualHttpSecurityMode.xml +++ b/xml/System.ServiceModel/WSDualHttpSecurityMode.xml @@ -16,12 +16,12 @@ supports. + This enumeration defines the security modes that the supports. ## Examples - The following code shows how to set to a member of this enumeration. + The following code shows how to set to a member of this enumeration. [!code-csharp[S_UEWSDualHttpSecurity#30](~/samples/snippets/csharp/VS_Snippets_CFX/s_uewsdualhttpsecurity/cs/program.cs#30)] [!code-vb[S_UEWSDualHttpSecurity#30](~/samples/snippets/visualbasic/VS_Snippets_CFX/s_uewsdualhttpsecurity/vb/module1.vb#30)] diff --git a/xml/System.ServiceModel/WorkflowServiceHost.xml b/xml/System.ServiceModel/WorkflowServiceHost.xml index 30817a558dd35..f648fa0f27000 100644 --- a/xml/System.ServiceModel/WorkflowServiceHost.xml +++ b/xml/System.ServiceModel/WorkflowServiceHost.xml @@ -459,7 +459,7 @@ calls before calling . This means the workflow runtime will shut down before the service host closes. + In the default implementation, calls before calling . This means the workflow runtime will shut down before the service host closes. ]]> diff --git a/xml/System.ServiceProcess.Design/ServiceInstallerDialog.xml b/xml/System.ServiceProcess.Design/ServiceInstallerDialog.xml index 52540df06c439..511ad4147bc00 100644 --- a/xml/System.ServiceProcess.Design/ServiceInstallerDialog.xml +++ b/xml/System.ServiceProcess.Design/ServiceInstallerDialog.xml @@ -83,7 +83,7 @@ on a new form; it is typically used for testing purposes. + This method is equivalent to calling on a new form; it is typically used for testing purposes. Call on the form to display the dialog box in your application. diff --git a/xml/System.ServiceProcess.Design/ServiceInstallerDialogResult.xml b/xml/System.ServiceProcess.Design/ServiceInstallerDialogResult.xml index fcffc27b70ae3..89857ab0dd9d7 100644 --- a/xml/System.ServiceProcess.Design/ServiceInstallerDialogResult.xml +++ b/xml/System.ServiceProcess.Design/ServiceInstallerDialogResult.xml @@ -15,7 +15,7 @@ property uses this enumeration to indicate the user response to the dialog box. + The property uses this enumeration to indicate the user response to the dialog box. diff --git a/xml/System.ServiceProcess/ServiceBase.xml b/xml/System.ServiceProcess/ServiceBase.xml index 5f6c18c13321e..99262355b4b8b 100644 --- a/xml/System.ServiceProcess/ServiceBase.xml +++ b/xml/System.ServiceProcess/ServiceBase.xml @@ -109,7 +109,7 @@ to `true` instructs the service to use the Application event log to report command failures, as well as state change information for Start, Stop, Pause, and Continue events on the service. The name of the service is used as the log's . + Setting to `true` instructs the service to use the Application event log to report command failures, as well as state change information for Start, Stop, Pause, and Continue events on the service. The name of the service is used as the log's . To report information to a custom event log rather than the Application log, set to `false` and write instructions within the command-handling methods , , or to post to the appropriate log. @@ -147,7 +147,7 @@ ## Remarks When the computer power status changes, the Service Control Manager (SCM) verifies whether the service accepts power event commands using the value of . - If is `true`, the command is passed to the service and the method is called if defined. If is not implemented in the derived class, the SCM handles the power event through the empty base class method. + If is `true`, the command is passed to the service and the method is called if defined. If is not implemented in the derived class, the SCM handles the power event through the empty base class method. ]]> @@ -284,7 +284,7 @@ ## Remarks When Stop is called on a service, the Service Control Manager (SCM) verifies whether the service accepts Stop commands using the value of . For most services, the value of is `true`, but some operating system services, for example, do not allow the user to stop them. - If is `true`, the Stop command is passed to the service and the method is called if it is defined. If is not implemented in the derived class, the SCM handles the Stop command through the empty base class method. + If is `true`, the Stop command is passed to the service and the method is called if it is defined. If is not implemented in the derived class, the SCM handles the Stop command through the empty base class method. ]]> @@ -352,9 +352,9 @@ property to an instance with the and properties set. The source is the of the service, and the log is the computer's Application log. These values are set automatically and cannot be changed for automatic logging of service commands. + The constructor initializes the property to an instance with the and properties set. The source is the of the service, and the log is the computer's Application log. These values are set automatically and cannot be changed for automatic logging of service commands. - When is `true`, Start, Stop, Pause, Continue, and custom commands are recorded automatically in the Application event log. You can use the property to write additional messages to that log as well. The component calls using this member. + When is `true`, Start, Stop, Pause, Continue, and custom commands are recorded automatically in the Application event log. You can use the property to write additional messages to that log as well. The component calls using this member. To report information to a custom event log rather than the Application log, set to `false` and write instructions within the command-handling methods , , or to post to the appropriate log. @@ -731,7 +731,7 @@ ## Remarks Call this overload in the `main()` function of the service executable to register the service with the Service Control Manager. After you call , the Service Control Manager issues a Start command, which results in a call to the method in the service. The service is not started until the Start command is executed. - The method is called in much the same way as for Windows Forms applications. + The method is called in much the same way as for Windows Forms applications. If is `true`, an entry is written to the event log if the service specified by the `service` parameter fails to start. @@ -765,7 +765,7 @@ ## Remarks Call this overload in the `main()` function of the service executable to register the services with the Service Control Manager. After you call , the Service Control Manager issues Start commands, which result in calls to the methods in the services. The services are not started until the Start commands are executed. - The method is called in much the same way as the method for Windows Forms applications. + The method is called in much the same way as the method for Windows Forms applications. If is `true`, an entry is written to the event log if any service in the array fails to start. @@ -863,9 +863,9 @@ identifies the service to the Service Control Manager. The value of this property must be identical to the name recorded for the service in the property of the corresponding installer class. In code, the of the service is usually set in the `main()` function of the executable. + The identifies the service to the Service Control Manager. The value of this property must be identical to the name recorded for the service in the property of the corresponding installer class. In code, the of the service is usually set in the `main()` function of the executable. - The is also used to specify the associated with the property. This is an instance that writes service command information to the Application log. + The is also used to specify the associated with the property. This is an instance that writes service command information to the Application log. The , which supplies the source string for the event log, must be set before the service writes to the event log. Trying to access the event log before the source name is set causes an exception to be thrown. diff --git a/xml/System.ServiceProcess/ServiceController.xml b/xml/System.ServiceProcess/ServiceController.xml index 5112d0ee5d4e5..aa46aa9ab5cb3 100644 --- a/xml/System.ServiceProcess/ServiceController.xml +++ b/xml/System.ServiceProcess/ServiceController.xml @@ -40,7 +40,7 @@ > [!NOTE] > By default, is set to the local computer, so you do not need to change it unless you want to set the instance to point to another computer. - Generally, the service author writes code that customizes the action associated with a specific command. For example, a service can contain code to respond to an command. In that case, the custom processing for the task runs before the system pauses the service. + Generally, the service author writes code that customizes the action associated with a specific command. For example, a service can contain code to respond to an command. In that case, the custom processing for the task runs before the system pauses the service. The set of commands a service can process depends on its properties; for example, you can set the property for a service to `false`. This setting renders the `Stop` command unavailable on that particular service; it prevents you from stopping the service from the SCM by disabling the necessary button. If you try to stop the service from your code, the system raises an error and displays the error message "Failed to stop `servicename`." @@ -95,7 +95,7 @@ constructor to create a object that is used to control a sample service. This example is part of a larger example that is provided for the class. + The following example demonstrates the use of the constructor to create a object that is used to control a sample service. This example is part of a larger example that is provided for the class. [!code-csharp[ServiceControllerClass#2](~/samples/snippets/csharp/VS_Snippets_CLR/ServiceControllerClass/CS/program.cs#2)] [!code-vb[ServiceControllerClass#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/ServiceControllerClass/VB/program.vb#2)] @@ -536,7 +536,7 @@ ## Examples - The following code example shows the use of the method to execute custom commands in the `SimpleService` service example. + The following code example shows the use of the method to execute custom commands in the `SimpleService` service example. [!code-csharp[ServiceContoller_ExecuteCommand#1](~/samples/snippets/csharp/VS_Snippets_CLR/ServiceContoller_ExecuteCommand/CS/program.cs#1)] [!code-vb[ServiceContoller_ExecuteCommand#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/ServiceContoller_ExecuteCommand/VB/module1.vb#1)] diff --git a/xml/System.ServiceProcess/ServiceInstaller.xml b/xml/System.ServiceProcess/ServiceInstaller.xml index 0da07e9256b59..21ef166b257fa 100644 --- a/xml/System.ServiceProcess/ServiceInstaller.xml +++ b/xml/System.ServiceProcess/ServiceInstaller.xml @@ -28,17 +28,17 @@ The associated with your project installation class installs information common to all instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method. > [!NOTE] -> It is crucial that the be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. +> It is crucial that the be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. You can modify other properties on the either before or after adding it to the collection of your project installer. For example, a service's may be set to start the service automatically at reboot or require a user to start the service manually. - Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. + Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. The installation utility calls to remove the object. - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance, and each instance is installed by the utility. It is usually unnecessary for your code to modify state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance, and each instance is installed by the utility. It is usually unnecessary for your code to modify state information explicitly. - When the installation is performed, it automatically creates an to install the event log source associated with the derived class. The property for this source is set by the constructor to the computer's Application log. When you set the of the (which should be identical to the of the service), the is automatically set to the same value. In an installation failure, the source's installation is rolled-back along with previously installed services. + When the installation is performed, it automatically creates an to install the event log source associated with the derived class. The property for this source is set by the constructor to the computer's Application log. When you set the of the (which should be identical to the of the service), the is automatically set to the same value. In an installation failure, the source's installation is rolled-back along with previously installed services. The method tries to stop the service if it is running. Whether this succeeds or not, undoes the changes made by . If a new source was created for event logging, the source is deleted. @@ -47,7 +47,7 @@ ## Examples The following example creates a project installer, called `MyProjectInstaller`, which inherits from . It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for `MyProjectInstaller` (which would be called by the install utility), objects are created for each of these services, and a is created for the executable. For the install utility to recognize `MyProjectInstaller` as a valid installer, the attribute is set to `true`. - Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses `MyProjectInstaller`, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each can be backed out in turn, if an installation failure occurs. + Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses `MyProjectInstaller`, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each can be backed out in turn, if an installation failure occurs. Normally, you would not create an instance of your project installer class explicitly. You would create it and add the attribute to the syntax, but it is the install utility that actually calls, and therefore instantiates, the class. @@ -77,7 +77,7 @@ ## Remarks To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. - The constructor automatically generates an event log source whose property is set to the computer's Application log, and an . When you set the of the , which should be identical to the of the service, the property of the event log is automatically set to the same value. The source is deleted automatically in the case of an installation failure. + The constructor automatically generates an event log source whose property is set to the computer's Application log, and an . When you set the of the , which should be identical to the of the service, the property of the event log is automatically set to the same value. The source is deleted automatically in the case of an installation failure. The constructor sets the property to `ServiceStartMode.Manual` to specify that a user start the service. You can reset the property to `ServiceStartMode.Automatic` to specify that the service start when the computer reboots. @@ -109,7 +109,7 @@ ## Remarks This method will rarely be called within your code. is usually called only by designers. - saves the service name of the `component` parameter to the of the instance. (Because the parameter must be an instance of a class that derives from , `component` is guaranteed to have a property.) + saves the service name of the `component` parameter to the of the instance. (Because the parameter must be an instance of a class that derives from , `component` is guaranteed to have a property.) > [!NOTE] > If you are using the Visual Studio designer, this method is called at design time when the user clicks `Add Installer` on a component that specified this class as its installer. The installer takes all information it can from the live component and stores it for use at install time. @@ -262,7 +262,7 @@ ## Remarks Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the method during installation. It backs out failures, if necessary, by calling on the object that generated the exception. - An application's install routine maintains information automatically about the components that were already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components that were already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. The associated with your project installation class installs information common to all instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method. @@ -350,7 +350,7 @@ ## Remarks Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. ]]> @@ -386,7 +386,7 @@ be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. + It is crucial that the be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. When you set the of the service installer, the of the associated event log is set to the same value. This allows the service to automatically log service commands (such as Start and Stop) calls to the Application log on the computer. @@ -500,7 +500,7 @@ Normally, you will not call the methods on within your code; they are generally called only by the install utility. InstallUtil is used to uninstall services as well as install them; uninstalling takes a switch in the command line call. - An application's uninstall routine maintains information automatically about the components being uninstalled, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's uninstall routine maintains information automatically about the components being uninstalled, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. diff --git a/xml/System.ServiceProcess/ServiceProcessInstaller.xml b/xml/System.ServiceProcess/ServiceProcessInstaller.xml index 24ff30ba8c71c..8c0a41c599474 100644 --- a/xml/System.ServiceProcess/ServiceProcessInstaller.xml +++ b/xml/System.ServiceProcess/ServiceProcessInstaller.xml @@ -27,9 +27,9 @@ > [!NOTE] > The computer's System account is not the same as the Administrator account. - Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. + Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. Instantiating a causes the base class constructor, , to be called. @@ -38,7 +38,7 @@ ## Examples The following example creates a project installer called MyProjectInstaller, which inherits from . It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for MyProjectInstaller (which would be called by the install utility), objects are created for each service, and a is created for the executable. For the install utility to recognize MyProjectInstaller as a valid installer, the attribute is set to `true`. - Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses MyProjectInstaller, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each object can be backed out in turn in case of an installation failure. + Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses MyProjectInstaller, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each object can be backed out in turn in case of an installation failure. Normally, you would not instantiate your project installer class explicitly. You would create it and add the , but the install utility actually calls, and therefore instantiates, the class. @@ -177,11 +177,11 @@ within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on all previously installed components. This method passes the installation to the base class method. + Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on all previously installed components. This method passes the installation to the base class method. - Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components + Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. passes to the calling method any exceptions thrown by base class methods or / event handlers. @@ -216,7 +216,7 @@ ## Remarks The and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. - and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. + and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. @@ -250,9 +250,9 @@ within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. + Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. passes to the calling method any exceptions thrown by base class methods or / event handlers. @@ -294,7 +294,7 @@ ## Remarks The and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. - and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. + and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. diff --git a/xml/System.ServiceProcess/ServiceStartMode.xml b/xml/System.ServiceProcess/ServiceStartMode.xml index 65cc0ebb41f12..008de336c31a2 100644 --- a/xml/System.ServiceProcess/ServiceStartMode.xml +++ b/xml/System.ServiceProcess/ServiceStartMode.xml @@ -20,7 +20,7 @@ is used by the service installer to indicate whether the new service should be disabled at system startup, whether the system should start the service automatically at system startup, or whether the service should be started manually by a user or application. It is also used by the property to indicate how a particular service starts. + The is used by the service installer to indicate whether the new service should be disabled at system startup, whether the system should start the service automatically at system startup, or whether the service should be started manually by a user or application. It is also used by the property to indicate how a particular service starts. ]]> diff --git a/xml/System.ServiceProcess/SessionChangeDescription.xml b/xml/System.ServiceProcess/SessionChangeDescription.xml index 87b7aa83a709a..df4e484456eb4 100644 --- a/xml/System.ServiceProcess/SessionChangeDescription.xml +++ b/xml/System.ServiceProcess/SessionChangeDescription.xml @@ -139,7 +139,7 @@ ## Remarks This operator is implemented using the method. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -171,7 +171,7 @@ ## Remarks This operator is implemented using the method. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml index 4824ed1937234..d36a634bbef1b 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml @@ -26,7 +26,7 @@ ## Remarks An object can consist of phrases, entities such as objects, logical combinations of phrases and objects, and so on. You can use the property on the class to gain access to the constituents of an object. - The order in which objects appear in a given object specifies the order in which a user must speak them. By default, the contents of an must be spoken exactly once. To specify that the contents of an must be spoken repeatedly, use the constructor and set the `repeatCount` parameter. Similarly, to specify a range for the number of times that an can be spoken, create the with one of the constructors that set the property and the property. If the already exists, you can use one of the or the methods to specify repeats. + The order in which objects appear in a given object specifies the order in which a user must speak them. By default, the contents of an must be spoken exactly once. To specify that the contents of an must be spoken repeatedly, use the constructor and set the `repeatCount` parameter. Similarly, to specify a range for the number of times that an can be spoken, create the with one of the constructors that set the property and the property. If the already exists, you can use one of the or the methods to specify repeats. You can also specify the probability that an item will be repeatedly spoken by setting the value of the property. diff --git a/xml/System.Speech.Recognition/AudioLevelUpdatedEventArgs.xml b/xml/System.Speech.Recognition/AudioLevelUpdatedEventArgs.xml index 1b83ffba42f13..4b8752a4b71d6 100644 --- a/xml/System.Speech.Recognition/AudioLevelUpdatedEventArgs.xml +++ b/xml/System.Speech.Recognition/AudioLevelUpdatedEventArgs.xml @@ -16,9 +16,9 @@ and events pass an instance of to the handler for the associated event. + When they are raised, the and events pass an instance of to the handler for the associated event. - The property gets the new level of audio input when the or event is raised. + The property gets the new level of audio input when the or event is raised. The `AudioLevel` property of the and classes provides the current level of the audio input to the speech recognition engine. diff --git a/xml/System.Speech.Recognition/AudioState.xml b/xml/System.Speech.Recognition/AudioState.xml index 14eaa6bf8827a..3fe0f0b8b0a9b 100644 --- a/xml/System.Speech.Recognition/AudioState.xml +++ b/xml/System.Speech.Recognition/AudioState.xml @@ -15,7 +15,7 @@ and properties. The and events are raised when the audio input state of a speech recognition engine changes. + You can obtain the audio input state of the speech recognition engine with the and properties. The and events are raised when the audio input state of a speech recognition engine changes. diff --git a/xml/System.Speech.Recognition/AudioStateChangedEventArgs.xml b/xml/System.Speech.Recognition/AudioStateChangedEventArgs.xml index 914e55f6aa0f3..f3fa0eb8348e0 100644 --- a/xml/System.Speech.Recognition/AudioStateChangedEventArgs.xml +++ b/xml/System.Speech.Recognition/AudioStateChangedEventArgs.xml @@ -16,7 +16,7 @@ property gets a new instance of the enumeration when a or a event is raised. + The property gets a new instance of the enumeration when a or a event is raised. You can obtain the current state of the audio input using the `AudioState` property of the or classes. diff --git a/xml/System.Speech.Recognition/Choices.xml b/xml/System.Speech.Recognition/Choices.xml index 108a980f23a36..9832094bd363a 100644 --- a/xml/System.Speech.Recognition/Choices.xml +++ b/xml/System.Speech.Recognition/Choices.xml @@ -26,7 +26,7 @@ For example, a object could represent the component *colorChoice* in the phrase, "Change the color to *colorChoice*", where acceptable values for *colorChoice* are "red", or "green", or "blue". > [!NOTE] -> To use a object as an optional component in a phrase, create the object and add it to a object with `minRepeat` and `maxRepeat` set to 0 and 1, respectively. Phrases containing optional components can be recognized whether or not the optional component is spoken. +> To use a object as an optional component in a phrase, create the object and add it to a object with `minRepeat` and `maxRepeat` set to 0 and 1, respectively. Phrases containing optional components can be recognized whether or not the optional component is spoken. The class serves the same function as the `one-of` XML element defined by the [Speech Recognition Grammar Specification (SRGS) Version 1.0](http://www.w3.org/TR/speech-grammar/) and is similar to the class in the namespace. diff --git a/xml/System.Speech.Recognition/Grammar.xml b/xml/System.Speech.Recognition/Grammar.xml index bcdbd8d234c53..78d7871e8b2a3 100644 --- a/xml/System.Speech.Recognition/Grammar.xml +++ b/xml/System.Speech.Recognition/Grammar.xml @@ -390,7 +390,7 @@ private static Grammar CreateSrgsDocumentGrammar() An SRGS grammar can define a root rule. To create a object from a string and specify a root rule, use the constructor. - To create a object that specifies a base URI to use to resolve relative rule references, open the file in a file stream and use the constructor. + To create a object that specifies a base URI to use to resolve relative rule references, open the file in a file stream and use the constructor. @@ -1537,7 +1537,7 @@ private static void DumpGrammarStatus(Grammar item) object's event is raised prior to the speech recognizer's `SpeechRecognized` event . For more information, see the , , and events. + The speech recognizer also raises a `SpeechRecognized` event when it recognizes input. The object's event is raised prior to the speech recognizer's `SpeechRecognized` event . For more information, see the , , and events. Any tasks specific to a particular grammar should always be handled by handlers for the object's event. diff --git a/xml/System.Speech.Recognition/GrammarBuilder.xml b/xml/System.Speech.Recognition/GrammarBuilder.xml index 6735b3b432d39..8122de6239e06 100644 --- a/xml/System.Speech.Recognition/GrammarBuilder.xml +++ b/xml/System.Speech.Recognition/GrammarBuilder.xml @@ -1499,7 +1499,7 @@ namespace SampleRecognition ## Remarks The subset element is added to the end of the current sequence of elements. For more information about building a speech recognition grammar using strings, see [Using Strings to Create a GrammarBuilder Grammar](http://msdn.microsoft.com/en-us/0d87b445-a342-4369-9b3f-91d07fd7e114). - For detailed information on the use of subset matching modes, see . + For detailed information on the use of subset matching modes, see . @@ -1998,7 +1998,7 @@ private static Grammar CreateCitiesGrammar2() ## Examples - The following example creates a grammar that accepts password input as a wildcard. The example attaches a event handler to the grammar that validates the password input. + The following example creates a grammar that accepts password input as a wildcard. The example attaches a event handler to the grammar that validates the password input. ```csharp private Grammar CreatePasswordGrammar() @@ -2264,7 +2264,7 @@ private static Grammar CreatePizzaGrammar() > [!IMPORTANT] > When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. For more information about building a speech recognition grammar that contains semantic information, see [Understanding SemanticResultValue and SemanticResultKey Objects](http://msdn.microsoft.com/en-us/0fea1236-5261-4608-89b3-9ce9ffc22a1c). - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2308,7 +2308,7 @@ private static Grammar CreatePizzaGrammar() > [!IMPORTANT] > When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. For more information about building a speech recognition grammar that contains semantic information, see [Understanding SemanticResultValue and SemanticResultKey Objects](http://msdn.microsoft.com/en-us/0fea1236-5261-4608-89b3-9ce9ffc22a1c). - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](http://go.microsoft.com/fwlink/?LinkId=159733), , and objects. @@ -2382,7 +2382,7 @@ private Grammar CreateColorGrammar() > [!IMPORTANT] > When you combine objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. For more information about building a speech recognition grammar that contains semantic information, see [Understanding SemanticResultValue and SemanticResultKey Objects](http://msdn.microsoft.com/en-us/0fea1236-5261-4608-89b3-9ce9ffc22a1c). - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2423,7 +2423,7 @@ private Grammar CreateColorGrammar() This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. - The equivalent method for this operator is ]]> + The equivalent method for this operator is ]]> @@ -2464,7 +2464,7 @@ private Grammar CreateColorGrammar() This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. - The equivalent method for this operator is + The equivalent method for this operator is ## Examples The following example creates a speech recognition grammar that can recognize the two phrases, "Make background *color*" and "Set background to *color*", where *color* is selected from a set of colors. Various types are used to build the final grammar, such as [String](http://go.microsoft.com/fwlink/?LinkId=159733), , and objects. diff --git a/xml/System.Speech.Recognition/LoadGrammarCompletedEventArgs.xml b/xml/System.Speech.Recognition/LoadGrammarCompletedEventArgs.xml index b4ada018b53d5..7ca275b1b6e98 100644 --- a/xml/System.Speech.Recognition/LoadGrammarCompletedEventArgs.xml +++ b/xml/System.Speech.Recognition/LoadGrammarCompletedEventArgs.xml @@ -16,7 +16,7 @@ object raises its or the object raises its event. The events are raised when calls to the `LoadGrammarAsync` methods complete. + An instance of `LoadGrammarCompletedEventArgs` is created when the object raises its or the object raises its event. The events are raised when calls to the `LoadGrammarAsync` methods complete. To obtain information about the object that was loaded, access the property in the handler for the event. diff --git a/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml b/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml index 9b9426dc2e93f..77089ce5af1b5 100644 --- a/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml +++ b/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml @@ -21,7 +21,7 @@ ## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -162,7 +162,7 @@ namespace SampleRecognition ## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -300,7 +300,7 @@ namespace SampleRecognition method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -438,7 +438,7 @@ namespace SampleRecognition method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -581,7 +581,7 @@ namespace SampleRecognition ## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; @@ -723,7 +723,7 @@ namespace SampleRecognition ## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. ``` using System; diff --git a/xml/System.Speech.Recognition/RecognizedAudio.xml b/xml/System.Speech.Recognition/RecognizedAudio.xml index 98ad9f6754f59..b45ab5a3082e8 100644 --- a/xml/System.Speech.Recognition/RecognizedAudio.xml +++ b/xml/System.Speech.Recognition/RecognizedAudio.xml @@ -22,25 +22,25 @@ - Events: - - and + - and - - and + - and - - and + - and - - and + - and - - + - - Methods: - - and + - and - - and + - and - - + - - - + - > [!IMPORTANT] > A recognition result produced by emulated speech recognition does not contain recognized audio. For such a recognition result, its property returns `null` and its method throws an exception. For more information about emulated speech recognition, see the `EmulateRecognize` and `EmulateRecognizeAsync` methods of the and classes. @@ -48,7 +48,7 @@ ## Examples - The following example handles the , , or event and outputs to the console information about the recognized audio that is associated with the recognition result. + The following example handles the , , or event and outputs to the console information about the recognized audio that is associated with the recognition result. ```csharp @@ -106,7 +106,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) ## Examples - The following example handles the or event and outputs to the console information about the recognized audio that is associated with the recognition result. + The following example handles the or event and outputs to the console information about the recognized audio that is associated with the recognition result. ```csharp @@ -157,7 +157,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) or event and outputs to the console information about the recognized audio that is associated with the recognition result. + The following example handles the or event and outputs to the console information about the recognized audio that is associated with the recognition result. ```csharp @@ -208,7 +208,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) or event and outputs to the console information about the recognized audio that is associated with the recognition result. + The following example handles the or event and outputs to the console information about the recognized audio that is associated with the recognition result. ```csharp @@ -375,7 +375,7 @@ private static void TestAudio(object item) ## Examples - The following example handles the or event and outputs to the console information about the recognized audio that is associated with the recognition result. + The following example handles the or event and outputs to the console information about the recognized audio that is associated with the recognition result. ```csharp diff --git a/xml/System.Speech.Recognition/RecognizedPhrase.xml b/xml/System.Speech.Recognition/RecognizedPhrase.xml index 37da9e1258383..cc3aa9099d8af 100644 --- a/xml/System.Speech.Recognition/RecognizedPhrase.xml +++ b/xml/System.Speech.Recognition/RecognizedPhrase.xml @@ -42,7 +42,7 @@ ## Examples - The following example shows a handler for a , , or event and some of the information associated with the object. The class derives from the class. + The following example shows a handler for a , , or event and some of the information associated with the object. The class derives from the class. ```csharp void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) @@ -137,7 +137,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) ## Examples - The following example shows a handler for a , , or event. The example shows information associated with the object, some of which is derived from . The handler displays confidence scores for a recognized phrase as well as for recognition alternates. + The following example shows a handler for a , , or event. The example shows information associated with the object, some of which is derived from . The handler displays confidence scores for a recognized phrase as well as for recognition alternates. ```csharp void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) diff --git a/xml/System.Speech.Recognition/RecognizerInfo.xml b/xml/System.Speech.Recognition/RecognizerInfo.xml index 552430f7bb041..d72d12cafba8e 100644 --- a/xml/System.Speech.Recognition/RecognizerInfo.xml +++ b/xml/System.Speech.Recognition/RecognizerInfo.xml @@ -20,7 +20,7 @@ for a object or for a object. + You can obtain identifying information for an initialized recognition engine using for a object or for a object. The information returned in instances of obtained from a is determined by the settings in the **Speech Properties** member of the **Control Panel**. diff --git a/xml/System.Speech.Recognition/RecognizerUpdateReachedEventArgs.xml b/xml/System.Speech.Recognition/RecognizerUpdateReachedEventArgs.xml index 40deb63501d00..6b2c95ee45bc6 100644 --- a/xml/System.Speech.Recognition/RecognizerUpdateReachedEventArgs.xml +++ b/xml/System.Speech.Recognition/RecognizerUpdateReachedEventArgs.xml @@ -18,15 +18,15 @@ ## Remarks `RecognizerUpdateReached` events provide a mechanism for pausing a speech recognition engine to apply atomic and synchronous modifications, such as loading and unloading grammars. - If your application is using a instance to manage recognition, it can use one of the methods to request that the engine pauses to receive an update. The instance raises a event when it is ready for the update. + If your application is using a instance to manage recognition, it can use one of the methods to request that the engine pauses to receive an update. The instance raises a event when it is ready for the update. While a instance is paused, you can load, unload, enable, and disable objects, and modify values for the , , and properties. - If your application is using a instance to manage recognition, it can use one of the methods to request that the engine pauses to receive an update. The instance raises a event when it is ready for the update. + If your application is using a instance to manage recognition, it can use one of the methods to request that the engine pauses to receive an update. The instance raises a event when it is ready for the update. While a instance is paused, you can load, unload, enable, and disable objects. - When handling and events, a recognition engine pauses until the event handler returns. + When handling and events, a recognition engine pauses until the event handler returns. derives from . @@ -35,7 +35,7 @@ ## Examples The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The application then loads or unloads a object. - At each update, a handler for event writes the name and status of the currently loaded objects to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. + At each update, a handler for event writes the name and status of the currently loaded objects to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. ```csharp using System; @@ -187,14 +187,14 @@ namespace SampleRecognition or methods that take a `userToken` parameter. + An application specifies a `UserToken` when it requests the generation of a `RecognizerUpdateReached` event by calling one of the or methods that take a `userToken` parameter. ## Examples The following example shows a console application that loads and unloads objects. The application uses the method to request the speech recognition engine to pause so it can receive an update. The method passes in a object for the `userToken` parameter that describes what the application will recognize after the update. The application then loads or unloads a object. - At each update, a handler for event writes the contents of `userToken` to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. + At each update, a handler for event writes the contents of `userToken` to the console. As grammars are loaded and unloaded, the application first recognizes the names of farm animals, then the names of farm animals and the names of fruits, then only the names of fruits. ``` using System; diff --git a/xml/System.Speech.Recognition/SemanticValue.xml b/xml/System.Speech.Recognition/SemanticValue.xml index 0233dca363c5f..2596479a7b81b 100644 --- a/xml/System.Speech.Recognition/SemanticValue.xml +++ b/xml/System.Speech.Recognition/SemanticValue.xml @@ -287,7 +287,7 @@ newGrammar.SpeechRecognized += property, which returns a measure of the correctness of semantic parsing, should not be confused with the property, which returns a measure of the accuracy of speech recognition. + The property, which returns a measure of the correctness of semantic parsing, should not be confused with the property, which returns a measure of the accuracy of speech recognition. diff --git a/xml/System.Speech.Recognition/SpeechDetectedEventArgs.xml b/xml/System.Speech.Recognition/SpeechDetectedEventArgs.xml index 01473fdcec468..4b5b0fc8f5fbd 100644 --- a/xml/System.Speech.Recognition/SpeechDetectedEventArgs.xml +++ b/xml/System.Speech.Recognition/SpeechDetectedEventArgs.xml @@ -25,7 +25,7 @@ ## Examples - The example below creates a handler for or events. The handler initializes a display every time speech is detected and displays status information, including audio position. + The example below creates a handler for or events. The handler initializes a display every time speech is detected and displays status information, including audio position. ``` _recognizer.SpeechDetected += @@ -64,7 +64,7 @@ _recognizer.SpeechDetected += or events. The handler initializes a display each time speech is detected and displays status information, including audio position. + The example below creates a handler for or events. The handler initializes a display each time speech is detected and displays status information, including audio position. ``` _recognizer.SpeechDetected += diff --git a/xml/System.Speech.Recognition/SpeechHypothesizedEventArgs.xml b/xml/System.Speech.Recognition/SpeechHypothesizedEventArgs.xml index f2a6dddbc916a..c52993378dc56 100644 --- a/xml/System.Speech.Recognition/SpeechHypothesizedEventArgs.xml +++ b/xml/System.Speech.Recognition/SpeechHypothesizedEventArgs.xml @@ -29,7 +29,7 @@ ## Examples - The example below creates a handler for or events. The handler uses an instance of `SpeechHypothesizedEventArgs` to return and display information about a tentatively recognized phrase. + The example below creates a handler for or events. The handler uses an instance of `SpeechHypothesizedEventArgs` to return and display information about a tentatively recognized phrase. ``` // Create a handler for the SpeechHypothesized event. diff --git a/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml b/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml index a64372091c770..4f7f66e55376f 100644 --- a/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml +++ b/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml @@ -962,7 +962,7 @@ namespace SampleRecognition ## Remarks Each speech recognizer has an algorithm to distinguish between silence and speech. The recognizer classifies as background noise any non-silence input that does not match the initial rule of any of the recognizer's loaded and enabled speech recognition grammars. If the recognizer receives only background noise and silence within the babble timeout interval, then the recognizer finalizes that recognition operation. -- For asynchronous recognition operations, the recognizer raises the event, where the property is `true`, and the property is `null`. +- For asynchronous recognition operations, the recognizer raises the event, where the property is `true`, and the property is `null`. - For synchronous recognition operations and emulation, the recognizer returns `null`, instead of a valid . @@ -2088,7 +2088,7 @@ private static void ListGrammars(SpeechRecognitionEngine recognizer) ## Remarks Each speech recognizer has an algorithm to distinguish between silence and speech. If the recognizer input is silence during the initial silence timeout period, then the recognizer finalizes that recognition operation. -- For asynchronous recognition operations and emulation, the recognizer raises the event, where the property is `true`, and the property is `null`. +- For asynchronous recognition operations and emulation, the recognizer raises the event, where the property is `true`, and the property is `null`. - For synchronous recognition operations and emulation, the recognizer returns `null`, instead of a valid . diff --git a/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml b/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml index 23cfb0546d903..d808c19b84132 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml @@ -206,7 +206,7 @@ Determines if two instances of are equal. Returns if the instances referenced by and are equal, otherwise returns . - .]]> + .]]> @@ -232,7 +232,7 @@ Determines if two instances of are NOT equal. Returns if the instances referenced by and are NOT equal, otherwise returns . - .]]> + .]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml b/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml index 525173c5ab929..1cf61a72cb890 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml @@ -286,7 +286,7 @@ Determines if two instances of describes the same state. Returns if both instances of , and , describe the same state, otherwise is returned. - .]]> + .]]> @@ -312,7 +312,7 @@ Determines if two instances of describes the different state. Returns if both instances of , and , do not describe the same state, otherwise is returned. - .]]> + .]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/ProsodyNumber.xml b/xml/System.Speech.Synthesis.TtsEngine/ProsodyNumber.xml index b43ea1c0e87c0..38d131b0af3e4 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/ProsodyNumber.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/ProsodyNumber.xml @@ -203,7 +203,7 @@ if is the same as ; otherwise, . - .]]> + .]]> @@ -230,7 +230,7 @@ if is different from ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/SayAs.xml b/xml/System.Speech.Synthesis.TtsEngine/SayAs.xml index 40f50cc57e1f7..1affe844f732b 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/SayAs.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/SayAs.xml @@ -56,7 +56,7 @@ property gets or sets the value for the property in a instance. + The property gets or sets the value for the property in a instance. ]]> @@ -81,7 +81,7 @@ property gets or sets the value for the property in a instance. + The property gets or sets the value for the property in a instance. For example, a prompt may contain the phrase "The time is ` 05:00 `". In this example, `05:00` could be spoken as "five o’clock" or "five AM" or "oh five hundred". The property allows the value of the `interpret-as` attribute to be extended to specify which time format to speak. If the value for the `interpret-as` attribute is "time:24hour", the speaks "oh five hundred". If the value for the `interpret-as` attribute is "time:12hour", the speaks "five A M". @@ -108,7 +108,7 @@ property gets or sets the value for the property in a instance. + The property gets or sets the value for the property in a instance. The uses the content type indicated by the property to determine how to render specified text. diff --git a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml index 687949f59409e..93e5c9a2e7f7c 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml @@ -385,7 +385,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si if is the same as ; otherwise, . - .]]> + .]]> @@ -412,7 +412,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si if is different from ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Speech.Synthesis/SpeechSynthesizer.xml b/xml/System.Speech.Synthesis/SpeechSynthesizer.xml index 24ba7845a0be6..e969ecda0c190 100644 --- a/xml/System.Speech.Synthesis/SpeechSynthesizer.xml +++ b/xml/System.Speech.Synthesis/SpeechSynthesizer.xml @@ -729,7 +729,7 @@ namespace SampleSynthesis method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. To select a voice, pass the entire contents of the property as the argument for the method. The object selects the first installed voice that contains `name` in the voice's property. The performs a case-sensitive, substring comparison to determine if the voice matches the `name`. + Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. To select a voice, pass the entire contents of the property as the argument for the method. The object selects the first installed voice that contains `name` in the voice's property. The performs a case-sensitive, substring comparison to determine if the voice matches the `name`. When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice’s property. @@ -1781,13 +1781,13 @@ namespace SampleSynthesis ## Remarks You can also use this method to cancel an asynchronous speak operation for the following: -- The contents of a specified by a method. +- The contents of a specified by a method. -- The contents of a specified by a method. +- The contents of a specified by a method. - The contents of a containing SSML specified by a method. - When you call , , or , System.Speech creates a object and populates it with the contents of the method's parameter, and returns the object. If you retain a copy of the returned , you can pass it into to cancel speaking content specified in a or a object. + When you call , , or , System.Speech creates a object and populates it with the contents of the method's parameter, and returns the object. If you retain a copy of the returned , you can pass it into to cancel speaking content specified in a or a object. ]]> diff --git a/xml/System.Speech.Synthesis/SynthesizerEmphasis.xml b/xml/System.Speech.Synthesis/SynthesizerEmphasis.xml index 2292dfb5b4aa0..5d964fbfb9da0 100644 --- a/xml/System.Speech.Synthesis/SynthesizerEmphasis.xml +++ b/xml/System.Speech.Synthesis/SynthesizerEmphasis.xml @@ -20,7 +20,7 @@ property uses `SynthesiszerEmphasis` to describe the emphasis of a viseme when the event is raised. The property uses `SynthesiszerEmphasis` to describe the emphasis of a phoneme when the event is raised. + The property uses `SynthesiszerEmphasis` to describe the emphasis of a viseme when the event is raised. The property uses `SynthesiszerEmphasis` to describe the emphasis of a phoneme when the event is raised. ]]> diff --git a/xml/System.Text.Encodings.Web/TextEncoder.xml b/xml/System.Text.Encodings.Web/TextEncoder.xml index 008da1cb33425..c476da4f1eebb 100644 --- a/xml/System.Text.Encodings.Web/TextEncoder.xml +++ b/xml/System.Text.Encodings.Web/TextEncoder.xml @@ -18,7 +18,7 @@ , , and properties. + TextEncoder subclasses can be used to do HTML encoding, URI encoding, and JavaScript encoding. Instances of such subclasses can be accessed using the , , and properties. The source code for this type is available in the [System.Text.Encodings.Web project](https://github.com/dotnet/corefx/tree/master/src/System.Text.Encodings.Web) on GitHub. Unit tests that can also serve as code examples are found in the [System.Text.Encodings.Web/tests](https://github.com/dotnet/corefx/tree/master/src/System.Text.Encodings.Web/tests) folder on GitHub. ]]> diff --git a/xml/System.Text.RegularExpressions/Capture.xml b/xml/System.Text.RegularExpressions/Capture.xml index ceba123db8994..678a2d8a9f1c8 100644 --- a/xml/System.Text.RegularExpressions/Capture.xml +++ b/xml/System.Text.RegularExpressions/Capture.xml @@ -29,9 +29,9 @@ object is immutable and has no public constructor. Instances are returned through the object, which is returned by the `Match.Captures` and properties. However, the `Match.Captures` property provides information about the same match as the object. + A object is immutable and has no public constructor. Instances are returned through the object, which is returned by the `Match.Captures` and properties. However, the `Match.Captures` property provides information about the same match as the object. - If you do not apply a to a capturing group, the property returns a with a single object that provides information about the same capture as the object. If you do apply a quantifier to a capturing group, the `Group.Index`, `Group.Length`, and `Group.Value` properties provide information only about the last captured group, whereas the objects in the provide information about all subexpression captures. The example provides an illustration. + If you do not apply a to a capturing group, the property returns a with a single object that provides information about the same capture as the object. If you do apply a quantifier to a capturing group, the `Group.Index`, `Group.Length`, and `Group.Value` properties provide information only about the last captured group, whereas the objects in the provide information about all subexpression captures. The example provides an illustration. @@ -189,12 +189,12 @@ or method fails to find a match, the value of the returned `Match.Value` property is . If the regular expression engine is unable to match a capturing group. the value of the returned `Group.Value` property is . See the second example for an illustration. + If a call to the or method fails to find a match, the value of the returned `Match.Value` property is . If the regular expression engine is unable to match a capturing group. the value of the returned `Group.Value` property is . See the second example for an illustration. ## Examples - The following example defines a regular expression that matches sentences that contain no punctuation except for a period ("."). The `Match.Value` property displays the result string, which consists of a matched sentence, for each match. The `Group.Value` property displays the result string for each capturing group; it consists of the last string captured by that capturing group. The property displays the result string for each capture. + The following example defines a regular expression that matches sentences that contain no punctuation except for a period ("."). The `Match.Value` property displays the result string, which consists of a matched sentence, for each match. The `Group.Value` property displays the result string for each capturing group; it consists of the last string captured by that capturing group. The property displays the result string for each capture. [!code-csharp[System.Text.RegularExpressions.Capture.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.capture.class/cs/example1.cs#1)] [!code-vb[System.Text.RegularExpressions.Capture.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.capture.class/vb/example1.vb#1)] @@ -210,7 +210,7 @@ In this example, the input string consists of two sentences. As the output shows, the first sentence consists of only one word, so the object has a single object that represents the same capture as the object. The second sentence consists of multiple words, so the objects only contain information about the last matched subexpression. Group 1, which represents the first capture, contains the last word in the sentence that has a closing period. Group 2, which represents the second capture, contains the last word in the sentence. However, the objects in the group's object capture each subexpression match. The objects in the first capturing group's collection of captures contain information about each captured word and white-space character or period. The objects in the second capturing group's collection of captures contain information about each captured word. - The following example uses a regular expression pattern, `^([a-z]+)(\d+)*\.([a-z]+(\d)*)$`, to match a product number that consists of two parts separated by a period. Both parts consist of alphabetic characters followed by optional numbers. Because the first input string does not match the pattern, the value of the returned object's `Value` property is . Similarly, when the regular expression pattern is unable to match a capturing group, the value of the corresponding object's `Value` property is . + The following example uses a regular expression pattern, `^([a-z]+)(\d+)*\.([a-z]+(\d)*)$`, to match a product number that consists of two parts separated by a period. Both parts consist of alphabetic characters followed by optional numbers. Because the first input string does not match the pattern, the value of the returned object's `Value` property is . Similarly, when the regular expression pattern is unable to match a capturing group, the value of the corresponding object's `Value` property is . [!code-csharp[System.Text.RegularExpressions.Capture.Value#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.capture.value/cs/value1.cs#1)] [!code-vb[System.Text.RegularExpressions.Capture.Value#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.capture.value/vb/value1.vb#1)] @@ -220,7 +220,7 @@ |Pattern|Description| |-------------|-----------------| |`^`|Begin the match at the beginning of the string.| -|`([a-z]+)`|Match one or more occurrences of any character from a to z. Because the regular expression engine is passed the option, this comparison is case-insensitive. This is the first capturing group.| +|`([a-z]+)`|Match one or more occurrences of any character from a to z. Because the regular expression engine is passed the option, this comparison is case-insensitive. This is the first capturing group.| |`(\d+)?`|Match zero or one occurrence of one or more decimal digits. This is the second capturing group.| |`\.`|Match a literal period character.| |`([a-z]+`|Match one or more occurrences of any character from a to z. The comparison is case-insensitive.| diff --git a/xml/System.Text.RegularExpressions/CaptureCollection.xml b/xml/System.Text.RegularExpressions/CaptureCollection.xml index 3ae1cb1819391..a9a9bdbed6dec 100644 --- a/xml/System.Text.RegularExpressions/CaptureCollection.xml +++ b/xml/System.Text.RegularExpressions/CaptureCollection.xml @@ -37,7 +37,7 @@ Instances of the class are returned by the following properties: -- The property. Each member of the collection represents a substring captured by a capturing group. If a quantifier is not applied to a capturing group, the includes a single object that represents the same captured substring as the object. If a quantifier is applied to a capturing group, the includes one object for each captured substring, and the object provides information only about the last captured substring. +- The property. Each member of the collection represents a substring captured by a capturing group. If a quantifier is not applied to a capturing group, the includes a single object that represents the same captured substring as the object. If a quantifier is applied to a capturing group, the includes one object for each captured substring, and the object provides information only about the last captured substring. - The `Match.Captures` property. In this case, the collection consists of a single object that provides information about the match as a whole. That is, the object provides the same information as the object. @@ -46,15 +46,15 @@ ## Examples - The following example compares the objects in the object returned by the and `Match.Captures` properties. It also compares objects with the objects in the returned by the property. The example uses the following two regular expressions to find matches in a single input string: + The following example compares the objects in the object returned by the and `Match.Captures` properties. It also compares objects with the objects in the returned by the property. The example uses the following two regular expressions to find matches in a single input string: - `\b\w+\W{1,2}` - This regular expression pattern identifies a word that consists of one or more word characters, followed by either one or two non-word characters such as white space or punctuation. The regular expression does not include any capturing groups. The output from the example shows that both the object and the objects returned by the and `Match.Captures` properties contain information about the same match. + This regular expression pattern identifies a word that consists of one or more word characters, followed by either one or two non-word characters such as white space or punctuation. The regular expression does not include any capturing groups. The output from the example shows that both the object and the objects returned by the and `Match.Captures` properties contain information about the same match. - `(\b\w+\W{1,2})+` - This regular expression pattern identifies the words in a sentence. The pattern defines a single capturing group that consists of one or more word characters followed by one or two non-word characters. The regular expression pattern uses the `+` quantifier to match one or more occurrences of this group. The output from this example shows that the object and the object returned by the `Match.Captures` property contain information about the same match. The second object, which corresponds to the only capturing group in the regular expression, identifies only the last captured string, whereas the object returned by the first capturing group's property includes all captured substrings. + This regular expression pattern identifies the words in a sentence. The pattern defines a single capturing group that consists of one or more word characters followed by one or two non-word characters. The regular expression pattern uses the `+` quantifier to match one or more occurrences of this group. The output from this example shows that the object and the object returned by the `Match.Captures` property contain information about the same match. The second object, which corresponds to the only capturing group in the regular expression, identifies only the last captured string, whereas the object returned by the first capturing group's property includes all captured substrings. [!code-csharp[System.Text.RegularExpressions.CaptureCollection#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.capturecollection/cs/capturecollectionex1.cs#1)] [!code-vb[System.Text.RegularExpressions.CaptureCollection#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.capturecollection/vb/capturecollectionex1.vb#1)] @@ -99,7 +99,7 @@ Because the entire collection is copied into the array starting at the given index, the destination array must be at least as large as the collection. > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the method instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the method instead. ]]> @@ -265,7 +265,7 @@ ## Remarks > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. ]]> @@ -338,7 +338,7 @@ ## Remarks > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. ]]> diff --git a/xml/System.Text.RegularExpressions/Group.xml b/xml/System.Text.RegularExpressions/Group.xml index d573020ba03b2..08b46eddf2105 100644 --- a/xml/System.Text.RegularExpressions/Group.xml +++ b/xml/System.Text.RegularExpressions/Group.xml @@ -29,9 +29,9 @@ property. Information about the last substring captured can be accessed directly from the `Value` and `Index` properties. (That is, the instance is equivalent to the last item of the collection returned by the property, which reflects the last capture made by the capturing group.) + A capturing group can capture zero, one, or more strings in a single match because of quantifiers. (For more information, see [Quantifiers](~/docs/standard/base-types/quantifiers-in-regular-expressions.md).) All the substrings matched by a single capturing group are available from the property. Information about the last substring captured can be accessed directly from the `Value` and `Index` properties. (That is, the instance is equivalent to the last item of the collection returned by the property, which reflects the last capture made by the capturing group.) - An example helps to clarify this relationship between a object and the that is returned by the property. The regular expression pattern `(\b(\w+?)[,:;]?\s?)+[?.!]` matches entire sentences. The regular expression is defined as shown in the following table. + An example helps to clarify this relationship between a object and the that is returned by the property. The regular expression pattern `(\b(\w+?)[,:;]?\s?)+[?.!]` matches entire sentences. The regular expression is defined as shown in the following table. |Pattern|Description| |-------------|-----------------| diff --git a/xml/System.Text.RegularExpressions/GroupCollection.xml b/xml/System.Text.RegularExpressions/GroupCollection.xml index 600662ae14f6a..b6c22531e3910 100644 --- a/xml/System.Text.RegularExpressions/GroupCollection.xml +++ b/xml/System.Text.RegularExpressions/GroupCollection.xml @@ -33,11 +33,11 @@ class is a zero-based collection class that consists of one or more objects that provide information about captured groups in a regular expression match. The collection is immutable (read-only) and has no public constructor. A object is returned by the property. + The class is a zero-based collection class that consists of one or more objects that provide information about captured groups in a regular expression match. The collection is immutable (read-only) and has no public constructor. A object is returned by the property. - The collection contains one or more objects. If the match is successful, the first element in the collection contains the object that corresponds to the entire match. Each subsequent element represents a captured group, if the regular expression includes capturing groups. Matches from numbered (unnamed) capturing groups appear in numeric order before matches from named capturing groups. If the match is unsuccessful, the collection contains a single object whose property is `false` and whose property equals . For more information, see the "Grouping Constructs and Regular Expression Objects" section in the [Grouping Constructs](~/docs/standard/base-types/grouping-constructs-in-regular-expressions.md) article. + The collection contains one or more objects. If the match is successful, the first element in the collection contains the object that corresponds to the entire match. Each subsequent element represents a captured group, if the regular expression includes capturing groups. Matches from numbered (unnamed) capturing groups appear in numeric order before matches from named capturing groups. If the match is unsuccessful, the collection contains a single object whose property is `false` and whose property equals . For more information, see the "Grouping Constructs and Regular Expression Objects" section in the [Grouping Constructs](~/docs/standard/base-types/grouping-constructs-in-regular-expressions.md) article. - To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. In addition, you can access individual numbered captured groups from the property (the indexer in C#), and you can access individual named captured groups from the property. Note that you can retrieve an array that contains the numbers and names of all capturing groups by calling the and methods, respectively. Both are instance methods and require that you instantiate a object that represents the regular expression to be matched. + To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. In addition, you can access individual numbered captured groups from the property (the indexer in C#), and you can access individual named captured groups from the property. Note that you can retrieve an array that contains the numbers and names of all capturing groups by calling the and methods, respectively. Both are instance methods and require that you instantiate a object that represents the regular expression to be matched. @@ -95,7 +95,7 @@ Because the entire collection is copied into the array starting at the given index, the destination array must be at least as large as the collection. > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the method instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the method instead. @@ -180,7 +180,7 @@ object always has at least one member. If a match is unsuccessful, the property returns a object that contains a single member. + The object always has at least one member. If a match is unsuccessful, the property returns a object that contains a single member. ]]> @@ -284,7 +284,7 @@ ## Remarks > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. ]]> @@ -328,13 +328,13 @@ ## Remarks The property is the index (in C#) or the default property (in Visual Basic) of the class. It allows you to enumerate the members of the collection by using a `foreach` statement in C# or a `For Each` statement in Visual Basic. - You can also use this property to retrieve individual captured groups by their index number. You can retrieve an array that contains the numbers of all capturing groups in a regular expression by calling the instance method. You can also map named capturing groups to their numbers by calling the instance method. + You can also use this property to retrieve individual captured groups by their index number. You can retrieve an array that contains the numbers of all capturing groups in a regular expression by calling the instance method. You can also map named capturing groups to their numbers by calling the instance method. You can determine the number of items in the collection by retrieving the value of the property. Valid values for the `groupnum` parameter range from 0 to one less than the number of items in the collection. - The object returned by the property always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the single object in the collection has its property set to `false` and its `Group.Value` property set to . + The object returned by the property always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the single object in the collection has its property set to `false` and its `Group.Value` property set to . - If `groupnum` is not the index of a member of the collection, or if `groupnum` is the index of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . + If `groupnum` is not the index of a member of the collection, or if `groupnum` is the index of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . @@ -392,9 +392,9 @@ ## Remarks `groupName` can be either the name of a capturing group that is defined by the `(?<`*name*`>)` element in a regular expression, or the string representation of the number of a capturing group that is defined by a grouping construct. For more information about groups in regular expressions, see [Grouping Constructs](~/docs/standard/base-types/grouping-constructs-in-regular-expressions.md). - You can retrieve the names of all the captured groups in a object by calling the method. You can also map the numbers of capturing groups in a regular expression to their names by calling the method. Individual names from the array can then be passed to the property to retrieve the captured string. + You can retrieve the names of all the captured groups in a object by calling the method. You can also map the numbers of capturing groups in a regular expression to their names by calling the method. Individual names from the array can then be passed to the property to retrieve the captured string. - If `groupname` is not the name of a capturing group in the collection, or if `groupname` is the name of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . + If `groupname` is not the name of a capturing group in the collection, or if `groupname` is the name of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . @@ -444,7 +444,7 @@ ## Remarks > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. ]]> diff --git a/xml/System.Text.RegularExpressions/Match.xml b/xml/System.Text.RegularExpressions/Match.xml index c00cc52192567..a0e56fb092e07 100644 --- a/xml/System.Text.RegularExpressions/Match.xml +++ b/xml/System.Text.RegularExpressions/Match.xml @@ -29,11 +29,11 @@ object is immutable and has no public constructor. An instance of the class is returned by the method and represents the first pattern match in a string. Subsequent matches are represented by objects returned by the method. In addition, a object that consists of zero, one, or more objects is returned by the method. + The object is immutable and has no public constructor. An instance of the class is returned by the method and represents the first pattern match in a string. Subsequent matches are represented by objects returned by the method. In addition, a object that consists of zero, one, or more objects is returned by the method. - If the method fails to match a regular expression pattern in an input string, it returns an empty object. You can then use a `foreach` construct in C# or a `For Each` construct in Visual Basic to iterate the collection. + If the method fails to match a regular expression pattern in an input string, it returns an empty object. You can then use a `foreach` construct in C# or a `For Each` construct in Visual Basic to iterate the collection. - If the method fails to match the regular expression pattern, it returns a object that is equal to . You can use the property to determine whether the match was successful. The following example provides an illustration. + If the method fails to match the regular expression pattern, it returns a object that is equal to . You can use the property to determine whether the match was successful. The following example provides an illustration. [!code-csharp[System.Text.RegularExpressions.Match.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Match.Class/cs/Match1.cs#1)] [!code-vb[System.Text.RegularExpressions.Match.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Match.Class/vb/Match1.vb#1)] @@ -44,9 +44,9 @@ - You can iterate the members of the object by using a `foreach` (C#) or `For Each` (Visual Basic) construct. -- You can use the property to retrieve groups by the number of the capturing group. Note that you can determine which numbered groups are present in a regular expression by calling the instance method. +- You can use the property to retrieve groups by the number of the capturing group. Note that you can determine which numbered groups are present in a regular expression by calling the instance method. -- You can use the property to retrieve groups by the name of the capturing group. Note that you can determine which named groups are present in a regular expression by calling the instance method. +- You can use the property to retrieve groups by the name of the capturing group. Note that you can determine which named groups are present in a regular expression by calling the instance method. @@ -60,7 +60,7 @@ **Example 1** - The following example calls the method to retrieve all pattern matches in an input string. It then iterates the objects in the returned object to display information about each match. + The following example calls the method to retrieve all pattern matches in an input string. It then iterates the objects in the returned object to display information about each match. [!code-csharp[System.Text.RegularExpressions.Match.Class#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Match.Class/cs/Match2.cs#2)] [!code-vb[System.Text.RegularExpressions.Match.Class#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Match.Class/vb/Match2.vb#2)] @@ -108,7 +108,7 @@ ). + This property should not be used to determine if a match is successful. Instead, use the `Match.Success` property (which is inherited from ). ]]> @@ -151,7 +151,7 @@ [!code-csharp[System.Text.RegularExpressions.Match.Groups#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.match.groups/cs/groups1.cs#1)] [!code-vb[System.Text.RegularExpressions.Match.Groups#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.match.groups/vb/groups1.vb#1)] - The object returned by the property is a zero-based collection object that always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the property of the single object in the collection (the object at index 0) is set to `false` and the object's property is set to . If the regular expression engine can find a match, the first element of the object (the element at index 0) returned by the property contains a string that matches the entire regular expression pattern. Each subsequent element, from index one upward, represents a captured group, if the regular expression includes capturing groups. For more information, see the "Grouping Constructs and Regular Expression Objects" section of the [Grouping Constructs](~/docs/standard/base-types/grouping-constructs-in-regular-expressions.md) article. + The object returned by the property is a zero-based collection object that always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the property of the single object in the collection (the object at index 0) is set to `false` and the object's property is set to . If the regular expression engine can find a match, the first element of the object (the element at index 0) returned by the property contains a string that matches the entire regular expression pattern. Each subsequent element, from index one upward, represents a captured group, if the regular expression includes capturing groups. For more information, see the "Grouping Constructs and Regular Expression Objects" section of the [Grouping Constructs](~/docs/standard/base-types/grouping-constructs-in-regular-expressions.md) article. @@ -199,7 +199,7 @@ again and passing (`Index+Length`) as the new starting position. + This method is similar to calling again and passing (`Index+Length`) as the new starting position. > [!NOTE] > This method does not modify the current instance. Instead, it returns a new object that contains information about the next match. @@ -264,7 +264,7 @@ method replaces all matches in an input string with a specified replacement pattern, the method replaces a single match with a specified replacement pattern. Because it operates on an individual match, it is also possible to perform processing on the matched string before you call the method. + Whereas the method replaces all matches in an input string with a specified replacement pattern, the method replaces a single match with a specified replacement pattern. Because it operates on an individual match, it is also possible to perform processing on the matched string before you call the method. The `replacement` parameter is a standard regular expression replacement pattern. It can consist of literal characters and regular expression substitutions. For more information, see [Substitutions](~/docs/standard/base-types/substitutions-in-regular-expressions.md). diff --git a/xml/System.Text.RegularExpressions/MatchCollection.xml b/xml/System.Text.RegularExpressions/MatchCollection.xml index ab99759e3d62c..20387e838c7a5 100644 --- a/xml/System.Text.RegularExpressions/MatchCollection.xml +++ b/xml/System.Text.RegularExpressions/MatchCollection.xml @@ -33,19 +33,19 @@ method returns a object. + The collection is immutable (read-only) and has no public constructor. The method returns a object. - The collection contains zero or more objects. If the match is successful, the collection is populated with one object for each match found in the input string. If the match is unsuccessful, the collection contains no objects, and its property equals zero. + The collection contains zero or more objects. If the match is successful, the collection is populated with one object for each match found in the input string. If the match is unsuccessful, the collection contains no objects, and its property equals zero. When applying a regular expression pattern to a particular input string, the regular expression engine uses either of two techniques to build the object: - Direct evaluation. - The object is populated all at once, with all matches resulting from a particular call to the method. This technique is used when the collection's property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit. + The object is populated all at once, with all matches resulting from a particular call to the method. This technique is used when the collection's property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit. - Lazy evaluation. - The object is populated as needed on a match-by-match basis. It is equivalent to the regular expression engine calling the method repeatedly and adding each match to the collection. This technique is used when the collection is accessed through its method, or when it is accessed using the `foreach` statement (in C#) or the `For Each`...`Next` statement (in Visual Basic). + The object is populated as needed on a match-by-match basis. It is equivalent to the regular expression engine calling the method repeatedly and adding each match to the collection. This technique is used when the collection is accessed through its method, or when it is accessed using the `foreach` statement (in C#) or the `For Each`...`Next` statement (in Visual Basic). To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. @@ -98,7 +98,7 @@ Because the collection is copied into the array starting at the given index, the destination array must be at least as large as the entire collection. > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the method instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the method instead. Because the object is generally populated by using lazy evaluation, trying to copy the collection before it has been fully populated may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a single match exceeds that time-out interval. @@ -177,7 +177,7 @@ ## Examples - The following example uses the property to determine whether the call to the method found any matches. If not, it indicates that no matches were found. Otherwise, it enumerates the matches and displays their value and the position in the input string at which they were found. + The following example uses the property to determine whether the call to the method found any matches. If not, it indicates that no matches were found. Otherwise, it enumerates the matches and displays their value and the position in the input string at which they were found. [!code-csharp[System.Text.RegularExpressions.MatchCollection.Count#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.matchcollection.count/cs/countex1.cs#1)] [!code-vb[System.Text.RegularExpressions.MatchCollection.Count#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.matchcollection.count/vb/countex1.vb#1)] @@ -224,7 +224,7 @@ ## Remarks Instead of calling the method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) provided by your programming language. - Iterating the members of the object using the method (or the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. This is analogous to repeatedly calling the method, and then adding the resulting match to the object. In contrast, the regular expression engine uses direct evaluation to populate the collection all at once when the property is accessed. This can be a much more expensive method of building the collection than lazy evaluation. + Iterating the members of the object using the method (or the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. This is analogous to repeatedly calling the method, and then adding the resulting match to the object. In contrast, the regular expression engine uses direct evaluation to populate the collection all at once when the property is accessed. This can be a much more expensive method of building the collection than lazy evaluation. Because the object is generally populated by using lazy evaluation, trying to navigate to the next member of the collection may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find the next match exceeds that time-out interval. @@ -292,7 +292,7 @@ ## Remarks > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. ]]> @@ -393,7 +393,7 @@ huge ## Remarks > [!WARNING] -> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. +> This member is not present in the [!INCLUDE[net_portable](~/includes/net-portable-md.md)]. If you are developing applications that target the [!INCLUDE[net_portable](~/includes/net-portable-md.md)], use the property instead. ]]> diff --git a/xml/System.Text.RegularExpressions/MatchEvaluator.xml b/xml/System.Text.RegularExpressions/MatchEvaluator.xml index d3a66e1099504..995384d65c6f6 100644 --- a/xml/System.Text.RegularExpressions/MatchEvaluator.xml +++ b/xml/System.Text.RegularExpressions/MatchEvaluator.xml @@ -36,7 +36,7 @@ delegate method to perform a custom verification or manipulation operation for each match found by a replacement method such as . For each matched string, the method calls the delegate method with a object that represents the match. The delegate method performs whatever processing you prefer and returns a string that the method substitutes for the matched string. + You can use a delegate method to perform a custom verification or manipulation operation for each match found by a replacement method such as . For each matched string, the method calls the delegate method with a object that represents the match. The delegate method performs whatever processing you prefer and returns a string that the method substitutes for the matched string. diff --git a/xml/System.Text.RegularExpressions/Regex.xml b/xml/System.Text.RegularExpressions/Regex.xml index 80753aef31cba..d7ea8d04a339d 100644 --- a/xml/System.Text.RegularExpressions/Regex.xml +++ b/xml/System.Text.RegularExpressions/Regex.xml @@ -40,7 +40,7 @@ The class represents the .NET Framework's regular expression engine. It can be used to quickly parse large amounts of text to find specific character patterns; to extract, edit, replace, or delete text substrings; and to add the extracted strings to a collection to generate a report. > [!NOTE] -> If your primary interest is to validate a string by determining whether it conforms to a particular pattern, you can use the class. +> If your primary interest is to validate a string by determining whether it conforms to a particular pattern, you can use the class. To use regular expressions, you define the pattern that you want to identify in a text stream by using the syntax documented in [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). Next, you can optionally instantiate a object. Finally, you call a method that performs some operation, such as replacing text that matches the regular expression pattern, or identifying a pattern match. @@ -64,7 +64,7 @@ ## Regex vs. String Methods - The class includes several search and comparison methods that you can use to perform pattern matching with text. For example, the , , and methods determine whether a string instance contains a specified substring; and the , , , and methods return the starting position of a specified substring in a string. Use the methods of the class when you are searching for a specific string. Use the class when you are searching for a specific pattern in a string. For more information and examples, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md). + The class includes several search and comparison methods that you can use to perform pattern matching with text. For example, the , , and methods determine whether a string instance contains a specified substring; and the , , , and methods return the starting position of a specified substring in a string. Use the methods of the class when you are searching for a specific string. Use the class when you are searching for a specific pattern in a string. For more information and examples, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md). [Back to Remarks](#remarks) @@ -85,7 +85,7 @@ However, caching can adversely affect performance in the following two cases: -- When you use static method calls with a large number of regular expressions. By default, the regular expression engine caches the 15 most recently used static regular expressions. If your application uses more than 15 static regular expressions, some regular expressions must be recompiled. To prevent this recompilation, you can increase the property. +- When you use static method calls with a large number of regular expressions. By default, the regular expression engine caches the 15 most recently used static regular expressions. If your application uses more than 15 static regular expressions, some regular expressions must be recompiled. To prevent this recompilation, you can increase the property. - When you instantiate new objects with regular expressions that have previously been compiled. For example, the following code defines a regular expression to locate duplicated words in a text stream. Although the example uses a single regular expression, it instantiates a new object to process each line of text. This results in the recompilation of the regular expression with each iteration of the loop. @@ -105,9 +105,9 @@ - Validation of a match. You call the method to determine whether a match is present. -- Retrieval of a single match. You call the method to retrieve a object that represents the first match in a string or in part of a string. Subsequent matches can be retrieved by calling the method. +- Retrieval of a single match. You call the method to retrieve a object that represents the first match in a string or in part of a string. Subsequent matches can be retrieved by calling the method. -- Retrieval of all matches. You call the method to retrieve a object that represents all the matches found in a string or in part of a string. +- Retrieval of all matches. You call the method to retrieve a object that represents all the matches found in a string or in part of a string. - Replacement of matched text. You call the method to replace matched text. The replacement text can also be defined by a regular expression. In addition, some of the methods include a parameter that enables you to programmatically define the replacement text. @@ -119,7 +119,7 @@ - The method removes these escape characters. -- The method creates an assembly that contains predefined regular expressions. The .NET Framework contains examples of these special-purpose assemblies in the namespace. +- The method creates an assembly that contains predefined regular expressions. The .NET Framework contains examples of these special-purpose assemblies in the namespace. [Back to Remarks](#remarks) @@ -133,7 +133,7 @@ You can set a time-out interval by calling the constructor when you instantiate a regular expression object. For static methods, you can set a time-out interval by calling an overload of a matching method that has a `matchTimeout` parameter. If you do not set a time-out value explicitly, the default time-out value is determined as follows: -- By using the application-wide time-out value, if one exists. This can be any time-out value that applies to the application domain in which the object is instantiated or the static method call is made. You can set the application-wide time-out value by calling the method to assign the string representation of a value to the "REGEX_DEFAULT_MATCH_TIMEOUT" property. +- By using the application-wide time-out value, if one exists. This can be any time-out value that applies to the application domain in which the object is instantiated or the static method call is made. You can set the application-wide time-out value by calling the method to assign the string representation of a value to the "REGEX_DEFAULT_MATCH_TIMEOUT" property. - By using the value , if no application-wide time-out value has been set. @@ -159,7 +159,7 @@ [!code-csharp[Regex_Words#0](~/samples/snippets/csharp/VS_Snippets_CLR/Regex_Words/CS/words.cs#0)] [!code-vb[Regex_Words#0](~/samples/snippets/visualbasic/VS_Snippets_CLR/Regex_Words/VB/words.vb#0)] - The following example illustrates the use of a regular expression to check whether a string either represents a currency value or has the correct format to represent a currency value. In this case, the regular expression is built dynamically from the , , , , and properties for the user's current culture. If the system's current culture is en-US, the resulting regular expression is `^\s*[\+-]?\s?\$?\s?(\d*\.?\d{2}?){1}$`. This regular expression can be interpreted as shown in the following table. + The following example illustrates the use of a regular expression to check whether a string either represents a currency value or has the correct format to represent a currency value. In this case, the regular expression is built dynamically from the , , , , and properties for the user's current culture. If the system's current culture is en-US, the resulting regular expression is `^\s*[\+-]?\s?\$?\s?(\d*\.?\d{2}?){1}$`. This regular expression can be interpreted as shown in the following table. |Pattern|Description| |-------------|-----------------| @@ -260,7 +260,7 @@ A object is immutable, which means that it can be used only for the match pattern you define when you create it. However, it can be used any number of times without being recompiled. - This constructor instantiates a regular expression object that attempts a case-sensitive match of any alphabetical characters defined in `pattern`. For a case-insensitive match, use the constructor. + This constructor instantiates a regular expression object that attempts a case-sensitive match of any alphabetical characters defined in `pattern`. For a case-insensitive match, use the constructor. @@ -427,7 +427,7 @@ - -- +- Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](~/docs/standard/base-types/best-practices.md) and [Backtracking](~/docs/standard/base-types/backtracking-in-regular-expressions.md). To set a reasonable time-out interval, consider the following factors: @@ -799,7 +799,7 @@ 5. Instantiate a object by passing its constructor the object retrieved in step 3 and the array created in step 4. - You can then pass an array of these objects instead of the `attributes` parameter to the method. + You can then pass an array of these objects instead of the `attributes` parameter to the method. @@ -958,14 +958,14 @@ In a regular expression that is defined by using static text, characters that are to be interpreted literally rather than as metacharacters can be escaped by preceding them with a backslash symbol (\\) as well as by calling the method. In a regular expression that is defined dynamically using characters that are not known at design time, calling the method is particularly important to ensure that the regular expression engine interprets individual characters as literals rather than as metacharacters. > [!NOTE] -> If a regular expression pattern includes either the number sign (#) or literal white-space characters, they must be escaped if input text is parsed with the option enabled. +> If a regular expression pattern includes either the number sign (#) or literal white-space characters, they must be escaped if input text is parsed with the option enabled. While the method escapes the straight opening bracket ([) and opening brace ({) characters, it does not escape their corresponding closing characters (] and }). In most cases, escaping these is not necessary. If a closing bracket or brace is not preceded by its corresponding opening character, the regular expression engine interprets it literally. If an opening braket or brace is interpreted as a metacharacter, the regular expression engine interprets the first corresponding closing character as a metacharacter. If this is not the desired behavior, the closing bracket or brace should be escaped by explicitly prepending the backslash (\\) character. For an illustration, see the Example section. ## Examples - The following example extracts comments from text. It assumes that the comments are delimited by a begin comment symbol and an end comment symbol that is selected by the user. Because the comment symbols are to be interpreted literally, they are passed to the method to ensure that they cannot be misinterpreted as metacharacters. In addition, the example explicitly checks whether the end comment symbol entered by the user is a closing bracket (]) or brace (}). If it is, a backslash character (\\) is prepended to the bracket or brace so that it is interpreted literally. Note that the example also uses the collection to display the comment only, rather than the comment together with its opening and closing comment symbols. + The following example extracts comments from text. It assumes that the comments are delimited by a begin comment symbol and an end comment symbol that is selected by the user. Because the comment symbols are to be interpreted literally, they are passed to the method to ensure that they cannot be misinterpreted as metacharacters. In addition, the example explicitly checks whether the end comment symbol entered by the user is a closing bracket (]) or brace (}). If it is, a backslash character (\\) is prepended to the bracket or brace so that it is interpreted literally. Note that the example also uses the collection to display the comment only, rather than the comment together with its opening and closing comment symbols. [!code-csharp[System.Text.RegularExpressions.Regex.Escape#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Escape/cs/Escape3.cs#3)] [!code-vb[System.Text.RegularExpressions.Regex.Escape#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Escape/vb/Escape3.vb#3)] @@ -1164,9 +1164,9 @@ ## Remarks A regular expression pattern may contain either named or numbered capturing groups, which delineate subexpressions within a pattern match. Numbered groups are delimited by the syntax (*subexpression*) and are assigned numbers based on their order in the regular expression. Named groups are delimited by the syntax (?`<`*name*`>`*subexpression*) or (?'*name*'*subexpression*), where *name* is the name by which the subexpression will be identified. (For more information, see [Grouping Constructs](~/docs/standard/base-types/grouping-constructs-in-regular-expressions.md).) The method identifies both named groups and numbered groups by their ordinal positions in the regular expression. Ordinal position zero always represents the entire regular expression. All numbered groups are then counted before named groups, regardless of their actual position in the regular expression pattern. - If `i` is the number of a named group, the method returns the name of the group. If `i` is the number of an unnamed group, the method returns the string representation of the number. For example, if `i` is 1, the method returns "1". If `i` is not the number of a capturing group, the method returns . + If `i` is the number of a named group, the method returns the name of the group. If `i` is the number of an unnamed group, the method returns the string representation of the number. For example, if `i` is 1, the method returns "1". If `i` is not the number of a capturing group, the method returns . - If a pattern match is found, the value returned by this method can then be used to retrieve the object that represents the captured group from the property. The object is returned by the property. + If a pattern match is found, the value returned by this method can then be used to retrieve the object that represents the captured group from the property. The object is returned by the property. @@ -1281,7 +1281,7 @@ - -- +- - @@ -1401,7 +1401,7 @@ ## Remarks The method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -1479,7 +1479,7 @@ ## Remarks The method is typically used to validate a string or to ensure that a string conforms to a particular pattern without retrieving that string for subsequent manipulation. If you want to determine whether one or more strings match a regular expression pattern and then retrieve them for subsequent manipulation, call the or method. - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -1562,7 +1562,7 @@ The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -1650,7 +1650,7 @@ The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -1680,7 +1680,7 @@ |`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| |`$`|End the match at the end of the string.| - Calling the method with the `options` parameter set to is equivalent to defining the following regular expression: + Calling the method with the `options` parameter set to is equivalent to defining the following regular expression: ``` [a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9] @@ -1780,7 +1780,7 @@ |`[A-Z0-9]`|Match any single alphabetic character from `A` through `Z`, or any numeric character.| |`$`|End the match at the end of the string.| - Calling the method with the `options` parameter set to is equivalent to defining the following regular expression: + Calling the method with the `options` parameter set to is equivalent to defining the following regular expression: ``` [a-zA-Z0-9]\d{2}[a-zA-Z0-9](-\d{3}){2}[A-Za-z0-9] @@ -1849,11 +1849,11 @@ ## Remarks The method returns the first substring that matches a regular expression pattern in an input string. For information about the language elements used to build a regular expression pattern, see [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. @@ -1921,15 +1921,15 @@ The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - You can optionally specify a starting position in the string by using the `startat` parameter. When the regular expression engine parses from left to right (the default), the match and the scan move rightward, starting at the character specified in `startat`. When the regular expression engine parses from right to left (when the regular expression pattern is constructed with the option), the match and scan move in the opposite direction and begin with the character at `startat` -1. If you do not specify a starting position, the search begins at the default `startat` position. If the regular expression searches from left to right, the default `startat` position is at the left end of `input`; if it searches from right to left, the default `startat` position is at the right end of `input`. + You can optionally specify a starting position in the string by using the `startat` parameter. When the regular expression engine parses from left to right (the default), the match and the scan move rightward, starting at the character specified in `startat`. When the regular expression engine parses from right to left (when the regular expression pattern is constructed with the option), the match and scan move in the opposite direction and begin with the character at `startat` -1. If you do not specify a starting position, the search begins at the default `startat` position. If the regular expression searches from left to right, the default `startat` position is at the left end of `input`; if it searches from right to left, the default `startat` position is at the right end of `input`. If you want to restrict a match so that it begins at a particular character position in the string and the regular expression engine does not scan the remainder of the string for a match, anchor the regular expression with a `\G` (at the left for a left-to-right pattern, or at the right for a right-to-left pattern). This restricts the match so it must start exactly at `startat`. - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring found at or after the `startat` character position in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring found at or after the `startat` character position in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exeeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exeeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. ]]> @@ -1984,16 +1984,16 @@ The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. ## Examples - The following example calls the method to find the first word that contains at least one `z` character, and then calls the method to find any additional matches. + The following example calls the method to find the first word that contains at least one `z` character, and then calls the method to find any additional matches. [!code-csharp[System.Text.RegularExpressions.Regex.Match#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.match/cs/match1.cs#1)] [!code-vb[System.Text.RegularExpressions.Regex.Match#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.match/vb/match1.vb#1)] @@ -2063,11 +2063,11 @@ The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - The method searches the portion of `input` defined by the `beginning` and `length` parameters for the regular expression pattern. `beginning` always defines the index of the leftmost character to include in the search, and `length` defines the maximum number of characters to search. Together, they define the range of the search. If the search proceeds from left to right (the default), the regular expression engine searches from the character at index `beginning` to the character at index `beginning` + `length` – 1. If the regular expression engine was instantiated by using the option so that the search proceeds from right to left, the regular expression engine searches from the character at index `beginning` + `length` – 1 to the character at index `beginning`. This method returns the first match that it finds within this range. You can retrieve subsequent matches by repeatedly calling the returned object's method. + The method searches the portion of `input` defined by the `beginning` and `length` parameters for the regular expression pattern. `beginning` always defines the index of the leftmost character to include in the search, and `length` defines the maximum number of characters to search. Together, they define the range of the search. If the search proceeds from left to right (the default), the regular expression engine searches from the character at index `beginning` to the character at index `beginning` + `length` – 1. If the regular expression engine was instantiated by using the option so that the search proceeds from right to left, the regular expression engine searches from the character at index `beginning` + `length` – 1 to the character at index `beginning`. This method returns the first match that it finds within this range. You can retrieve subsequent matches by repeatedly calling the returned object's method. - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out value when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified by the constructor. If you do not set a time-out value when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown. ]]> @@ -2132,16 +2132,16 @@ The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. - The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the matching operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. ## Examples - The following example defines a regular expression that matches words beginning with the letter "a". It uses the option to ensure that the regular expression locates words beginning with both an uppercase "a" and a lowercase "a". + The following example defines a regular expression that matches words beginning with the letter "a". It uses the option to ensure that the regular expression locates words beginning with both an uppercase "a" and a lowercase "a". [!code-csharp[System.Text.RegularExpressions.Regex.Match#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.match/cs/match2.cs#2)] [!code-vb[System.Text.RegularExpressions.Regex.Match#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.match/vb/match2.vb#2)] @@ -2216,9 +2216,9 @@ The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . + You can determine whether the regular expression pattern has been found in the input string by checking the value of the returned object's property. If a match is found, the returned object's property contains the substring from `input` that matches the regular expression pattern. If no match is found, its value is . - This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. + This method returns the first substring found in `input` that matches the regular expression pattern. You can retrieve subsequent matches by repeatedly calling the returned object's method. You can also retrieve all matches in a single method call by calling the method. The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](~/docs/standard/base-types/best-practices.md) and [Backtracking](~/docs/standard/base-types/backtracking-in-regular-expressions.md). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. @@ -2290,9 +2290,9 @@ The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. - Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval. + Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval. @@ -2362,9 +2362,9 @@ The regular expression pattern for which the method searches is defined by the call to one of the class constructors. For more information about the elements that can form a regular expression pattern, see [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. - Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval.. + Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if the property is not and a matching operation exceeds the time-out interval.. @@ -2438,7 +2438,7 @@ The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval. @@ -2518,7 +2518,7 @@ The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. Because of its lazy evaluation, calling the method does not throw a exception. However, the exception is thrown when an operation is performed on the object returned by this method, if a time-out interval is defined by the "REGEX_DEFAULT_MATCH_TIMEOUT" property of the current application domain and a matching operation exceeds this time-out interval. @@ -2602,7 +2602,7 @@ The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). - The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. + The method uses lazy evaluation to populate the returned object. Accessing members of this collection such as and causes the collection to be populated immediately. To take advantage of lazy evaluation, you should iterate the collection by using a construct such as `foreach` in C# and `For Each`…`Next` in Visual Basic. Because of its lazy evaluation, calling the method does not throw a exception. However, an exception is thrown when an operation is performed on the object returned by this method, if a matching operation exceeds this time-out interval specified by the`matchTimeout` parameter. @@ -2679,12 +2679,12 @@ ## Remarks The property defines the approximate maximum time interval for a instance to execute a single matching operation before the operation times out. The regular expression engine throws a exception during its next timing check after the time-out interval has elapsed. This prevents the regular expression engine from processing input strings that require excessive backtracking. For more information, see [Backtracking](~/docs/standard/base-types/backtracking-in-regular-expressions.md) and [Best Practices for Regular Expressions](~/docs/standard/base-types/best-practices.md). - This property is read-only. You can set its value explicitly for an individual object by calling the constructor; and you can set its value for all matching operations in an application domain by calling the method and providing a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property, as the following example illustrates. + This property is read-only. You can set its value explicitly for an individual object by calling the constructor; and you can set its value for all matching operations in an application domain by calling the method and providing a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property, as the following example illustrates. [!code-csharp[System.Text.RegularExpressions.Regex.MatchTimeout#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matchtimeout/cs/regexmatchtimeout1.cs#1)] [!code-vb[System.Text.RegularExpressions.Regex.MatchTimeout#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.matchtimeout/vb/regexmatchtimeout1.vb#1)] - If you do not explicitly set a time-out interval, the default value is used, and matching operations do not time out. + If you do not explicitly set a time-out interval, the default value is used, and matching operations do not time out. ]]> @@ -2722,7 +2722,7 @@ property consists of one or more members of the enumeration. If no options were defined in the class constructor, its value is . The available options are discussed in detail in the [Regular Expression Options](~/docs/standard/base-types/regular-expression-options.md) topic. + The value of the property consists of one or more members of the enumeration. If no options were defined in the class constructor, its value is . The available options are discussed in detail in the [Regular Expression Options](~/docs/standard/base-types/regular-expression-options.md) topic. Note that the property does not reflect inline options defined in the regular expression pattern itself. @@ -2807,9 +2807,9 @@ > [!NOTE] > Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](~/docs/standard/base-types/character-escapes-in-regular-expressions.md), are allowed in regular expression patterns only and are not recognized in replacement patterns. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -2882,7 +2882,7 @@ method is useful for replacing a regular expression match if any of the following conditions is true: + The method is useful for replacing a regular expression match if any of the following conditions is true: - The replacement string cannot readily be specified by a regular expression replacement pattern. @@ -2890,7 +2890,7 @@ - The replacement string results from conditional processing. - The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. + The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. The regular expression is the pattern defined by the constructor for the current object. @@ -2901,9 +2901,9 @@ Your custom method returns a string that replaces the matched input. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -2967,9 +2967,9 @@ > [!NOTE] > Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](~/docs/standard/base-types/character-escapes-in-regular-expressions.md), are allowed in regular expression patterns only and are not recognized in replacement patterns. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -3035,9 +3035,9 @@ > [!NOTE] > Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](~/docs/standard/base-types/character-escapes-in-regular-expressions.md), are allowed in regular expression patterns only and are not recognized in replacement patterns. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -3047,7 +3047,7 @@ [!code-csharp[System.Text.RegularExpressions.Regex.Replace#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/cs/replaceexample6.cs#6)] [!code-vb[System.Text.RegularExpressions.Regex.Replace#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replaceexample6.vb#6)] - The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. [!code-csharp[System.Text.RegularExpressions.Regex.Replace#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/cs/replace3.cs#3)] [!code-vb[System.Text.RegularExpressions.Regex.Replace#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace3.vb#3)] @@ -3061,7 +3061,7 @@ |Pattern|Description| |-------------|-----------------| |`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| -|`(?i:" + Environment.MachineName + ")`|Perform a case-insensitive match of the string that is returned by the property.| +|`(?i:" + Environment.MachineName + ")`|Perform a case-insensitive match of the string that is returned by the property.| |`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| |`\\`|Match a backslash (`\`) character.| |`((?i:[" + driveNames + "]))`|Perform a case-insensitive match of the character class that consists of the individual drive lettters. This match is the first captured subexpression.| @@ -3120,7 +3120,7 @@ method is useful for replacing a regular expression match if any of the following conditions is true: + The method is useful for replacing a regular expression match if any of the following conditions is true: - The replacement string cannot readily be specified by a regular expression replacement pattern. @@ -3128,7 +3128,7 @@ - The replacement string results from conditional processing. - The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. + The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). @@ -3139,14 +3139,14 @@ Your custom method returns a string that replaces the matched input. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. [!code-csharp[System.Text.RegularExpressions.Regex.Replace#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/cs/replace5.cs#2)] [!code-vb[System.Text.RegularExpressions.Regex.Replace#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace5.vb#2)] @@ -3202,7 +3202,7 @@ method is useful for replacing a regular expression match if any of the following conditions is true: + The method is useful for replacing a regular expression match if any of the following conditions is true: - The replacement string cannot readily be specified by a regular expression replacement pattern. @@ -3210,7 +3210,7 @@ - The replacement string results from conditional processing. - The method is equivalent to calling the method and passing the first `count` objects in the returned collection to the `evaluator` delegate. + The method is equivalent to calling the method and passing the first `count` objects in the returned collection to the `evaluator` delegate. The regular expression is the pattern defined by the constructor for the current object. @@ -3221,9 +3221,9 @@ Your custom method returns a string that replaces the matched input. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -3299,9 +3299,9 @@ > [!NOTE] > Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](~/docs/standard/base-types/character-escapes-in-regular-expressions.md), are allowed in regular expression patterns only and are not recognized in replacement patterns. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. @@ -3315,9 +3315,9 @@ |Pattern|Description| |-------------|-----------------| -|`^`|Match the start of a line. (Note that the object was instantiated by using the option; otherwise, this character class would only match the beginning of the input string.)| +|`^`|Match the start of a line. (Note that the object was instantiated by using the option; otherwise, this character class would only match the beginning of the input string.)| |`.*`|Match any character zero or more times.| -|`$`|Match the end of a line. (Note that the object was instantiated by using the option; otherwise, this character class would only match the beginning of the input string.)| +|`$`|Match the end of a line. (Note that the object was instantiated by using the option; otherwise, this character class would only match the beginning of the input string.)| The replacement string (`vbCrLf + "$&"` in Visual Basic, `"\n$&"` in C#) adds a new line before the matched string. Note that `\n` in the C# example is interpreted as the newline character by the C# compiler; it does not represent a regular expression character escape. @@ -3381,14 +3381,14 @@ > [!NOTE] > Substitutions are the only regular expression language elements that are recognized in a replacement pattern. All other regular expression language elements, including [character escapes](~/docs/standard/base-types/character-escapes-in-regular-expressions.md), are allowed in regular expression patterns only and are not recognized in replacement patterns. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer, and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. [!code-csharp[System.Text.RegularExpressions.Regex.Replace#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/cs/replace4.cs#4)] [!code-vb[System.Text.RegularExpressions.Regex.Replace#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace4.vb#4)] @@ -3402,7 +3402,7 @@ |Pattern|Description| |-------------|-----------------| |`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| -|`+ Environment.MachineName +`|Match the string that is returned by the property.| +|`+ Environment.MachineName +`|Match the string that is returned by the property.| |`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| |`\\`|Match a backslash (`\`) character.| |`([" + driveNames + "])`|Match the character class that consists of the individual drive letters. This match is the first captured subexpression.| @@ -3465,7 +3465,7 @@ method is useful for replacing a regular expression match in if any of the following conditions is true: + The method is useful for replacing a regular expression match in if any of the following conditions is true: - The replacement string cannot readily be specified by a regular expression replacement pattern. @@ -3473,7 +3473,7 @@ - The replacement string results from conditional processing. - The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. + The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). @@ -3486,14 +3486,14 @@ If you specify for the `options` parameter, the search for matches begins at the end of the input string and moves left; otherwise, the search begins at the start of the input string and moves right. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. [!code-csharp[System.Text.RegularExpressions.Regex.Replace#10](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/cs/replace6.cs#10)] [!code-vb[System.Text.RegularExpressions.Regex.Replace#10](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace6.vb#10)] @@ -3550,7 +3550,7 @@ method is useful for replacing a regular expression match if any of the following conditions is true: + The method is useful for replacing a regular expression match if any of the following conditions is true: - The replacement string cannot readily be specified by a regular expression replacement pattern. @@ -3558,7 +3558,7 @@ - The replacement string results from conditional processing. - The method is equivalent to calling the method and passing the first `count` objects in the returned collection to the `evaluator` delegate. + The method is equivalent to calling the method and passing the first `count` objects in the returned collection to the `evaluator` delegate. The regular expression is the pattern defined by the constructor for the current object. @@ -3569,9 +3569,9 @@ Your custom method returns a string that replaces the matched input. - The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the replacement operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ]]> @@ -3637,12 +3637,12 @@ The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](~/docs/standard/base-types/best-practices.md) and [Backtracking](~/docs/standard/base-types/backtracking-in-regular-expressions.md). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive, and any single replacement operation times out if a match cannot be found in 0.5 second. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. + The following example uses the method to replace the local machine and drive names in a UNC path with a local file path. The regular expression uses the property to include the name of the local computer and the method to include the names of the logical drives. All regular expression string comparisons are case-insensitive, and any single replacement operation times out if a match cannot be found in 0.5 second. To run the example successfully, you should replace the literal string "MyMachine" with your local machine name. [!code-csharp[System.Text.RegularExpressions.Regex.Replace#12](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/cs/replace12.cs#12)] [!code-vb[System.Text.RegularExpressions.Regex.Replace#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace12.vb#12)] @@ -3656,7 +3656,7 @@ |Pattern|Description| |-------------|-----------------| |`\\\\`|Match two consecutive backslash (`\`) characters. Because the backslash character is interpreted as the escape character, each backslash must be escaped with another backslash.| -|`+ Environment.MachineName +`|Match the string that is returned by the property.| +|`+ Environment.MachineName +`|Match the string that is returned by the property.| |`(?:\.\w+)*`|Match the period (`.`) character followed by one or more word characters. This match can occur zero or more times. The matched subexpression is not captured.| |`\\`|Match a backslash (`\`) character.| |`([" + driveNames + "])`|Match the character class that consists of the individual drive letters. This match is the first captured subexpression.| @@ -3731,7 +3731,7 @@ method is useful for replacing a regular expression match if any of the following conditions is true: + The method is useful for replacing a regular expression match if any of the following conditions is true: - If the replacement string cannot readily be specified by a regular expression replacement pattern. @@ -3739,7 +3739,7 @@ - If the replacement string results from conditional processing. - The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. + The method is equivalent to calling the method and passing each object in the returned collection to the `evaluator` delegate. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). @@ -3754,12 +3754,12 @@ The `matchTimeout` parameter specifies how long a pattern matching method should try to find a match before it times out. Setting a time-out interval prevents regular expressions that rely on excessive backtracking from appearing to "stop responding when they process input that contains near matches. For more information, see [Best Practices for Regular Expressions](~/docs/standard/base-types/best-practices.md) and [Backtracking](~/docs/standard/base-types/backtracking-in-regular-expressions.md). If no match is found in that time interval, the method throws a exception. `matchTimeout` overrides any default time-out value defined for the application domain in which the method executes. - Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. + Because the method returns `input` unchanged if there is no match, you can use the method to determine whether the method has made any replacements to the input string. ## Examples - The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. + The following example uses a regular expression to extract the individual words from a string, and then uses a delegate to call a method named `WordScramble` that scrambles the individual letters in the word. To do this, the `WordScramble` method creates an array that contains the characters in the match. It also creates a parallel array that it populates with random floating-point numbers. The arrays are sorted by calling the method, and the sorted array is provided as an argument to a class constructor. This newly created string is then returned by the `WordScramble` method. The regular expression pattern `\w+` matches one or more word characters; the regular expression engine will continue to add characters to the match until it encounters a non-word character, such as a white-space character. The call to the method includes the option so that the comment in the regular expression pattern `\w+ # Matches all the characters in a word.` is ignored by the regular expression engine. [!code-csharp[System.Text.RegularExpressions.Regex.Replace#13](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/cs/replace13.cs#13)] [!code-vb[System.Text.RegularExpressions.Regex.Replace#13](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regex.replace/vb/replace13.vb#13)] @@ -3890,19 +3890,19 @@ methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original input string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original input string. If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found, as the following code shows. [!code-csharp[System.Text.RegularExpressions.Regex.Split#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split1.cs#1)] [!code-vb[System.Text.RegularExpressions.Regex.Split#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split1.vb#1)] - If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `\d+` to split an input string on numeric characters. Because the string begins and ends with matching numeric characters, the value of the first and last element of the returned array is . + If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `\d+` to split an input string on numeric characters. Because the string begins and ends with matching numeric characters, the value of the first and last element of the returned array is . [!code-csharp[System.Text.RegularExpressions.Regex.Split#21](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split21.cs#21)] [!code-vb[System.Text.RegularExpressions.Regex.Split#21](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split21.vb#21)] - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. [!code-csharp[System.Text.RegularExpressions.Regex.Split#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split2.cs#2)] [!code-vb[System.Text.RegularExpressions.Regex.Split#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split2.vb#2)] @@ -3919,7 +3919,7 @@ Note that the returned array also includes an empty string at the beginning and end of the array. - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown ]]> @@ -3966,9 +3966,9 @@ methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string can be split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string can be split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. - If multiple matches are adjacent to one another or if a match is found at the beginning or end of `input`, and the number of matches found is at least two less than `count`, an empty string is inserted into the array. That is, empty strings that result from adjacent matches or from matches at the beginning or end of the input string are counted in determining whether the number of matched substrings equals `count`. In the following example, the regular expression `/d+` is used to split an input string that includes one or more decimal digits into a maximum of three substrings. Because the beginning of the input string matches the regular expression pattern, the first array element contains , the second contains the first set of alphabetic characters in the input string, and the third contains the remainder of the string that follows the third match. + If multiple matches are adjacent to one another or if a match is found at the beginning or end of `input`, and the number of matches found is at least two less than `count`, an empty string is inserted into the array. That is, empty strings that result from adjacent matches or from matches at the beginning or end of the input string are counted in determining whether the number of matched substrings equals `count`. In the following example, the regular expression `/d+` is used to split an input string that includes one or more decimal digits into a maximum of three substrings. Because the beginning of the input string matches the regular expression pattern, the first array element contains , the second contains the first set of alphabetic characters in the input string, and the third contains the remainder of the string that follows the third match. [!code-csharp[System.Text.RegularExpressions.Regex.Split#25](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split25.cs#25)] [!code-vb[System.Text.RegularExpressions.Regex.Split#25](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split25.vb#25)] @@ -3987,7 +3987,7 @@ [!code-vb[System.Text.RegularExpressions.Regex.Split#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split12.vb#12)] - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown ]]> @@ -4034,7 +4034,7 @@ methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `input` string is split as many times as possible. If `pattern` is not found in the `input` string, the return value contains one element whose value is the original `input` string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `input` string is split as many times as possible. If `pattern` is not found in the `input` string, the return value contains one element whose value is the original `input` string. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). @@ -4046,12 +4046,12 @@ [!code-csharp[System.Text.RegularExpressions.Regex.Split#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split8.cs#8)] [!code-vb[System.Text.RegularExpressions.Regex.Split#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split8.vb#8)] - If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `\d+` to split an input string on numeric characters. Because the string begins and ends with matching numeric characters, the value of the first and last element of the returned array is . + If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `\d+` to split an input string on numeric characters. Because the string begins and ends with matching numeric characters, the value of the first and last element of the returned array is . [!code-csharp[System.Text.RegularExpressions.Regex.Split#22](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split22.cs#22)] [!code-vb[System.Text.RegularExpressions.Regex.Split#22](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split22.vb#22)] - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. [!code-csharp[System.Text.RegularExpressions.Regex.Split#9](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split9.cs#9)] [!code-vb[System.Text.RegularExpressions.Regex.Split#9](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split9.vb#9)] @@ -4068,7 +4068,7 @@ Note that the returned array also includes an empty string at the beginning and end of the array. - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. ]]> @@ -4121,7 +4121,7 @@ methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string is split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. The `startat` parameter defines the point at which the search for the first delimiter begins (this can be used for skipping leading white space). + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The `count` parameter specifies the maximum number of substrings into which the `input` string is split; the last string contains the unsplit remainder of the string. A `count` value of zero provides the default behavior of splitting as many times as possible. The `startat` parameter defines the point at which the search for the first delimiter begins (this can be used for skipping leading white space). If no matches are found from the `count`+1 position in the string, the method returns a one-element array that contains the `input` string. If one or more matches are found, the first element of the returned array contains the first portion of the string from the first character up to one character before the match. @@ -4144,7 +4144,7 @@ [!code-csharp[System.Text.RegularExpressions.Regex.Split#14](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split14.cs#14)] [!code-vb[System.Text.RegularExpressions.Regex.Split#14](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split14.vb#14)] - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified by the constructor. If you do not set a time-out interval when you call the constructor, the exception is thrown if the operation exceeds any time-out value established for the application domain in which the object is created. If no time-out is defined in the constructor call or in the application domain's properties, or if the time-out value is , no exception is thrown ]]> @@ -4195,7 +4195,7 @@ methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). @@ -4204,12 +4204,12 @@ If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found. - If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `[a-z]+` to split an input string on any uppercase or lowercase alphabetic character. Because the string begins and ends with matching alphabetic characters, the value of the first and last element of the returned array is . + If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `[a-z]+` to split an input string on any uppercase or lowercase alphabetic character. Because the string begins and ends with matching alphabetic characters, the value of the first and last element of the returned array is . [!code-csharp[System.Text.RegularExpressions.Regex.Split#24](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split24.cs#24)] [!code-vb[System.Text.RegularExpressions.Regex.Split#24](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split24.vb#24)] - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. [!code-csharp[System.Text.RegularExpressions.Regex.Split#9](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split9.cs#9)] [!code-vb[System.Text.RegularExpressions.Regex.Split#9](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split9.vb#9)] @@ -4221,7 +4221,7 @@ If the regular expression can match the empty string, will split the string into an array of single-character strings because the empty string delimiter can be found at every location. - The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. + The exception is thrown if the execution time of the split operation exceeds the time-out interval specified for the application domain in which the method is called. If no time-out is defined in the application domain's properties, or if the time-out value is , no exception is thrown. ]]> @@ -4278,7 +4278,7 @@ methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. + The methods are similar to the method, except that splits the string at a delimiter determined by a regular expression instead of a set of characters. The string is split as many times as possible. If no delimiter is found, the return value contains one element whose value is the original `input` string. The `pattern` parameter consists of regular expression language elements that symbolically describe the string to match. For more information about regular expressions, see [.NET Framework Regular Expressions](~/docs/standard/base-types/regular-expressions.md) and [Regular Expression Language - Quick Reference](~/docs/standard/base-types/regular-expression-language-quick-reference.md). @@ -4287,12 +4287,12 @@ If multiple matches are adjacent to one another, an empty string is inserted into the array. For example, splitting a string on a single hyphen causes the returned array to include an empty string in the position where two adjacent hyphens are found. - If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `[a-z]+` to split an input string on any uppercase or lowercase alphabetic character. Because the string begins and ends with matching alphabetic characters, the value of the first and last element of the returned array is . + If a match is found at the beginning or the end of the input string, an empty string is included at the beginning or the end of the returned array. The following example uses the regular expression pattern `[a-z]+` to split an input string on any uppercase or lowercase alphabetic character. Because the string begins and ends with matching alphabetic characters, the value of the first and last element of the returned array is . [!code-csharp[System.Text.RegularExpressions.Regex.Split#23](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split23.cs#23)] [!code-vb[System.Text.RegularExpressions.Regex.Split#23](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split23.vb#23)] - If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. + If capturing parentheses are used in a expression, any captured text is included in the resulting string array. For example, if you split the string "plum-pear" on a hyphen placed within capturing parentheses, the returned array includes a string element that contains the hyphen. [!code-csharp[System.Text.RegularExpressions.Regex.Split#9](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/cs/split9.cs#9)] [!code-vb[System.Text.RegularExpressions.Regex.Split#9](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.Regex.Split/vb/split9.vb#9)] diff --git a/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml b/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml index dee5e2c79228a..a89d7b62ba01a 100644 --- a/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml +++ b/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml @@ -195,7 +195,7 @@ property is `false`, the regular expression class defined by the current instance can be instantiated only by code that is executing in the assembly that contains the class. However, because the method generates an assembly that contains only compiled regular expressions and does not allow additional code to be added, there is generally no reason to assign this property a value of `false`. + If the property is `false`, the regular expression class defined by the current instance can be instantiated only by code that is executing in the assembly that contains the class. However, because the method generates an assembly that contains only compiled regular expressions and does not allow additional code to be added, there is generally no reason to assign this property a value of `false`. ]]> @@ -228,7 +228,7 @@ You can assign a default time-out value to a object in any of the following ways: -- By calling the method and providing the string representation of a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property. +- By calling the method and providing the string representation of a value for the "REGEX_DEFAULT_MATCH_TIMEOUT" property. - By calling the constructor and providing a value for the `matchTimeout` parameter. diff --git a/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml b/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml index 94d4d06d9cde1..4f2443fdfe7a2 100644 --- a/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml +++ b/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml @@ -46,7 +46,7 @@ ## Examples - The following example illustrates two possible approaches to handling the exception. A constant whose value is two seconds defines the maximum time-out interval. The method is initially called with a time-out interval of one second. Each exception causes the time-out interval to be increased by one second and results in another call to the method if the current time-out interval is less than the maximum time-out interval. However, if the current time-out interval exceeds the maximum time-out interval, the exception handler writes information to the event log and abandons the processing of the regular expression. + The following example illustrates two possible approaches to handling the exception. A constant whose value is two seconds defines the maximum time-out interval. The method is initially called with a time-out interval of one second. Each exception causes the time-out interval to be increased by one second and results in another call to the method if the current time-out interval is less than the maximum time-out interval. However, if the current time-out interval exceeds the maximum time-out interval, the exception handler writes information to the event log and abandons the processing of the regular expression. [!code-csharp[System.Text.RegularExpressions.RegexMatchTimeoutException#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.regularexpressions.regexmatchtimeoutexception/cs/class1.cs#1)] [!code-vb[System.Text.RegularExpressions.RegexMatchTimeoutException#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.regularexpressions.regexmatchtimeoutexception/vb/class1.vb#1)] @@ -122,7 +122,7 @@ property. The string should be localized for the current culture. + The `message` string is assigned to the property. The string should be localized for the current culture. ]]> @@ -158,7 +158,7 @@ object. Instead, it is called by the method when deserializing the object from a stream. + This constructor is not called directly by your code to instantiate the object. Instead, it is called by the method when deserializing the object from a stream. ]]> @@ -198,9 +198,9 @@ object's property. + Typically, you use this overload to handle an exception in a `try/catch` block. The `innerException` parameter should be a reference to the exception object handled in the `catch` block, or it can be `null`. This value is then assigned to the object's property. - The `message` string is assigned to the property. The string should be localized for the current culture. + The `message` string is assigned to the property. The string should be localized for the current culture. ]]> @@ -280,9 +280,9 @@ constructor. If this parameter is not explicitly initialized in a constructor call, its value is . + This property reflects the value of the `regexInput` parameter of the constructor. If this parameter is not explicitly initialized in a constructor call, its value is . - When the exception is thrown by the regular expression engine, the value of the property reflects the entire input string passed to the regular expression engine. It does not reflect a partial string, such as the substring that the engine searches in the call to a method such as . + When the exception is thrown by the regular expression engine, the value of the property reflects the entire input string passed to the regular expression engine. It does not reflect a partial string, such as the substring that the engine searches in the call to a method such as . ]]> @@ -360,7 +360,7 @@ constructor. If the parameter is not properly initialized in a constructor call, its value is . + This property reflects the value of the `regexPattern` parameter of the constructor. If the parameter is not properly initialized in a constructor call, its value is . ]]> diff --git a/xml/System.Text.RegularExpressions/RegexOptions.xml b/xml/System.Text.RegularExpressions/RegexOptions.xml index 5703136cffd0c..341488b418ed7 100644 --- a/xml/System.Text.RegularExpressions/RegexOptions.xml +++ b/xml/System.Text.RegularExpressions/RegexOptions.xml @@ -35,17 +35,17 @@ ## Remarks A value can be provided as a parameter to the following members of the class: -- The class constructor. +- The class constructor. -- The method. +- The method. -- The method. +- The method. -- The method. +- The method. -- The method. +- The method. -- The and methods. +- The and methods. A value can also be supplied as a parameter to the constructor, or it can be assigned directly to the property. The resulting object is then used in the call to the method. @@ -54,7 +54,7 @@ ## Examples - The following example defines two regular expressions that identify repeated words in text but that are instantiated using different values. The first regular expression is case-insensitive; case is ignored when determining whether a word is identical to the preceding word. The second regular expression is case-sensitive; a word must match the case of the preceding word exactly to be considered a duplicate. + The following example defines two regular expressions that identify repeated words in text but that are instantiated using different values. The first regular expression is case-insensitive; case is ignored when determining whether a word is identical to the preceding word. The second regular expression is case-sensitive; a word must match the case of the preceding word exactly to be considered a duplicate. [!code-csharp[System.Text.RegularExpressions.RegexOptions#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.RegularExpressions.RegexOptions/cs/RegexOptions.cs#1)] [!code-vb[System.Text.RegularExpressions.RegexOptions#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.RegularExpressions.RegexOptions/vb/RegexOptions.vb#1)] diff --git a/xml/System.Text/ASCIIEncoding.xml b/xml/System.Text/ASCIIEncoding.xml index 83b78c502b592..949245df22007 100644 --- a/xml/System.Text/ASCIIEncoding.xml +++ b/xml/System.Text/ASCIIEncoding.xml @@ -33,7 +33,7 @@ ## Remarks Encoding is the process of transforming a set of Unicode characters into a sequence of bytes. Decoding is the process of transforming a sequence of encoded bytes into a set of Unicode characters. - corresponds to the Windows code page 20127. Because ASCII is a 7-bit encoding, ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007F. If you use the default encoder returned by the property or the constructor, characters outside that range are replaced with a question mark (?) before the encoding operation is performed. Because the class supports only a limited character set, the , , and classes are better suited for globalized applications. The following considerations can help you to decide whether to use : + corresponds to the Windows code page 20127. Because ASCII is a 7-bit encoding, ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007F. If you use the default encoder returned by the property or the constructor, characters outside that range are replaced with a question mark (?) before the encoding operation is performed. Because the class supports only a limited character set, the , , and classes are better suited for globalized applications. The following considerations can help you to decide whether to use : - Some protocols require ASCII or a subset of ASCII. In these cases ASCII encoding is appropriate. @@ -91,7 +91,7 @@ > [!CAUTION] > The class does not provide error detection. For security reasons, you should use the , , or class and enable error detection. - If you choose to use ASCII encoding, this constructor may not provide the appropriate fallback behavior for your application. It uses the and classes to replace every character outside the range of U+0000 through U+007F with a question mark (?). Instead, you can call the or method and pass it and objects to use exception fallback. + If you choose to use ASCII encoding, this constructor may not provide the appropriate fallback behavior for your application. It uses the and classes to replace every character outside the range of U+0000 through U+007F with a question mark (?). Instead, you can call the or method and pass it and objects to use exception fallback. > [!NOTE] > supports only the Unicode character values between U+0000 and U+007F. Therefore, , , and are better suited for globalized applications. @@ -920,7 +920,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ]]> @@ -961,7 +961,7 @@ method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, an maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, an maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ]]> diff --git a/xml/System.Text/CodePagesEncodingProvider.xml b/xml/System.Text/CodePagesEncodingProvider.xml index 54449533b56ee..7796afbf04d6e 100644 --- a/xml/System.Text/CodePagesEncodingProvider.xml +++ b/xml/System.Text/CodePagesEncodingProvider.xml @@ -29,19 +29,19 @@ The .NET Framework for the Windows desktop supports a large set of Unicode and code page encodings. The Universal Windows platform and .NET Native, on the other hand, support only the following encodings: -- ASCII (code page 20127), which is returned by the property. +- ASCII (code page 20127), which is returned by the property. - ISO-8859-1 (code page 28591). -- UTF-7 (code page 65000), which is returned by the property. +- UTF-7 (code page 65000), which is returned by the property. -- UTF-8 (code page 65001), which is returned by the property. +- UTF-8 (code page 65001), which is returned by the property. -- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. +- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. -- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. +- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. -- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. +- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. - UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. @@ -51,11 +51,11 @@ - Add a reference to the System.Text.Encoding.CodePages.dll assembly to your project. -- Retrieve a object from the static property. +- Retrieve a object from the static property. -- Pass the object to the method. +- Pass the object to the method. - After an object is registered, the encodings that it supports are available by calling the overloads of ; you should not call the overloads. + After an object is registered, the encodings that it supports are available by calling the overloads of ; you should not call the overloads. ]]> @@ -84,21 +84,21 @@ ## Remarks The property returns an object that makes encodings available to apps that target the [!INCLUDE[net_v46](~/includes/net-v46-md.md)] or a later version and that otherwise are available only in the .NET Framework on the Windows desktop. - The .NET Framework on the Windows desktop supports a large number of character encodings and code pages. You can get a complete list of encodings by calling the method, which is available in the full .NET Framework on the Windows desktop. .NET Native for UWP apps, on the other hand, supports only the following encodings by default: + The .NET Framework on the Windows desktop supports a large number of character encodings and code pages. You can get a complete list of encodings by calling the method, which is available in the full .NET Framework on the Windows desktop. .NET Native for UWP apps, on the other hand, supports only the following encodings by default: -- ASCII (code page 20127), which is returned by the property. +- ASCII (code page 20127), which is returned by the property. - ISO-8859-1 (code page 28591). -- UTF-7 (code page 65000), which is returned by the property. +- UTF-7 (code page 65000), which is returned by the property. -- UTF-8 (code page 65001), which is returned by the property. +- UTF-8 (code page 65001), which is returned by the property. -- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. +- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. -- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. +- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. -- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. +- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. - UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. @@ -106,11 +106,11 @@ - Add a reference to the System.Text.Encoding.CodePages.dll assembly to your project. -- Get the object from the static property. +- Get the object from the static property. -- Pass the object to the method to make the encodings supplied by the object available to the common language runtime. +- Pass the object to the method to make the encodings supplied by the object available to the common language runtime. -- Call an overload to retrieve the encoding. The method will call the corresponding method to determine whether it can supply the requested encoding. +- Call an overload to retrieve the encoding. The method will call the corresponding method to determine whether it can supply the requested encoding. ]]> diff --git a/xml/System.Text/Decoder.xml b/xml/System.Text/Decoder.xml index 738d334249dac..e6e459fa14c7b 100644 --- a/xml/System.Text/Decoder.xml +++ b/xml/System.Text/Decoder.xml @@ -37,7 +37,7 @@ ## Remarks To obtain an instance of an implementation of the class, the application should use the method of an implementation. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. There are several versions of both of these methods available in the class. For more information, see . A object maintains state information between successive calls to `GetChars` or methods so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations because those operations often deal with blocks of data instead of a complete data stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. There are several versions of both of these methods available in the class. For more information, see . A object maintains state information between successive calls to `GetChars` or methods so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations because those operations often deal with blocks of data instead of a complete data stream. > [!NOTE] > When the application is done with a stream of data, it should make sure that the state information is flushed by setting the `flush` parameter to `true` in the appropriate method call. If an exception occurs or if the application switches streams, it should call to clear the internal state of the `Decoder` object. @@ -165,7 +165,7 @@ ## Remarks Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. - The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the decoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. + The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the decoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. The `completed` output parameter indicates whether all the data in the input buffer was converted and stored in the output buffer. This parameter is set to `false` if the number of bytes specified by the `byteCount` parameter cannot be converted without exceeding the number of characters specified by the `charCount` parameter. In that situation, the application should use the contents of the output buffer or provide a new output buffer, increment the `bytes` parameter by the number of bytes specified by the `bytesUsed` parameter, then call the `Convert` method again to process the remaining input. @@ -249,7 +249,7 @@ ## Remarks Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the decoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. - The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the decoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. + The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the decoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. The `completed` output parameter indicates whether all the data in the input buffer was converted and stored in the output buffer. This parameter is set to `false` if the number of bytes specified by the `byteCount` parameter cannot be converted without exceeding the number of characters specified by the `charCount` parameter. In that situation, the application should use the contents of the output buffer or provide a new output buffer, increment the `bytes` parameter by the number of bytes specified by the `bytesUsed` parameter, then call the `Convert` method again to process the remaining input. @@ -644,7 +644,7 @@ If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. ]]> @@ -717,7 +717,7 @@ If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. @@ -809,7 +809,7 @@ If `GetChars` is called with `flush` set to `false`, the decoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next decoding operation. The application should call `GetCharCount` on a block of data immediately before calling `GetChars` on the same block, so that any trailing bytes from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the bytes read and chars written. Also see the topic for more comments. ]]> diff --git a/xml/System.Text/DecoderExceptionFallbackBuffer.xml b/xml/System.Text/DecoderExceptionFallbackBuffer.xml index 11ccd07735618..9cc06f7ba6d4f 100644 --- a/xml/System.Text/DecoderExceptionFallbackBuffer.xml +++ b/xml/System.Text/DecoderExceptionFallbackBuffer.xml @@ -27,7 +27,7 @@ ## Remarks A common reason for an encoding or decoding operation to fail is if the underlying encoding class does not provide a mapping between a character and an equivalent byte sequence. If the input byte sequence cannot be converted to an output character, the decoding operation calls the method, which throws . - The class, which represents a data buffer used in a decoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior in which an exception is thrown if a decoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. + The class, which represents a data buffer used in a decoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior in which an exception is thrown if a decoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. ]]> diff --git a/xml/System.Text/DecoderFallback.xml b/xml/System.Text/DecoderFallback.xml index 00f5bee3097f9..9535e36b95075 100644 --- a/xml/System.Text/DecoderFallback.xml +++ b/xml/System.Text/DecoderFallback.xml @@ -29,7 +29,7 @@ class. Specifically, a character is encoded to a byte sequence by calling the encoding type's method, and the byte sequence is decoded to a character array or a string by calling the or method. + An encoding maps a Unicode character to an encoded sequence of bytes. A particular encoding is represented by a type that is derived from the class. Specifically, a character is encoded to a byte sequence by calling the encoding type's method, and the byte sequence is decoded to a character array or a string by calling the or method. A decoding operation can fail if the input byte sequence cannot be mapped by the encoding. For example, an object cannot decode a byte sequence if that sequence represents a character that has a code point value that is outside the range U+0000 to U+007F. @@ -39,7 +39,7 @@ - Best-fit fallback, which maps valid Unicode characters that cannot be decoded to an approximate equivalent. For example, a best-fit fallback handler for the class might map Æ (U+00C6) to AE (U+0041 + U+0045). A best-fit fallback handler might also be implemented to transliterate one alphabet (such as Cyrillic) to another (such as Latin or Roman). The .NET Framework does not provide any public best-fit fallback implementations. -- Replacement fallback, which replaces each character that cannot be decoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the constructor. After the substitute string is emitted, the decoding operation continues converting the remainder of the input. +- Replacement fallback, which replaces each character that cannot be decoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the constructor. After the substitute string is emitted, the decoding operation continues converting the remainder of the input. - Exception fallback, which throws an exception when a byte sequence cannot be decoded. The .NET Framework provides a predefined exception fallback handler. The class throws a when an invalid byte sequence is encountered, and the decoding operation terminates. @@ -116,7 +116,7 @@ that is responsible for performing the fallback operation. For example, of the predefined implementations in the .NET Framework, the method returns a object, and the method returns a object. + This method returns an object derived from that is responsible for performing the fallback operation. For example, of the predefined implementations in the .NET Framework, the method returns a object, and the method returns a object. The method is called by a decoder when it encounters the first byte that it is unable to decode. The object returned by this method provides the fallback implementation and is responsible for returning the string that replaces the byte or bytes that could not be decoded. diff --git a/xml/System.Text/DecoderFallbackBuffer.xml b/xml/System.Text/DecoderFallbackBuffer.xml index 4951b67d32107..57650b410b237 100644 --- a/xml/System.Text/DecoderFallbackBuffer.xml +++ b/xml/System.Text/DecoderFallbackBuffer.xml @@ -126,7 +126,7 @@ , , and methods call if they encounter an unknown input byte sequence that cannot be decoded. A return value of `true` indicates that the fallback buffer can process the input byte sequence, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual bytes, the method in an exception fallback handler throws an exception. + The , , and methods call if they encounter an unknown input byte sequence that cannot be decoded. A return value of `true` indicates that the fallback buffer can process the input byte sequence, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual bytes, the method in an exception fallback handler throws an exception. ]]> diff --git a/xml/System.Text/DecoderFallbackException.xml b/xml/System.Text/DecoderFallbackException.xml index fcaccf7cd42ab..f8689b3b2f2f1 100644 --- a/xml/System.Text/DecoderFallbackException.xml +++ b/xml/System.Text/DecoderFallbackException.xml @@ -70,7 +70,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -109,7 +109,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -150,7 +150,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -193,7 +193,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> diff --git a/xml/System.Text/DecoderReplacementFallbackBuffer.xml b/xml/System.Text/DecoderReplacementFallbackBuffer.xml index bf943adcf9f67..73c641b5aaa63 100644 --- a/xml/System.Text/DecoderReplacementFallbackBuffer.xml +++ b/xml/System.Text/DecoderReplacementFallbackBuffer.xml @@ -27,7 +27,7 @@ ## Remarks It might not be possible to convert an encoded byte sequence to an equivalent character if no suitable decoding exists. A common reason for a decoding to fail is that the conversion operation uses a code page that cannot represent the character to decode. - If the input byte sequence cannot be converted to an output character, a object provides a replacement string that is substituted for the output character. The replacement string initializes the value of the object, and the value of the object initializes the value of a object. The value of a object is called the replacement fallback buffer. The conversion operation uses the replacement fallback buffer to emit a replacement string instead of a decoded character, then continues to process the remainder of the input. + If the input byte sequence cannot be converted to an output character, a object provides a replacement string that is substituted for the output character. The replacement string initializes the value of the object, and the value of the object initializes the value of a object. The value of a object is called the replacement fallback buffer. The conversion operation uses the replacement fallback buffer to emit a replacement string instead of a decoded character, then continues to process the remainder of the input. ]]> @@ -131,7 +131,7 @@ and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character of the replacement fallback buffer. + The and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character of the replacement fallback buffer. ]]> diff --git a/xml/System.Text/Encoder.xml b/xml/System.Text/Encoder.xml index a48d73c968b78..88a232dd499c3 100644 --- a/xml/System.Text/Encoder.xml +++ b/xml/System.Text/Encoder.xml @@ -37,7 +37,7 @@ ## Remarks To obtain an instance of an implementation of the class, the application should use the method of an implementation. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. There are several versions of both of these methods available in the class. For more information, see . + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. There are several versions of both of these methods available in the class. For more information, see . A object maintains state information between successive calls to `GetBytes` or methods so that it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. @@ -167,7 +167,7 @@ ## Remarks Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. - The `Convert` method is designed to be used in a loop to encode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. + The `Convert` method is designed to be used in a loop to encode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. The `completed` output parameter indicates whether all the data in the input buffer was converted and stored in the output buffer. This parameter is set to `false` if the number of characters specified by the `charCount` parameter cannot be converted without exceeding the number of bytes specified by the `byteCount` parameter. In that situation, the application should use the contents of the output buffer or provide a new output buffer, increment the `chars` parameter by the number of characters specified by the `charsUsed` parameter, then call the `Convert` method again to process the remaining input. @@ -251,7 +251,7 @@ ## Remarks Remember that the object saves state between calls to . When the application is done with a stream of data, it should set the `flush` parameter to `true` to make sure that the state information is flushed. With this setting, the encoder ignores invalid bytes at the end of the data block and clears the internal buffer. Any remaining processed data that is part of a logical unit, such as the high surrogate of a surrogate pair, is converted according to the current fallback settings. - The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. + The `Convert` method is designed to be used in a loop to decode an arbitrary amount of input, such as data read from a file or stream. It stores the output of the encoding operation in a fixed-size buffer. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. The `completed` output parameter indicates whether all the data in the input buffer was converted and stored in the output buffer. This parameter is set to `false` if the number of characters specified by the `charCount` parameter cannot be converted without exceeding the number of bytes specified by the `byteCount` parameter. In that situation, the application should use the contents of the output buffer or provide a new output buffer, increment the `chars` parameter by the number of characters specified by the `charsUsed` parameter, then call the `Convert` method again to process the remaining input. @@ -582,7 +582,7 @@ If `GetBytes` is called with `flush` set to `false`, the encoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next encoding operation. The application should call `GetByteCount` on a block of data immediately before calling `GetBytes` on the same block, so that any trailing characters from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. ]]> @@ -658,7 +658,7 @@ If `GetBytes` is called with `flush` set to `false`, the encoder stores trailing bytes at the end of the data block in an internal buffer and uses them in the next encoding operation. The application should call `GetByteCount` on a block of data immediately before calling `GetBytes` on the same block, so that any trailing characters from the previous block are included in the calculation. - If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. + If your application is to convert many segments of an input stream, consider using the method. will throw an exception if the output buffer isn't large enough, but will fill as much space as possible and return the chars read and bytes written. Also see the topic for more comments. diff --git a/xml/System.Text/EncoderExceptionFallback.xml b/xml/System.Text/EncoderExceptionFallback.xml index ac5e4205a5859..a283bd87a79c4 100644 --- a/xml/System.Text/EncoderExceptionFallback.xml +++ b/xml/System.Text/EncoderExceptionFallback.xml @@ -111,7 +111,7 @@ class, which is a subclass of the class. An object throws an exception whenever characters are passed to its method. + An encoder fallback buffer is responsible for receiving and handling characters that an encoder cannot convert to a byte sequence. This method returns an instance of the class, which is a subclass of the class. An object throws an exception whenever characters are passed to its method. ]]> diff --git a/xml/System.Text/EncoderExceptionFallbackBuffer.xml b/xml/System.Text/EncoderExceptionFallbackBuffer.xml index ac47606efce41..a0bcf02441825 100644 --- a/xml/System.Text/EncoderExceptionFallbackBuffer.xml +++ b/xml/System.Text/EncoderExceptionFallbackBuffer.xml @@ -27,7 +27,7 @@ ## Remarks A common reason for an encoding or decoding operation to fail is if the underlying encoding class does not provide a mapping between a character and an equivalent byte sequence. If the input character cannot be converted to an output byte sequence, the encoding operation calls the method, which throws . - The class, which represents a data buffer used in an encoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior wherein an exception is thrown if an encoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. + The class, which represents a data buffer used in an encoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior wherein an exception is thrown if an encoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. ]]> diff --git a/xml/System.Text/EncoderFallback.xml b/xml/System.Text/EncoderFallback.xml index a66892d76264c..78fcefad0a8c0 100644 --- a/xml/System.Text/EncoderFallback.xml +++ b/xml/System.Text/EncoderFallback.xml @@ -29,7 +29,7 @@ class. Specifically, a character is encoded to a byte sequence by calling the encoding type's method, and the byte sequence is decoded to a character array or a string by calling the or method. + An encoding maps a Unicode character to an encoded sequence of bytes. A particular encoding is represented by a type that is derived from the class. Specifically, a character is encoded to a byte sequence by calling the encoding type's method, and the byte sequence is decoded to a character array or a string by calling the or method. An encoding operation can fail if the input character cannot be represented by the encoding. For example, an object cannot encode a character whose Unicode code point value is outside the range U+0000 to U+007F. @@ -39,7 +39,7 @@ - Best-fit fallback, which maps valid Unicode characters that cannot be encoded to an approximate equivalent. For example, a best-fit fallback handler for the class might map Æ (U+00C6) to AE (U+0041 + U+0045). A best-fit fallback handler might also be implemented to transliterate one alphabet (such as Cyrillic) to another (such as Latin or Roman). The .NET Framework does not provide any public best-fit fallback implementations. -- Replacement fallback, which replaces each character that cannot be encoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the constructor. After the substitute string is emitted, the encoding operation continues converting the remainder of the input. +- Replacement fallback, which replaces each character that cannot be encoded with a predefined string. The .NET Framework provides a predefined replacement fallback handler. The class replaces each byte sequence that cannot be decoded with a question mark character ("?", or U+003F) or a REPLACEMENT CHARACTER (U+FFFD). You can customize the replacement string by specifying a substitute in the call to the constructor. After the substitute string is emitted, the encoding operation continues converting the remainder of the input. - Exception fallback, which throws an exception when a character cannot be encoded. The .NET Framework provides a predefined exception fallback handler. The class throws an when an invalid character is encountered, and the encoding operation terminates. @@ -116,7 +116,7 @@ that is responsible for performing the fallback operation. For example, of the predefined implementations in the .NET Framework, the method returns an object, and the method returns an object. + This method returns an object derived from that is responsible for performing the fallback operation. For example, of the predefined implementations in the .NET Framework, the method returns an object, and the method returns an object. The method is called by an encoder when it encounters the first character that it is unable to encode. The object returned by this method provides the fallback implementation and is responsible for returning the byte array that replaces the character or characters that could not be encoded. diff --git a/xml/System.Text/EncoderFallbackBuffer.xml b/xml/System.Text/EncoderFallbackBuffer.xml index 3e650716eab2b..629492da7ac7c 100644 --- a/xml/System.Text/EncoderFallbackBuffer.xml +++ b/xml/System.Text/EncoderFallbackBuffer.xml @@ -126,7 +126,7 @@ and methods call if they encounter an unknown input character that cannot be encoded. A return value of `true` indicates that the fallback buffer can process the input character, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. + The and methods call if they encounter an unknown input character that cannot be encoded. A return value of `true` indicates that the fallback buffer can process the input character, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. ]]> @@ -173,7 +173,7 @@ and methods call if they encounter a surrogate pair in their input. A return value of `true` indicates that the fallback buffer can process the surrogate pair, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. + The and methods call if they encounter a surrogate pair in their input. A return value of `true` indicates that the fallback buffer can process the surrogate pair, which causes the calling method to call the method to obtain each character of the fallback buffer. Because it does not process individual characters, the method in an exception fallback handler throws an exception. ]]> diff --git a/xml/System.Text/EncoderFallbackException.xml b/xml/System.Text/EncoderFallbackException.xml index ef0fb6d9b0557..f922cc3dbfb1e 100644 --- a/xml/System.Text/EncoderFallbackException.xml +++ b/xml/System.Text/EncoderFallbackException.xml @@ -70,7 +70,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -109,7 +109,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -150,7 +150,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> diff --git a/xml/System.Text/EncoderReplacementFallbackBuffer.xml b/xml/System.Text/EncoderReplacementFallbackBuffer.xml index bb033ecc3f609..0191cce0a30de 100644 --- a/xml/System.Text/EncoderReplacementFallbackBuffer.xml +++ b/xml/System.Text/EncoderReplacementFallbackBuffer.xml @@ -27,7 +27,7 @@ ## Remarks It might not be possible to convert a character to an equivalent encoded byte sequence if no suitable encoding exists. A common reason for an encoding to fail is if the conversion operation uses a code page that cannot represent the character to encode. - If the input character cannot be converted to an output byte sequence, a object provides a replacement string that is substituted for the original input character. The replacement string initializes the value of the object, and the value of the object initializes the value of an object. The value of an object is called the replacement fallback buffer. The conversion operation encodes the replacement fallback buffer instead of the original input character, then continues to process the remainder of the input. + If the input character cannot be converted to an output byte sequence, a object provides a replacement string that is substituted for the original input character. The replacement string initializes the value of the object, and the value of the object initializes the value of an object. The value of an object is called the replacement fallback buffer. The conversion operation encodes the replacement fallback buffer instead of the original input character, then continues to process the remainder of the input. ]]> diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index f70bfbe9ada9f..e1bdd1305a7ff 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -45,7 +45,7 @@ Encoding is the process of transforming a set of Unicode characters into a sequence of bytes. In contrast, decoding is the process of transforming a sequence of encoded bytes into a set of Unicode characters. For information about the Unicode Transformation Formats (UTFs) and other encodings supported by , see [Character Encoding in the .NET Framework](~/docs/standard/base-types/character-encoding.md). - Note that is intended to operate on Unicode characters instead of arbitrary binary data, such as byte arrays. If you must encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + Note that is intended to operate on Unicode characters instead of arbitrary binary data, such as byte arrays. If you must encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . The .NET Framework provides the following implementations of the class to support current Unicode encodings and other encodings: @@ -63,7 +63,7 @@ Use the method to obtain other encodings, and call the method to get a list of all encodings. - The following table lists the encodings supported by the .NET Framework. It lists each encoding's code page number and the values of the encoding's and properties. An asterisk in the last column indicates that the code page is natively supported by the .NET Framework, regardless of the underlying platform. Note that code pages whose property corresponds to an international standard do not necessarily comply in full with that standard. + The following table lists the encodings supported by the .NET Framework. It lists each encoding's code page number and the values of the encoding's and properties. An asterisk in the last column indicates that the code page is natively supported by the .NET Framework, regardless of the underlying platform. Note that code pages whose property corresponds to an international standard do not necessarily comply in full with that standard. |Code page|Name|Display name|.NET Framework support| |---------------|----------|------------------|----------------------------| @@ -480,7 +480,7 @@ object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a big endian object whose fallback is either an or a , as the following example illustrates. + The object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a big endian object whose fallback is either an or a , as the following example illustrates. [!code-csharp[System.Text.Encoding.BigEndianUnicode#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/CS/bigendianunicode1.cs#2)] [!code-vb[System.Text.Encoding.BigEndianUnicode#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.BigEndianUnicode/VB/bigendianunicode1.vb#2)] @@ -545,7 +545,7 @@ ## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. [!code-cpp[System.Text.Encoding.Names#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp#1)] [!code-csharp[System.Text.Encoding.Names#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CS/names.cs#1)] @@ -633,7 +633,7 @@ . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. [!code-cpp[System.Text.Encoding.Names#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp#1)] [!code-csharp[System.Text.Encoding.Names#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CS/names.cs#1)] @@ -870,7 +870,7 @@ ### The Default property in the .NET Framework -In the .NET Framework on the Windows desktop, the property always gets the system's active code page and creates a object that corresponds to it. The active code page may be an ANSI code page, which includes the ASCII character set along with additional characters that vary by code page. Because all encodings based on ANSI code pages lose data, consider using the encoding instead. UTF-8 is often identical in the U+00 to U+7F range, but can encode characters outside the ASCII range without loss. +In the .NET Framework on the Windows desktop, the property always gets the system's active code page and creates a object that corresponds to it. The active code page may be an ANSI code page, which includes the ASCII character set along with additional characters that vary by code page. Because all encodings based on ANSI code pages lose data, consider using the encoding instead. UTF-8 is often identical in the U+00 to U+7F range, but can encode characters outside the ASCII range without loss. ## The Default property on .NET Core @@ -968,7 +968,7 @@ On .NET Core, the property always returns ## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. [!code-cpp[System.Text.Encoding.Names#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp#1)] [!code-csharp[System.Text.Encoding.Names#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CS/names.cs#1)] @@ -1070,7 +1070,7 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size required by to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1082,7 +1082,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, you should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. @@ -1143,7 +1143,7 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size required by to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1155,7 +1155,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. @@ -1228,7 +1228,7 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size that requires to store the resulting bytes, you should call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some considerations for using these methods: @@ -1240,7 +1240,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ]]> @@ -1299,7 +1299,7 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size required by to store the resulting bytes, call the method. To calculate the maximum array size, call the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1311,7 +1311,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. @@ -1404,7 +1404,7 @@ On .NET Core, the property always returns ## Remarks If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1416,7 +1416,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. @@ -1477,7 +1477,7 @@ On .NET Core, the property always returns ## Remarks If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1489,7 +1489,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. @@ -1554,7 +1554,7 @@ On .NET Core, the property always returns ## Remarks If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1566,7 +1566,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. @@ -1677,7 +1677,7 @@ On .NET Core, the property always returns If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1689,7 +1689,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. ]]> @@ -1760,7 +1760,7 @@ On .NET Core, the property always returns If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1772,7 +1772,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. @@ -1859,7 +1859,7 @@ On .NET Core, the property always returns If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. + The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. The method expects discrete conversions, in contrast to the method, which handles multiple conversions on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1871,7 +1871,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the version that supports byte arrays is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible, and does throw an exception if the output buffer is too small. For continuous encoding of a stream, this method is often the best choice. @@ -1948,7 +1948,7 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size required by to store the resulting characters, you should use the method. To calculate the maximum array size, you should use the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -1960,7 +1960,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the [\], Int32, Int32, Char\ version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -2033,7 +2033,7 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size that requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -2045,7 +2045,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the [\], Int32, Int32, Char\ version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ]]> @@ -2104,7 +2104,7 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size required by to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: @@ -2116,7 +2116,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the [\], Int32, Int32, Char\ version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -2187,17 +2187,17 @@ On .NET Core, the property always returns gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - **Note** This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + **Note** This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. @@ -2205,7 +2205,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the [\], Int32, Int32, Char\ version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -2268,17 +2268,17 @@ On .NET Core, the property always returns gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - **Note** This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + **Note** This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - If your app handles string outputs, it is recommended to use the method. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. @@ -2286,7 +2286,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the [\], Int32, Int32, Char\ version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -2369,17 +2369,17 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size that requires to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + gets characters from an input byte sequence. is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the object provided by the or the method, respectively, of a derived class. - **Note** This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + **Note** This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one call and continue at the beginning of the next call. will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. @@ -2387,7 +2387,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the [\], Int32, Int32, Char\ version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. ]]> @@ -2456,17 +2456,17 @@ On .NET Core, the property always returns ## Remarks To calculate the exact array size required by to store the resulting characters, you should use the method. To calculate the maximum array size, use the method. The method generally allows allocation of less memory, while the method generally executes faster. - [\], Int32, Int32, Char\ gets characters from an input byte sequence. [\], Int32, Int32, Char\ is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. + [\], Int32, Int32, Char\ gets characters from an input byte sequence. [\], Int32, Int32, Char\ is different than because expects discrete conversions, while is designed for multiple passes on a single input stream. If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - **Note** This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . + **Note** This method is intended to operate on Unicode characters, not on arbitrary binary data, such as byte arrays. If you need to encode arbitrary binary data into text, you should use a protocol such as uuencode, which is implemented by methods such as . - The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. + The method determines how many characters result in decoding a sequence of bytes, and the method performs the actual decoding. The method expects discrete conversions, in contrast to the method, which handles multiple passes on a single input stream. Several versions of and are supported. The following are some programming considerations for use of these methods: -- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one [\], Int32, Int32, Char\ call and continue at the beginning of the next [\], Int32, Int32, Char\ call. [\], Int32, Int32, Char\ will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) +- Your app might need to decode multiple input bytes from a code page and process the bytes using multiple calls. In this case, you probably need to maintain state between calls, because byte sequences can be interrupted when processed in batches. (For example, part of an ISO-2022 shift sequence may end one [\], Int32, Int32, Char\ call and continue at the beginning of the next [\], Int32, Int32, Char\ call. [\], Int32, Int32, Char\ will call the fallback for those incomplete sequences, but will remember those sequences for the next call.) - If your app handles string outputs, the method is recommended. Since this method must check string length and allocate a buffer, it is slightly slower, but the resulting type is to be preferred. @@ -2474,7 +2474,7 @@ On .NET Core, the property always returns - If your app must convert a large amount of data, it should reuse the output buffer. In this case, the [\], Int32, Int32, Char\ version that supports output character buffers is the best choice. -- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. +- Consider using the method instead of . The conversion method converts as much data as possible and throws an exception if the output buffer is too small. For continuous decoding of a stream, this method is often the best choice. @@ -2552,7 +2552,7 @@ On .NET Core, the property always returns method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly decodes byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly decodes byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ]]> @@ -2595,7 +2595,7 @@ On .NET Core, the property always returns method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method of this class. However, a maintains state information between calls so it correctly encodes character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. ]]> @@ -2819,14 +2819,14 @@ You can also supply a value of 0 for the `codepage` argument. Its precise behavi > [!NOTE] > The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on the full .NET Framework on the Windows desktop, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](http://msdn.microsoft.com/library/windows/desktop/dd318070.aspx) function from the .NET Framework on the Windows desktop. + To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on the full .NET Framework on the Windows desktop, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](http://msdn.microsoft.com/library/windows/desktop/dd318070.aspx) function from the .NET Framework on the Windows desktop. returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. ## Examples - The following example demonstrates the method. + The following example demonstrates the method. [!code-cpp[sys.txt.fallbackEncRpl#1](~/samples/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp#1)] [!code-csharp[sys.txt.fallbackEncRpl#1](~/samples/snippets/csharp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cs/fallEncRpl.cs#1)] @@ -2896,7 +2896,7 @@ You can also supply a value of 0 for the `codepage` argument. Its precise behavi ## Examples - The following example demonstrates the method. + The following example demonstrates the method. [!code-cpp[sys.txt.fallbackEncRpl#1](~/samples/snippets/cpp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cpp/fallEncRpl.cpp#1)] [!code-csharp[sys.txt.fallbackEncRpl#1](~/samples/snippets/csharp/VS_Snippets_CLR/sys.txt.fallbackEncRpl/cs/fallEncRpl.cs#1)] @@ -3043,7 +3043,7 @@ You can also supply a value of 0 for the `codepage` argument. Its precise behavi retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values, particularly in cases where the worst case for the encoding involves switching modes for every character. For example, this can happen for ISO-2022-JP. For more information, see the blog entry "[What's with Encoding.GetMaxByteCount() and Encoding.GetMaxCharCount()?](http://go.microsoft.com/fwlink/?LinkId=153702)" (http://blogs.msdn.com/shawnste/archive/2005/03/02/383903.aspx). - In most cases, this method retrieves reasonable values for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. You might also want to consider a different approach using or . + In most cases, this method retrieves reasonable values for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case when a more reasonable buffer is too small. You might also want to consider a different approach using or . When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. @@ -3116,11 +3116,11 @@ You can also supply a value of 0 for the `codepage` argument. Its precise behavi retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, retrieves large values. - In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is too small. You might also want to consider a different approach using or . + In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is too small. You might also want to consider a different approach using or . has no relation to . If you needs a similar function to use with , you should use . - When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. + When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. Note that considers the worst case for leftover bytes from a previous encoder operation. For most code pages, passing a value of 0 to this method retrieves values greater than or equal to 1. @@ -3264,14 +3264,14 @@ You can also supply a value of 0 for the `codepage` argument. Its precise behavi ## Remarks If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in the .NET Framework](~/docs/standard/base-types/character-encoding.md) topic. ## Examples - The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + The following example reads a UTF-8 encoded string from a binary file represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. [!code-csharp[System.Text.Encoding.GetString#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.GetString/CS/getstring1.cs#2)] [!code-vb[System.Text.Encoding.GetString#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring1.vb#2)] @@ -3354,7 +3354,7 @@ The goal is to save this file, then open and decode it as a binary stream. If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the object returned by the method of a derived class. - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. Note that the precise behavior of the method for a particular implementation depends on the fallback strategy defined for that object. For more information, see the "Choosing a Fallback Strategy" section of the [Character Encoding in the .NET Framework](~/docs/standard/base-types/character-encoding.md) topic. @@ -3414,12 +3414,12 @@ The goal is to save this file, then open and decode it as a binary stream. ## Remarks If the data to be converted is available only in sequential blocks (such as data read from a stream) or if the amount of data is so large that it needs to be divided into smaller blocks, you should use the or the provided by the method or the method, respectively, of a derived class. - See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. + See the Remarks section of the reference topic for a discussion of decoding techniques and considerations. ## Examples - The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. + The following example reads a UTF-8 encoded string from a binary file that is represented by a object. For files that are smaller than 2,048 bytes, it reads the contents of the entire file into a byte array and calls the method to perform the decoding. For larger files, it reads 2,048 bytes at a time into a byte array, calls the method to determine how many characters are contained in the array, and then calls the method to perform the decoding. [!code-csharp[System.Text.Encoding.GetString#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.GetString/CS/getstring2.cs#3)] [!code-vb[System.Text.Encoding.GetString#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.Encoding.GetString/VB/getstring2.vb#3)] @@ -3496,7 +3496,7 @@ The goal is to save this file, then open and decode it as a binary stream. ## Examples - The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. [!code-cpp[System.Text.Encoding.Names#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp#1)] [!code-csharp[System.Text.Encoding.Names#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CS/names.cs#1)] @@ -3821,7 +3821,7 @@ The goal is to save this file, then open and decode it as a binary stream. For a single-byte encoding, for example, , this property retrieves `true`. > [!CAUTION] -> You should be careful in what your application does with the value for . An assumption of how an Encoding will proceed may still be wrong. For example, Windows-1252 has a value of `true` for , but Encoding.GetMaxByteCount(1) returns 2. This is because the method considers potential leftover surrogates from a previous decoder operation. +> You should be careful in what your application does with the value for . An assumption of how an Encoding will proceed may still be wrong. For example, Windows-1252 has a value of `true` for , but Encoding.GetMaxByteCount(1) returns 2. This is because the method considers potential leftover surrogates from a previous decoder operation. @@ -3876,13 +3876,13 @@ The goal is to save this file, then open and decode it as a binary stream. method allows you to register a class derived from that makes character encodings available on a platform that does not otherwise support them. Once the encoding provider is registered, the encodings that it supports can be retrieved by calling any overload. If there are multiple encoding providers, the method attempts to retrieve a specified encoding from each provider starting with the one most recently registered. + The method allows you to register a class derived from that makes character encodings available on a platform that does not otherwise support them. Once the encoding provider is registered, the encodings that it supports can be retrieved by calling any overload. If there are multiple encoding providers, the method attempts to retrieve a specified encoding from each provider starting with the one most recently registered. Registering an encoding provider by using the method also modifies the behavior of the [Encoding.GetEncoding(Int32)]() and [EncodingProvider.GetEncoding(Int32, EncoderFallback, DecoderFallback)](xref:System.Text.Encoding.GetEncoding(System.Int32,System.Text.EncoderFallback,System.Text.DecoderFallback)) methods when passed an argument of `0`: - If the registered provider is the , the method returns the encoding that matches the system active code page when running on the Windows operating system. -- A custom encoding provider can choose which encoding to return when either of these method overloads is passed an argument of `0`. The provider can also choose to not return an encoding by having the method return `null`. +- A custom encoding provider can choose which encoding to return when either of these method overloads is passed an argument of `0`. The provider can also choose to not return an encoding by having the method return `null`. [!INCLUDE[net_v46](~/includes/net-v46-md.md)] includes one encoding provider, , that makes the encodings available that are present in the full .NET Framework but are not available in [!INCLUDE[net_v46](~/includes/net-v46-md.md)]. By default, [!INCLUDE[net_v46](~/includes/net-v46-md.md)] only supports the Unicode encodings, ASCII, and code page 28591. @@ -3931,7 +3931,7 @@ Registering an encoding provider by using the object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a little endian object whose fallback is either an or a , as the following example illustrates. + The object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a little endian object whose fallback is either an or a , as the following example illustrates. [!code-csharp[System.Text.Encoding.Unicode#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.encoding.unicode/cs/unicode1.cs#2)] [!code-vb[System.Text.Encoding.Unicode#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.unicode/vb/unicode1.vb#2)] @@ -3981,7 +3981,7 @@ Registering an encoding provider by using the object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with the Unicode REPLACEMENT CHARACTER (U+FFFE). Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. + The object that is returned by this property may not have the appropriate behavior for your app. It uses replacement fallback to replace each string that it cannot encode and each byte that it cannot decode with the Unicode REPLACEMENT CHARACTER (U+FFFE). Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. [!code-csharp[System.Text.Encoding.UTF32#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.encoding.utf32/cs/encoding.utf32.1.cs#1)] [!code-vb[System.Text.Encoding.UTF32#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf32/vb/encoding.utf32.1.vb#1)] @@ -4089,7 +4089,7 @@ Registering an encoding provider by using the object that provides a Unicode byte order mark (BOM). To instantiate a UTF8 encoding that doesn't provide a BOM, call any overload of the constructor. -- It returns a object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. +- It returns a object that uses replacement fallback to replace each string that it can't encode and each byte that it can't decode with a question mark ("?") character. Instead, you can call the constructor to instantiate a object whose fallback is either an or a , as the following example illustrates. [!code-csharp[System.Text.Encoding.UTF8#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.encoding.utf8/cs/encoding.utf8.1.cs#1)] [!code-vb[System.Text.Encoding.UTF8#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.encoding.utf8/vb/encoding.utf8.1.vb#1)] @@ -4159,7 +4159,7 @@ Registering an encoding provider by using the is the same as the returned by . Some of the web names are duplicates; see the remarks for for more information. + The is the same as the returned by . Some of the web names are duplicates; see the remarks for for more information. @@ -4170,7 +4170,7 @@ Registering an encoding provider by using the . It displays but does not compare against it. + The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. [!code-cpp[System.Text.Encoding.Names#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CPP/names.cpp#1)] [!code-csharp[System.Text.Encoding.Names#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.Encoding.Names/CS/names.cs#1)] diff --git a/xml/System.Text/EncodingInfo.xml b/xml/System.Text/EncodingInfo.xml index 28bec53ad675c..27401953ba7ef 100644 --- a/xml/System.Text/EncodingInfo.xml +++ b/xml/System.Text/EncodingInfo.xml @@ -25,14 +25,14 @@ class. The method returns an array of this type. + This class is primarily used by the class. The method returns an array of this type. This class is intended to provide minimal information about an encoding. To obtain additional information, the application should use the method to get an instance of the class, which contains more comprehensive information about the encoding it represents. ## Examples - The following example uses the method to retrieve an object for each encoding supported by the .NET Framework. It then displays the value of each encoding's , , and property and compares them with the corresponding names. + The following example uses the method to retrieve an object for each encoding supported by the .NET Framework. It then displays the value of each encoding's , , and property and compares them with the corresponding names. [!code-cpp[System.Text.EncodingInfo#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Text.EncodingInfo/CPP/encodinginfo.cpp#1)] [!code-csharp[System.Text.EncodingInfo#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.EncodingInfo/CS/encodinginfo.cs#1)] @@ -70,7 +70,7 @@ . + This member is equivalent to . diff --git a/xml/System.Text/EncodingProvider.xml b/xml/System.Text/EncodingProvider.xml index 2ca364959a75b..0e9a8a65e02d5 100644 --- a/xml/System.Text/EncodingProvider.xml +++ b/xml/System.Text/EncodingProvider.xml @@ -36,21 +36,21 @@ ## Remarks An encoding provider supplies encodings that are not otherwise available on a particular target platform. - The .NET Framework on the Windows desktop supports a large number of character encodings and code pages. You can get a complete list of encodings available in the .NET Framework on the Windows desktop by calling the method. .NET Core, on the other hand, by default supports only the following encodings: + The .NET Framework on the Windows desktop supports a large number of character encodings and code pages. You can get a complete list of encodings available in the .NET Framework on the Windows desktop by calling the method. .NET Core, on the other hand, by default supports only the following encodings: -- ASCII (code page 20127), which is returned by the property. +- ASCII (code page 20127), which is returned by the property. - ISO-8859-1 (code page 28591). -- UTF-7 (code page 65000), which is returned by the property. +- UTF-7 (code page 65000), which is returned by the property. -- UTF-8 (code page 65001), which is returned by the property. +- UTF-8 (code page 65001), which is returned by the property. - UTF-16 and UTF-16LE (code page 1200), which is returned by the property. -- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. +- UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. -- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. +- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. - UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. @@ -60,11 +60,11 @@ 2. Optionally, you can override the virtual and methods. In most cases, this is not necessary, since the base class provides a default implementation. -3. Pass the instance to the method to make the encodings supplied by the object available to the common language runtime. +3. Pass the instance to the method to make the encodings supplied by the object available to the common language runtime. -4. Call an overload to retrieve the encoding. The method will call the corresponding to determine whether it can supply the requested encoding. +4. Call an overload to retrieve the encoding. The method will call the corresponding to determine whether it can supply the requested encoding. - The .NET Framework Class Library provides one static property, , that returns an object that makes the full set of encodings available on the desktop .NET Framework Class Library available to [!INCLUDE[net_core](~/includes/net-core-md.md)] applications. In addition, you can derive from the class to make your own encodings available. + The .NET Framework Class Library provides one static property, , that returns an object that makes the full set of encodings available on the desktop .NET Framework Class Library available to [!INCLUDE[net_core](~/includes/net-core-md.md)] applications. In addition, you can derive from the class to make your own encodings available. ]]> @@ -239,7 +239,7 @@ This method is called by the [Encoding.GetEncoding(String)](, or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. -- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the default constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. +- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the default constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. - Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. @@ -297,7 +297,7 @@ This method is called by the [Encoding.GetEncoding(String)](, or the `decoderExceptionFallback` argument is an instance of , the encoding method throws an exception if characters cannot be encoded, and the decoding method throws an exception if a byte sequence cannot be decoded. -- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the default constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. +- Replacement fallback. If the `encoderFallback` argument is an instance of , or the `decoderExceptionFallback` argument is an instance of , the encoding and decoding methods substitute a replacement string for characters that cannot be encoded and byte sequences cannot be decoded. If you instantiated the replacement fallback object by calling the default constructor, the replacement character is a "?". If you call the or constructor, you can specify the replacement string. - Best-fit fallback. You can derive from the or class to implement a best-fit replacement mechanism. diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index b7aa80779abfb..b3d4df095665a 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -74,7 +74,7 @@ ## The String and StringBuilder types Although and both represent sequences of characters, they are implemented differently. is an immutable type. That is, each operation that appears to modify a object actually creates a new string. - For example, the call to the method in the following C# example appears to change the value of a string variable named `value`. In fact, the method returns a `value` object that has a different value and address from the `value` object that was passed to the method. Note that the example must be compiled using the `/unsafe` compiler option. + For example, the call to the method in the following C# example appears to change the value of a string variable named `value`. In fact, the method returns a `value` object that has a different value and address from the `value` object that was passed to the method. Note that the example must be compiled using the `/unsafe` compiler option. [!code-csharp[System.Text.StringBuilder.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.stringbuilder.class/cs/immutability2.cs#1)] @@ -99,7 +99,7 @@ ## How StringBuilder works - The property indicates the number of characters the object currently contains. If you add characters to the object, its length increases until it equals the size of the property, which defines the number of characters that the object can contain. If the number of added characters causes the length of the object to exceed its current capacity, new memory is allocated, the value of the property is doubled, new characters are added to the object, and its property is adjusted. Additional memory for the object is allocated dynamically until it reaches the value defined by the property. When the maximum capacity is reached, no further memory can be allocated for the object, and trying to add characters or expand it beyond its maximum capacity throws either an or an exception. + The property indicates the number of characters the object currently contains. If you add characters to the object, its length increases until it equals the size of the property, which defines the number of characters that the object can contain. If the number of added characters causes the length of the object to exceed its current capacity, new memory is allocated, the value of the property is doubled, new characters are added to the object, and its property is adjusted. Additional memory for the object is allocated dynamically until it reaches the value defined by the property. When the maximum capacity is reached, no further memory can be allocated for the object, and trying to add characters or expand it beyond its maximum capacity throws either an or an exception. The following example illustrates how a object allocates new memory and increases its capacity dynamically as the string assigned to the object expands. The code creates a object by calling its default (parameterless) constructor. The default capacity of this object is 16 characters, and its maximum capacity is more than 2 billion characters. Appending the string "This is a sentence." results in a new memory allocation because the string length (19 characters) exceeds the default capacity of the object. The capacity of the object doubles to 32 characters, the new string is added, and the length of the object now equals 19 characters. The code then appends the string "This is an additional sentence." to the value of the object 11 times. Whenever the append operation causes the length of the object to exceed its capacity, its existing capacity is doubled and the operation succeeds. @@ -108,15 +108,15 @@ ## Memory allocation - The default capacity of a object is 16 characters, and its default maximum capacity is . These default values are used if you call the and constructors. + The default capacity of a object is 16 characters, and its default maximum capacity is . These default values are used if you call the and constructors. You can explicitly define the initial capacity of a object in the following ways: - By calling any of the constructors that includes a `capacity` parameter when you create the object. -- By explicitly assigning a new value to the property to expand an existing object. Note that the property throws an exception if the new capacity is less than the existing capacity or greater than the object's maximum capacity. +- By explicitly assigning a new value to the property to expand an existing object. Note that the property throws an exception if the new capacity is less than the existing capacity or greater than the object's maximum capacity. -- By calling the method with the new capacity. The new capacity must not be greater than the object's maximum capacity. However, unlike an assignment to the property, does not throw an exception if the desired new capacity is less than the existing capacity; in this case, the method call has no effect. +- By calling the method with the new capacity. The new capacity must not be greater than the object's maximum capacity. However, unlike an assignment to the property, does not throw an exception if the desired new capacity is less than the existing capacity; in this case, the method call has no effect. If the length of the string assigned to the object in the constructor call exceeds either the default capacity or the specified capacity, the property is set to the length of the string specified with the `value` parameter. @@ -128,19 +128,19 @@ - If the eventual size of the object is likely to grow exceedingly large, typically in excess of several megabytes. In this case, there may be some performance benefit from setting the initial property to a significantly high value to eliminate the need for too many memory reallocations. -- If your app is running on a system with limited memory. In this case, you may want to consider setting the property to less than if your app is handling large strings that may cause it to execute in a memory-constrained environment. +- If your app is running on a system with limited memory. In this case, you may want to consider setting the property to less than if your app is handling large strings that may cause it to execute in a memory-constrained environment. ## Instantiating a StringBuilder object - You instantiate a object by calling one of its six overloaded class constructors, which are listed in the following table. Three of the constructors instantiate a object whose value is an empty string, but set its and values differently. The remaining three constructors define a object that has a specific string value and capacity. Two of the three constructors use the default maximum capacity of , whereas the third allows you to set the maximum capacity. + You instantiate a object by calling one of its six overloaded class constructors, which are listed in the following table. Three of the constructors instantiate a object whose value is an empty string, but set its and values differently. The remaining three constructors define a object that has a specific string value and capacity. Two of the three constructors use the default maximum capacity of , whereas the third allows you to set the maximum capacity. |Constructor|String value|Capacity|Maximum capacity| |-----------------|------------------|--------------|----------------------| -|||16|| -|||Defined by the `capacity` parameter|| -|||Defined by the `capacity` parameter|Defined by the `maxCapacity` parameter| -||Defined by the `value` parameter|16 or `value`. , whichever is greater|| -||Defined by the `value` parameter|Defined by the `capacity` parameter or `value`. , whichever is greater.|| +|||16|| +|||Defined by the `capacity` parameter|| +|||Defined by the `capacity` parameter|Defined by the `maxCapacity` parameter| +||Defined by the `value` parameter|16 or `value`. , whichever is greater|| +||Defined by the `value` parameter|Defined by the `capacity` parameter or `value`. , whichever is greater.|| ||Defined by `value`. (`startIndex`, `length`)|Defined by the `capacity` parameter or `value`. , whichever is greater.|Defined by the `maxCapacity` parameter| The following example uses three of these constructor overloads to instantiate objects. @@ -168,9 +168,9 @@ ### Iterating StringBuilder characters - You can access the characters in a object by using the property. In C#, is an indexer; in Visual Basic, it is the default property of the class. This enables you to set or retrieve individual characters by using their index only, without explicitly referencing the property. Characters in a object begin at index 0 (zero) and continue to index - 1. + You can access the characters in a object by using the property. In C#, is an indexer; in Visual Basic, it is the default property of the class. This enables you to set or retrieve individual characters by using their index only, without explicitly referencing the property. Characters in a object begin at index 0 (zero) and continue to index - 1. - The following example illustrates the property. It appends ten random numbers to a object, and then iterates each character. If the character's Unicode category is , it decreases the number by 1 (or changes the number to 9 if its value is 0). The example displays the contents of the object both before and after the values of individual characters were changed. + The following example illustrates the property. It appends ten random numbers to a object, and then iterates each character. If the character's Unicode category is , it decreases the number by 1 (or changes the number to 9 if its value is 0). The example displays the contents of the object both before and after the values of individual characters were changed. [!code-csharp[System.Text.StringBuilder.Class#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.stringbuilder.class/cs/chars1.cs#7)] [!code-vb[System.Text.StringBuilder.Class#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/chars1.vb#7)] @@ -203,14 +203,14 @@ ### Modifying the text in a StringBuilder object - The method replaces all occurrences of a character or a string in the entire object or in a particular character range. The following example uses the method to replace all exclamation points (!) with question marks (?) in the object. + The method replaces all occurrences of a character or a string in the entire object or in a particular character range. The following example uses the method to replace all exclamation points (!) with question marks (?) in the object. [!code-csharp[System.Text.StringBuilder.Class#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.stringbuilder.class/cs/replace1.cs#11)] [!code-vb[System.Text.StringBuilder.Class#11](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/replace1.vb#11)] ## Searching the text in a StringBuilder object - The class does not include methods similar to the , , and methods provided by the class, which allow you to search the object for a particular character or a substring. Determining the presence or starting character position of a substring requires that you search a value by using either a string search method or a regular expression method. There are four ways to implement such searches, as the following table shows. + The class does not include methods similar to the , , and methods provided by the class, which allow you to search the object for a particular character or a substring. Determining the presence or starting character position of a substring requires that you search a value by using either a string search method or a regular expression method. There are four ways to implement such searches, as the following table shows. |Technique|Pros|Cons| |---------------|----------|----------| @@ -226,7 +226,7 @@ [!code-csharp[System.Text.StringBuilder.Class#12](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.stringbuilder.class/cs/pattern1.cs#12)] [!code-vb[System.Text.StringBuilder.Class#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern1.vb#12)] -- Call the method to convert the object to a object. You can search the string by using methods such as or , or you can use regular expressions and the class to search for patterns. Because both and objects use UTF-16 encoding to store characters, the index positions of characters, substrings, and regular expression matches are the same in both objects. This enables you to use methods to make changes at the same position at which that text is found in the object. +- Call the method to convert the object to a object. You can search the string by using methods such as or , or you can use regular expressions and the class to search for patterns. Because both and objects use UTF-16 encoding to store characters, the index positions of characters, substrings, and regular expression matches are the same in both objects. This enables you to use methods to make changes at the same position at which that text is found in the object. > [!NOTE] > If you adopt this approach, you should work from the end of the object to its beginning so that you don't have to repeatedly convert the object to a string. @@ -236,23 +236,23 @@ [!code-csharp[System.Text.StringBuilder.Class#13](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.stringbuilder.class/cs/pattern2.cs#13)] [!code-vb[System.Text.StringBuilder.Class#13](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern2.vb#13)] -- Use the property to sequentially search a range of characters in a object. This approach may not be practical if the number of characters to be searched is large or the search logic is particularly complex. +- Use the property to sequentially search a range of characters in a object. This approach may not be practical if the number of characters to be searched is large or the search logic is particularly complex. The following example is identical in functionality to the previous example but differs in implementation. It uses the property to detect when a character value has changed, inserts an underscore at that position, and converts the first character in the new sequence to uppercase. [!code-csharp[System.Text.StringBuilder.Class#14](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.stringbuilder.class/cs/pattern3.cs#14)] [!code-vb[System.Text.StringBuilder.Class#14](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern3.vb#14)] -- Store all the unmodified text in the object, call the method to convert the object to a object, and perform the modifications on the object. You can use this approach if you have only a few modifications; otherwise, the cost of working with immutable strings may negate the performance benefits of using a object. +- Store all the unmodified text in the object, call the method to convert the object to a object, and perform the modifications on the object. You can use this approach if you have only a few modifications; otherwise, the cost of working with immutable strings may negate the performance benefits of using a object. - The following example is identical in functionality to the previous two examples but differs in implementation. It creates a object, converts it to a object, and then uses a regular expression to perform all remaining modifications on the string. The method uses a lambda expression to perform the replacement on each match. + The following example is identical in functionality to the previous two examples but differs in implementation. It creates a object, converts it to a object, and then uses a regular expression to perform all remaining modifications on the string. The method uses a lambda expression to perform the replacement on each match. [!code-csharp[System.Text.StringBuilder.Class#15](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.stringbuilder.class/cs/pattern4.cs#15)] [!code-vb[System.Text.StringBuilder.Class#15](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.class/vb/pattern4.vb#15)] ## Converting the StringBuilder object to a string - You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You perform this conversion by calling the method. For an illustration, see the previous example, which calls the method to convert a object to a string so that it can be passed to a regular expression method. + You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You perform this conversion by calling the method. For an illustration, see the previous example, which calls the method to convert a object to a string so that it can be passed to a regular expression method. @@ -299,7 +299,7 @@ , and the capacity is set to the implementation-specific default capacity. + The string value of this instance is set to , and the capacity is set to the implementation-specific default capacity. @@ -348,7 +348,7 @@ ## Remarks The `capacity` parameter defines the maximum number of characters that can be stored in the memory allocated by the current instance. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. - The string value of this instance is set to . If `capacity` is zero, the implementation-specific default capacity is used. + The string value of this instance is set to . If `capacity` is zero, the implementation-specific default capacity is used. @@ -630,7 +630,7 @@ [!code-csharp[System.Text.StringBuilder.Append#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append2.cs#2)] [!code-vb[System.Text.StringBuilder.Append#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb#2)] - The method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. + The method calls the method to get the string representation of `value`. The capacity of this instance is adjusted as needed. ]]> @@ -843,7 +843,7 @@ [!code-csharp[System.Text.StringBuilder.Append#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append2.cs#8)] [!code-vb[System.Text.StringBuilder.Append#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb#8)] - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -896,7 +896,7 @@ [!code-csharp[System.Text.StringBuilder.Append#9](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append2.cs#9)] [!code-vb[System.Text.StringBuilder.Append#9](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append2.vb#9)] - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -949,7 +949,7 @@ [!code-csharp[System.Text.StringBuilder.Append#10](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append3.cs#10)] [!code-vb[System.Text.StringBuilder.Append#10](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb#10)] - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1002,7 +1002,7 @@ [!code-csharp[System.Text.StringBuilder.Append#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append3.cs#11)] [!code-vb[System.Text.StringBuilder.Append#11](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb#11)] - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1055,7 +1055,7 @@ [!code-csharp[System.Text.StringBuilder.Append#12](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append3.cs#12)] [!code-vb[System.Text.StringBuilder.Append#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb#12)] - The method calls the to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1108,7 +1108,7 @@ [!code-csharp[System.Text.Stringbuilder.Append#18](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append4.cs#18)] [!code-vb[System.Text.Stringbuilder.Append#18](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append4.vb#18)] - The method calls the method to get the string representation of `value`. If `value` is `null`, no changes are made to the object. + The method calls the method to get the string representation of `value`. If `value` is `null`, no changes are made to the object. The capacity of this instance is adjusted as needed. @@ -1166,7 +1166,7 @@ [!code-csharp[System.Text.StringBuilder.Append#13](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append3.cs#13)] [!code-vb[System.Text.StringBuilder.Append#13](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb#13)] - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1219,7 +1219,7 @@ [!code-csharp[System.Text.StringBuilder.Append#14](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append3.cs#14)] [!code-vb[System.Text.StringBuilder.Append#14](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb#14)] - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1335,7 +1335,7 @@ [!code-csharp[System.Text.StringBuilder.Append#15](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append3.cs#15)] [!code-vb[System.Text.StringBuilder.Append#15](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb#15)] - The method calls the method to get the string representation of `value`. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value`. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1393,7 +1393,7 @@ [!code-csharp[System.Text.StringBuilder.Append#16](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append3.cs#16)] [!code-vb[System.Text.StringBuilder.Append#16](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb#16)] - The calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1451,7 +1451,7 @@ [!code-csharp[System.Text.StringBuilder.Append#17](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/cs/append3.cs#17)] [!code-vb[System.Text.StringBuilder.Append#17](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Text.StringBuilder.Append/vb/append3.vb#17)] - The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. + The method calls the method to get the string representation of `value` for the current culture. To control the formatting of `value`, call the method. The capacity of this instance is adjusted as needed. @@ -1790,7 +1790,7 @@ |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -1882,7 +1882,7 @@ |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -1968,7 +1968,7 @@ |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . In this case, since the method has a single argument in the argument list, the value of *index* must always be 0. If it is not, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . In this case, since the method has a single argument in the argument list, the value of *index* must always be 0. If it is not, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -2071,7 +2071,7 @@ |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -2086,7 +2086,7 @@ - A object that provides culture-specific formatting information for date and time values in `args`. -- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. +- A custom implementation that provides formatting information for one or more of the objects in `args`. Typically, such an implementation also implements the interface. The second example in the next section illustrates an method call with a custom implementation. If the `provider` parameter is `null`, format provider information is obtained from the current culture. @@ -2101,7 +2101,7 @@ [!code-csharp[stringbuilder.appendformat#1](~/samples/snippets/csharp/VS_Snippets_CLR/stringbuilder.appendformat/CS/appfmt.cs#1)] [!code-vb[stringbuilder.appendformat#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/stringbuilder.appendformat/VB/appfmt.vb#1)] - The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. + The following example defines a custom implementation named `CustomerFormatter` that formats a 10-digit customer number with hyphens after the fourth and seventh digits. It is passed to the method to create a string that includes the formatted customer number and customer name. [!code-csharp[System.Text.StringBuilder.AppendFormat#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/cs/customernumberformatter1.cs#1)] [!code-vb[System.Text.StringBuilder.AppendFormat#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.stringbuilder.appendformat/vb/customernumberformatter1.vb#1)] @@ -2172,7 +2172,7 @@ |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -2260,7 +2260,7 @@ |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -2357,7 +2357,7 @@ |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -2447,7 +2447,7 @@ |Element|Description| |-------------|-----------------| -|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| +|*index*|The zero-based position in the parameter list of the object to be formatted. If the object specified by *index* is `null`, the format item is replaced by . If there is no parameter in the *index* position, a is thrown.| |,*length*|The minimum number of characters in the string representation of the parameter. If positive, the parameter is right-aligned; if negative, it is left-aligned.| |:*formatString*|A standard or custom format string that is supported by the parameter.| @@ -2706,7 +2706,7 @@ property. + The default line terminator is the current value of the property. The capacity of this instance is adjusted as needed. @@ -2768,7 +2768,7 @@ property. + The default line terminator is the current value of the property. The capacity of this instance is adjusted as needed. @@ -3156,7 +3156,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. @@ -3215,7 +3215,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -3279,7 +3279,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -3399,7 +3399,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -3458,7 +3458,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -3517,7 +3517,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -3576,7 +3576,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -3635,7 +3635,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -3694,7 +3694,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. If `value` is `null`, the value of this instance is unchanged. @@ -3760,7 +3760,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity is adjusted as needed. @@ -3819,7 +3819,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -3949,7 +3949,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -4013,7 +4013,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -4077,7 +4077,7 @@ is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. + is used to get a string representation of `value`. Existing characters are shifted to make room for the new text. The capacity of this instance is adjusted as needed. @@ -4279,7 +4279,7 @@ ## Remarks The length of a object is defined by its number of objects. - Like the property, the property indicates the length of the current string object. Unlike the property, which is read-only, the property allows you to modify the length of the string stored to the object. + Like the property, the property indicates the length of the current string object. Unlike the property, which is read-only, the property allows you to modify the length of the string stored to the object. If the specified length is less than the current length, the current object is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of the current object is padded with the Unicode NULL character (U+0000). @@ -4331,7 +4331,7 @@ . However, this value is implementation-specific and might be different in other or later implementations. You can explicitly set the maximum capacity of a object by calling the constructor. + The maximum capacity for this implementation is . However, this value is implementation-specific and might be different in other or later implementations. You can explicitly set the maximum capacity of a object by calling the constructor. In the[!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)] and the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], when you instantiate the object by calling the constructor, both the length and the capacity of the instance can grow beyond the value of its property. This can occur particularly when you call the and methods to append small strings. @@ -4487,7 +4487,7 @@ , all occurrences of `oldValue` are removed. + This method performs an ordinal, case-sensitive comparison to identify occurrences of `oldValue` in the current instance. If `newValue` is `null` or , all occurrences of `oldValue` are removed. @@ -4611,7 +4611,7 @@ , all occurrences of `oldValue` are removed. + This method performs an ordinal, case-sensitive comparison to identify occurrences of `oldValue` in the specified substring. If `newValue` is `null` or , all occurrences of `oldValue` are removed. @@ -4679,7 +4679,7 @@ ## Remarks The `context` parameter is reserved for future use and does not participate in this operation. - For more information, see the method. + For more information, see the method. ]]> diff --git a/xml/System.Text/UTF32Encoding.xml b/xml/System.Text/UTF32Encoding.xml index cd4facd0e8826..2ecf73fe37472 100644 --- a/xml/System.Text/UTF32Encoding.xml +++ b/xml/System.Text/UTF32Encoding.xml @@ -44,7 +44,7 @@ - Little endian byte order: 41 00 00 00 - It is generally more efficient to store Unicode characters using the native byte order. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. corresponds to the Windows code pages 12000 (little endian byte order) and 12001 (big endian byte order). You can determine the "endianness" of a particular architecture by calling the method. + It is generally more efficient to store Unicode characters using the native byte order. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. corresponds to the Windows code pages 12000 (little endian byte order) and 12001 (big endian byte order). You can determine the "endianness" of a particular architecture by calling the method. Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF of a byte array. @@ -56,10 +56,10 @@ |Member|Endianness|BOM|Error detection| |------------|----------------|---------|---------------------| -||Little-endian|Yes|No (Replacement fallback)| -||Little-endian|Yes|No (Replacement fallback)| -||Configurable|Configurable|No (Replacement fallback)| -||Configurable|Configurable|Configurable| +||Little-endian|Yes|No (Replacement fallback)| +||Little-endian|Yes|No (Replacement fallback)| +||Configurable|Configurable|No (Replacement fallback)| +||Configurable|Configurable|Configurable| The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. @@ -221,7 +221,7 @@ . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. + If `throwOnInvalidCharacters` is `true`, a method that detects an invalid byte sequence throws . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. > [!NOTE] > For security reasons, you should enable error detection by calling the constructor and setting its `throwOnInvalidCharacters` argument to `true`. @@ -968,7 +968,7 @@ With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. @@ -1045,7 +1045,7 @@ With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application uses the or the provided by the method or the method, respectively. @@ -1118,7 +1118,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor was set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. @@ -1165,7 +1165,7 @@ method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high-surrogate, and the matching low-surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high-surrogate, and the matching low-surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor was set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. @@ -1248,7 +1248,7 @@ is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach and use or . + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach and use or . has no relationship to . If you need a similar function to use with , use . @@ -1385,7 +1385,7 @@ You can instantiate a object whose method returns a valid BOM in the following ways: -- By retrieving the object returned by the property. +- By retrieving the object returned by the property. - By calling the parameterless constructor to instantiate a object. @@ -1466,7 +1466,7 @@ ## Remarks With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM), and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM), and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. diff --git a/xml/System.Text/UTF7Encoding.xml b/xml/System.Text/UTF7Encoding.xml index c10d4b1677a61..7cf53026c5b25 100644 --- a/xml/System.Text/UTF7Encoding.xml +++ b/xml/System.Text/UTF7Encoding.xml @@ -88,7 +88,7 @@ constructor is equivalent to calling the constructor that takes an `allowOptionals` parameter and specifying `false` for that parameter. + This constructor creates an instance that does not allow optional characters. Calling the constructor is equivalent to calling the constructor that takes an `allowOptionals` parameter and specifying `false` for that parameter. If an instance allows optional characters, Unicode code points are encoded with a corresponding optional character instead of a modified base 64 character. The optional characters are exclamation point ("!"), backward slash ("\\"), vertical line ("|"), double quote ("""), number sign ("#"), dollar sign ("$"), percent sign ("%"), ampersand ("&"), asterisk ("*"), semicolon (";"), left angle bracket ("\<"), right angle bracket (">"), left curly bracket ("{"), right curly bracket ("}"), left square bracket ("["), right square bracket ("]"), equal sign ("="), at sign ("@"), circumflex accent ("^"), underscore ("_"), and grave accent ("`"). @@ -999,7 +999,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. @@ -1044,7 +1044,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. @@ -1137,7 +1137,7 @@ is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . While UTF-7 is very efficient at encoding ASCII data, one byte per character, it is extremely inefficient for other data. As remarked above, deals with a worst case. If the data to be encoded is largely ASCII, and especially if the ASCII characters cluster together, UTF-7 is significantly more efficient than the number returned by this method suggests. + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . While UTF-7 is very efficient at encoding ASCII data, one byte per character, it is extremely inefficient for other data. As remarked above, deals with a worst case. If the data to be encoded is largely ASCII, and especially if the ASCII characters cluster together, UTF-7 is significantly more efficient than the number returned by this method suggests. has no relation to . If your application needs a similar function to use with , it should use . @@ -1205,7 +1205,7 @@ is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . has no relation to . If your application needs a similar function to use with , it should use . diff --git a/xml/System.Text/UTF8Encoding.xml b/xml/System.Text/UTF8Encoding.xml index 21411f78c5221..c9b724a00b6aa 100644 --- a/xml/System.Text/UTF8Encoding.xml +++ b/xml/System.Text/UTF8Encoding.xml @@ -40,10 +40,10 @@ |Member|BOM|Error detection| |------------|---------|---------------------| -||Yes|No (Replacement fallback)| -||No|No (Replacement fallback)| -||Configurable|No (Replacement fallback)| -||Configurable|Configurable| +||Yes|No (Replacement fallback)| +||No|No (Replacement fallback)| +||Configurable|No (Replacement fallback)| +||Configurable|Configurable| The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. @@ -211,7 +211,7 @@ ## Remarks The `encoderShouldEmitUTF8Identifier` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-8 format. If `false`, it returns a zero-length byte array. However, setting `encoderShouldEmitUTF8Identifier` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. - If `throwOnInvalidBytes` is `true`, a method that detects an invalid byte sequence throws an exception. Otherwise, the method does not throw an exception, and the invalid sequence is ignored. + If `throwOnInvalidBytes` is `true`, a method that detects an invalid byte sequence throws an exception. Otherwise, the method does not throw an exception, and the invalid sequence is ignored. > [!NOTE] > For security reasons, you should enable error detection by calling a constructor that includes a `throwOnInvalidBytes` parameter and setting that parameter to `true`. @@ -971,7 +971,7 @@ With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the object provided by the method or the method, respectively. @@ -1049,7 +1049,7 @@ With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. @@ -1123,7 +1123,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the method of this class. However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. @@ -1171,7 +1171,7 @@ method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes, in a manner similar to the method. However, a maintains state information between calls so it can correctly encode character sequences that span blocks. The also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidCharacters` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. @@ -1267,7 +1267,7 @@ is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . For example, text in English and many other languages often needs only one UTF-8 byte to represent a character, but the number returned by has to allow for the possibility that the string to be converted will consist entirely of characters that each require four bytes. + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . For example, text in English and many other languages often needs only one UTF-8 byte to represent a character, but the number returned by has to allow for the possibility that the string to be converted will consist entirely of characters that each require four bytes. has no relation to . If your application needs a similar function to use with , it should use . @@ -1336,7 +1336,7 @@ is a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + In most cases, this method returns reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . has no relation to . If your application needs a similar function to use with , it should use . @@ -1402,7 +1402,7 @@ You can instantiate a object whose method returns a valid BOM in the following ways: -- By retrieving the object returned by the property. +- By retrieving the object returned by the property. - By calling a constructor with a `encoderShouldEmitUTF8Identifier` parameter and setting its value set to `true`. @@ -1487,7 +1487,7 @@ ## Remarks With error detection, an invalid sequence causes this method to throw an exception. Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, use the or the provided by the method or the method, respectively. @@ -1499,7 +1499,7 @@ [!code-csharp[System.Text.UTF8Encoding.GetString#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.utf8encoding.getstring/cs/getstring1.cs#1)] [!code-vb[System.Text.UTF8Encoding.GetString#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getstring/vb/getstring1.vb#1)] - Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. + Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. ]]> diff --git a/xml/System.Text/UnicodeEncoding.xml b/xml/System.Text/UnicodeEncoding.xml index 249f3e76442a9..8bd7fed64209a 100644 --- a/xml/System.Text/UnicodeEncoding.xml +++ b/xml/System.Text/UnicodeEncoding.xml @@ -50,7 +50,7 @@ - Little endian byte order: 41 00 00 00 - It is generally more efficient to store Unicode characters using the native byte order of a particular platform. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. The class corresponds to the Windows code pages 1200 (little endian byte order) and 1201 (big endian byte order). You can determine the "endianness" of a particular architecture by calling the method. + It is generally more efficient to store Unicode characters using the native byte order of a particular platform. For example, it is better to use the little endian byte order on little endian platforms, such as Intel computers. The class corresponds to the Windows code pages 1200 (little endian byte order) and 1201 (big endian byte order). You can determine the "endianness" of a particular architecture by calling the method. Optionally, the object provides a byte order mark (BOM), which is an array of bytes that can be prefixed to the sequence of bytes resulting from the encoding process. If the preamble contains a byte order mark (BOM), it helps the decoder determine the byte order and the transformation format or UTF. @@ -63,10 +63,10 @@ |Member|Endianness|BOM|Error detection| |------------|----------------|---------|---------------------| ||Big-endian|Yes|No (Replacement fallback)| -||Little-endian|Yes|No (Replacement fallback)| -||Little-endian|Yes|No (Replacement fallback)| +||Little-endian|Yes|No (Replacement fallback)| +||Little-endian|Yes|No (Replacement fallback)| ||Configurable|Configurable|No (Replacement fallback)| -||Configurable|Configurable|Configurable| +||Configurable|Configurable|Configurable| The method determines how many bytes result in encoding a set of Unicode characters, and the method performs the actual encoding. @@ -230,7 +230,7 @@ ## Remarks The `byteOrderMark` parameter controls the operation of the method. If `true`, the method returns a byte array containing the Unicode byte order mark (BOM) in UTF-16 format. If `false`, it returns a zero-length byte array. However, setting `byteOrderMark` to `true` does not cause the method to prefix the BOM at the beginning of the byte array, nor does it cause the method to include the number of bytes in the BOM in the byte count. - If the `throwOnInvalidBytes` parameter is `true`, a method that detects an invalid byte sequence throws . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. + If the `throwOnInvalidBytes` parameter is `true`, a method that detects an invalid byte sequence throws . Otherwise, the method does not throw an exception, and the invalid sequence is ignored. > [!NOTE] > For security reasons, your applications are recommended to use this constructor to create an instance of the class and turn on error detection by setting `throwOnInvalidBytes` to `true`. @@ -1036,7 +1036,7 @@ With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. @@ -1114,7 +1114,7 @@ With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the provided by the method or the method, respectively. @@ -1188,7 +1188,7 @@ method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the . However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of bytes into sequential blocks of characters, in a manner similar to the . However, a maintains state information between calls so it can correctly decode byte sequences that span blocks. The also preserves trailing bytes at the end of data blocks and uses the trailing bytes in the next decoding operation. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidBytes` parameter of the constructor is set to `true`, error detection is also enabled in the returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the decoder is undefined and processing must stop. @@ -1241,7 +1241,7 @@ method converts sequential blocks of characters into sequential blocks of bytes in a manner similar to the method of this class. However, a object maintains state information between calls so that it can correctly encode character sequences that span blocks. The object also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. + The method converts sequential blocks of characters into sequential blocks of bytes in a manner similar to the method of this class. However, a object maintains state information between calls so that it can correctly encode character sequences that span blocks. The object also preserves trailing characters at the end of data blocks and uses the trailing characters in the next encoding operation. For example, a data block might end with an unmatched high surrogate, and the matching low surrogate might be in the next data block. Therefore, and are useful for network transmission and file operations, because those operations often deal with blocks of data instead of a complete data stream. If error detection is enabled, that is, the `throwOnInvalidBytes` parameter of the constructor is set to `true`, error detection is also enabled in the object returned by this method. If error detection is enabled and an invalid sequence is encountered, the state of the encoder is undefined and processing must stop. @@ -1326,7 +1326,7 @@ retrieves a worst-case number, including the worst case for the currently selected . If a fallback is chosen with a potentially large string, can return large values. - In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . + In most cases, this method retrieves reasonable numbers for small strings. For large strings, you might have to choose between using very large buffers and catching errors in the rare case that a more reasonable buffer is exceeded. You might also want to consider a different approach using or . has no relation to . If your application needs a similar function to use with , it should use . @@ -1465,7 +1465,7 @@ You can instantiate a object whose method returns a valid BOM in the following ways: -- By retrieving the object returned by the or property. +- By retrieving the object returned by the or property. - By calling the parameterless constructor to instantiate a object. @@ -1548,7 +1548,7 @@ ## Remarks With error detection, an invalid sequence causes this method to throw a . Without error detection, invalid sequences are ignored, and no exception is thrown. - If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. + If the range of bytes to be decoded includes the byte order mark (BOM) and the byte array was returned by a method of a non-BOM aware type, the character U+FFFE is included in the character array returned by this method. You can remove it by calling the method. Data to be converted, such as data read from a stream, might be available only in sequential blocks. In this case, or if the amount of data is so large that it needs to be divided into smaller blocks, the application should use the or the object provided by the or the method, respectively. @@ -1560,7 +1560,7 @@ [!code-csharp[System.Text.UTF8Encoding.GetString#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.text.utf8encoding.getstring/cs/getstring1.cs#1)] [!code-vb[System.Text.UTF8Encoding.GetString#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.text.utf8encoding.getstring/vb/getstring1.vb#1)] - Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. + Note that in this case the decoded string differs from the original string, since it begins with a 16-bit byte order mark U+FFFD. This means that the two strings will compare as unequal, and that if the string is output, the BOM will be displayed as the replacement character "?". To remove the BOM at the beginning of the string, you can call the method. ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml b/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml index 270029890285c..982604474c513 100644 --- a/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml +++ b/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml @@ -35,7 +35,7 @@ ## Remarks > [!NOTE] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](~/includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](~/includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/TransformBlock`2.xml b/xml/System.Threading.Tasks.Dataflow/TransformBlock`2.xml index af3de3471ae15..0ca30ea03bf4d 100644 --- a/xml/System.Threading.Tasks.Dataflow/TransformBlock`2.xml +++ b/xml/System.Threading.Tasks.Dataflow/TransformBlock`2.xml @@ -39,7 +39,7 @@ ## Remarks > [!NOTE] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](~/includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](~/includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/TransformManyBlock`2.xml b/xml/System.Threading.Tasks.Dataflow/TransformManyBlock`2.xml index b04fa96028077..e65529253cadc 100644 --- a/xml/System.Threading.Tasks.Dataflow/TransformManyBlock`2.xml +++ b/xml/System.Threading.Tasks.Dataflow/TransformManyBlock`2.xml @@ -39,7 +39,7 @@ ## Remarks > [!NOTE] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](~/includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](~/includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/WriteOnceBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/WriteOnceBlock`1.xml index 4f04e839cc72f..bf36d3a3274c2 100644 --- a/xml/System.Threading.Tasks.Dataflow/WriteOnceBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/WriteOnceBlock`1.xml @@ -37,7 +37,7 @@ ## Remarks > [!NOTE] -> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](~/includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. +> The TPL Dataflow Library ( namespace) is not distributed with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)]. To install the namespace, open your project in [!INCLUDE[vs_dev11_long](~/includes/vs-dev11-long-md.md)], choose **Manage NuGet Packages** from the Project menu, and search online for the `Microsoft.Tpl.Dataflow` package. ]]> diff --git a/xml/System.Threading.Tasks/Parallel.xml b/xml/System.Threading.Tasks/Parallel.xml index 4772e6d12edcd..6a37d52a200f4 100644 --- a/xml/System.Threading.Tasks/Parallel.xml +++ b/xml/System.Threading.Tasks/Parallel.xml @@ -97,12 +97,12 @@ ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. [!code-csharp[System.Threading.Tasks.ParallelLoopState#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.parallelloopstate/cs/break1.cs#2)] [!code-vb[System.Threading.Tasks.ParallelLoopState#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.parallelloopstate/vb/break1.vb#2)] - Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. ]]> @@ -431,7 +431,7 @@ ## Examples - The following example shows how to use the method with a object: + The following example shows how to use the method with a object: [!code-csharp[System.Threading.Tasks.Parallel#03](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.parallel/cs/parallelfor.cs#03)] [!code-vb[System.Threading.Tasks.Parallel#03](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.parallel/vb/parallelfor.vb#03)] @@ -560,7 +560,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. If `fromInclusive` is greater than or equal to `toExclusive`, then the method returns immediately without performing any iterations. @@ -629,7 +629,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. If `fromInclusive` is greater than or equal to `toExclusive`, then the method returns immediately without performing any iterations. @@ -700,7 +700,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple threads; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. If `fromInclusive` is greater than or equal to `toExclusive`, then the method returns immediately without performing any iterations. @@ -783,7 +783,7 @@ The `localInit` delegate is invoked once for each thread that participates in the loop's execution and returns the initial local state for each of those threads. These initial states are passed to the first `body` invocations on each thread. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each thread returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per thread to perform a final action on each thread's local state. This delegate might be invoked concurrently on multiple threads; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. If `fromInclusive` is greater than or equal to `toExclusive`, then the method returns immediately without performing any iterations. @@ -846,7 +846,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). ]]> @@ -905,7 +905,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). ]]> @@ -964,12 +964,12 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). ## Examples - The following example shows how to implement a range partitioner for use with : + The following example shows how to implement a range partitioner for use with : [!code-csharp[System.Threading.Tasks.Parallel_RangePartitioners#01](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.parallel_rangepartitioners/cs/rangepartitioner.cs#01)] [!code-vb[System.Threading.Tasks.Parallel_RangePartitioners#01](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.parallel_rangepartitioners/vb/rangepart.vb#01)] @@ -1194,7 +1194,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). ]]> @@ -1261,7 +1261,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). ]]> @@ -1324,7 +1324,7 @@ method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). + This overload is provided for scenarios where you want to override the default partitioning scheme. For example, small loop bodies might benefit from partitioning the range. The method expects custom partitioners to support dynamic partitioning. For more information, see [Custom Partitioners for PLINQ and TPL](~/docs/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md) and [How to: Implement Dynamic Partitions](~/docs/standard/parallel-programming/how-to-implement-dynamic-partitions.md). ]]> @@ -1572,7 +1572,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -1642,7 +1642,7 @@ The `localInit` delegate is invoked once for each thread that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -1712,7 +1712,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task’s local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -1781,7 +1781,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per thread to perform a final action on each task’s local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. @@ -1860,7 +1860,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each thread returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task’s local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -1934,7 +1934,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per task to perform a final action on each task's local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -2012,7 +2012,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per thread to perform a final action on each task’s local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> @@ -2089,7 +2089,7 @@ The `localInit` delegate is invoked once for each task that participates in the loop's execution and returns the initial local state for each of those tasks. These initial states are passed to the first `body` invocations on each task. Then, every subsequent body invocation returns a possibly modified state value that is passed to the next body invocation. Finally, the last body invocation on each task returns a state value that is passed to the `localFinally` delegate. The `localFinally` delegate is invoked once per thread to perform a final action on each task’s local state. This delegate might be invoked concurrently on multiple tasks; therefore, you must synchronize access to any shared variables. - The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. + The method may use more tasks than threads over the lifetime of its execution, as existing tasks complete and are replaced by new tasks. This gives the underlying object the chance to add, change, or remove threads that service the loop. ]]> diff --git a/xml/System.Threading.Tasks/ParallelLoopState.xml b/xml/System.Threading.Tasks/ParallelLoopState.xml index bb19d9bc0b06c..0a65a4cef2f21 100644 --- a/xml/System.Threading.Tasks/ParallelLoopState.xml +++ b/xml/System.Threading.Tasks/ParallelLoopState.xml @@ -31,9 +31,9 @@ or method. The example provides an illustration. + Note that you cannot instantiate an instance of this class. It is automatically generated by the compiler as an argument in a call to the or method. The example provides an illustration. - Constructs such as `for` and `foreach` (in C#) and `For` and `For Each` (in Visual Basic) execute sequentially from the lowest index to the highest or from the first object in a set to the last. In contrast, the and methods do not. Because individual iterations of the loop run in parallel, they can begin and end in any order. The class allows individual iterations of parallel loops to interact with one another. The class allows you to: + Constructs such as `for` and `foreach` (in C#) and `For` and `For Each` (in Visual Basic) execute sequentially from the lowest index to the highest or from the first object in a set to the last. In contrast, the and methods do not. Because individual iterations of the loop run in parallel, they can begin and end in any order. The class allows individual iterations of parallel loops to interact with one another. The class allows you to: - Exit the current iteration and prevent any additional iterations from starting by calling the method. This does not affect iterations that have already begun execution. diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index b2d35361a4e49..9992727021252 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -68,7 +68,7 @@ [!code-csharp[System.Threading.Tasks.Task#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task/cs/run1.cs#6)] [!code-vb[System.Threading.Tasks.Task#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/run1.vb#6)] - An alternative, and the most common method to start a task in [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)], is the static method. The property returns a object. Overloads of the method let you specify parameters to pass to the task creation options and a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. + An alternative, and the most common method to start a task in [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)], is the static method. The property returns a object. Overloads of the method let you specify parameters to pass to the task creation options and a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. [!code-csharp[System.Threading.Tasks.Task#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task/cs/startnew1.cs#7)] [!code-vb[System.Threading.Tasks.Task#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/startnew1.vb#7)] @@ -77,15 +77,15 @@ ## Separating task creation and execution - The class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the or method is the preferred mechanism for creating and scheduling computational tasks, but for scenarios where creation and scheduling must be separated, you can use the constructors and then call the method to schedule the task for execution at a later time. + The class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the or method is the preferred mechanism for creating and scheduling computational tasks, but for scenarios where creation and scheduling must be separated, you can use the constructors and then call the method to schedule the task for execution at a later time. ## Waiting for one or more tasks to complete Because tasks typically run asynchronously on a thread pool thread, the thread that creates and starts the task continues execution as soon as the task has been instantiated. In some cases, when the calling thread is the main application thread, the app may terminate before any the task actually begins execution. In others, your application's logic may require that the calling thread continue execution only when one or more tasks has completed execution. You can synchronize the execution of the calling thread and the asynchronous tasks it launches by calling a `Wait` method to wait for one or more tasks to complete. - To wait for a single task to complete, you can call its method. A call to the method blocks the calling thread until the single class instance has completed execution. + To wait for a single task to complete, you can call its method. A call to the method blocks the calling thread until the single class instance has completed execution. - The following example calls the parameterless method to wait unconditionally until a task completes. The task simulates work by calling the method to sleep for two seconds. + The following example calls the parameterless method to wait unconditionally until a task completes. The task simulates work by calling the method to sleep for two seconds. [!code-csharp[System.Threading.Tasks.Task#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task/cs/Wait1.cs#8)] [!code-vb[System.Threading.Tasks.Task#8](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/Wait1.vb#8)] @@ -97,7 +97,7 @@ You can also supply a cancellation token by calling the and methods. If the token's property is `true`, the wait is cancelled; if it becomes true while the method terminates. - In some cases, you may want to wait for the first of a series of executing tasks to complete, but don't care which task it is. For this purpose, you can call one of the overloads of the method. The following example creates three tasks, each of which sleeps for an interval determine by a random number generator. The method waits for the first task to complete. The example then displays information about the status of all three tasks. + In some cases, you may want to wait for the first of a series of executing tasks to complete, but don't care which task it is. For this purpose, you can call one of the overloads of the method. The following example creates three tasks, each of which sleeps for an interval determine by a random number generator. The method waits for the first task to complete. The example then displays information about the status of all three tasks. [!code-csharp[System.Threading.Tasks.Task#10](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task/cs/WhenAny1.cs#10)] [!code-vb[System.Threading.Tasks.Task#10](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/WaitAny1.vb#10)] @@ -132,7 +132,7 @@ - Task `t1` is instantiated by calling a Task class constructor, but is started by calling its method only after task `t2` has started. -- Task `t2` is instantiated and started in a single method call by calling the method. +- Task `t2` is instantiated and started in a single method call by calling the method. - Task `t3` is instantiated and started in a single method call by calling the method. @@ -181,7 +181,7 @@ object and launch a task is by calling the static or method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static or method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. @@ -236,14 +236,14 @@ object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. For more information, see [Task Parallelism (Task Parallel Library)](~/docs/standard/parallel-programming/task-based-asynchronous-programming.md) and [Cancellation in Managed Threads](~/docs/standard/threading/cancellation-in-managed-threads.md). ## Examples - The following example calls the constructor to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. The method is then called to start the task. + The following example calls the constructor to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. The method is then called to start the task. [!code-csharp[System.Threading.Tasks.Task.ctor#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/cs/run4.cs#4)] [!code-vb[System.Threading.Tasks.Task.ctor#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/run4.vb#4)] @@ -289,7 +289,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -332,7 +332,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. @@ -384,7 +384,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. For more information, see [Task Parallelism (Task Parallel Library)](~/docs/standard/parallel-programming/task-based-asynchronous-programming.md) and [Task Cancellation](~/docs/standard/parallel-programming/task-cancellation.md). @@ -432,7 +432,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -477,7 +477,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -524,7 +524,7 @@ object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -2273,21 +2273,21 @@ Task t Status: RanToCompletion, Result: 42 class that is identical to the one created by calling the parameterless constructor. It has the following property values: + This property returns a default instance of the class that is identical to the one created by calling the parameterless constructor. It has the following property values: |Property|Value| |--------------|-----------| -||| -||| -||| -||`null`, or | +||| +||| +||| +||`null`, or | - The most common use of this property is to create and start a new task in a single call to the method. + The most common use of this property is to create and start a new task in a single call to the method. > [!NOTE] -> Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a object with default configuration values. +> Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a object with default configuration values. - The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. + The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. [!code-csharp[System.Threading.Tasks.Task.Factory#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.factory/cs/factory1.cs#1)] [!code-vb[System.Threading.Tasks.Task.Factory#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.factory/vb/factory1.vb#1)] @@ -2459,7 +2459,7 @@ Task t Status: RanToCompletion, Result: 42 ## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a faulted task if a particular subdirectory does not exist. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a faulted task if a particular subdirectory does not exist. [!code-csharp[System.Threading.Tasks.Task.FromResult#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/cs/fromresult1.cs#1)] [!code-vb[System.Threading.Tasks.Task.FromResult#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb#1)] @@ -2509,14 +2509,14 @@ Task t Status: RanToCompletion, Result: 42 object whose property is `result` and whose property is . The method is commonly used when the return value of a task is immediately known without executing a longer code path. The example provides an illustration. + This method creates a object whose property is `result` and whose property is . The method is commonly used when the return value of a task is immediately known without executing a longer code path. The example provides an illustration. To create a Task object that does not return a value, retrieve the Task object from the property. ## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a task whose property is zero (0) if a directory has no files. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a task whose property is zero (0) if a directory has no files. [!code-csharp[System.Threading.Tasks.Task.FromResult#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/cs/fromresult1.cs#1)] [!code-vb[System.Threading.Tasks.Task.FromResult#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb#1)] @@ -2692,7 +2692,7 @@ Task t Status: RanToCompletion, Result: 42 will return `true` when the task is in one of the three final states: , , or . > [!IMPORTANT] -> Retrieving the value of the property does not block the calling thread until the task has completed. +> Retrieving the value of the property does not block the calling thread until the task has completed. ]]> @@ -2753,7 +2753,7 @@ Task t Status: RanToCompletion, Result: 42 If is `true`, the task's is equal to , and its property will be non-null. > [!IMPORTANT] -> Retrieving the value of the property does not block the calling thread until the task has completed. +> Retrieving the value of the property does not block the calling thread until the task has completed. ]]> @@ -2816,9 +2816,9 @@ Task t Status: RanToCompletion, Result: 42 ## Remarks The method allows you to create and execute a task in a single method call and is a simpler alternative to the method. It creates a task with the following default values: -- Its cancellation token is . +- Its cancellation token is . -- Its property value is . +- Its property value is . - It uses the default task scheduler. @@ -2827,7 +2827,7 @@ Task t Status: RanToCompletion, Result: 42 ## Examples - The following example defines a `ShowThreadInfo` method that displays the of the current thread. It is called directly from the application thread, and is called from the delegate passed to the method. + The following example defines a `ShowThreadInfo` method that displays the of the current thread. It is called directly from the application thread, and is called from the delegate passed to the method. [!code-csharp[System.Threading.Tasks.Task.Run#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.run/cs/Run11.cs#11)] [!code-vb[System.Threading.Tasks.Task.Run#11](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run11.vb#11)] @@ -2936,9 +2936,9 @@ Task t Status: RanToCompletion, Result: 42 ## Remarks If cancellation is requested before the task begins execution, the task does not execute. Instead it is set to the state and throws a exception. - The method is a simpler alternative to the method. It creates a task with the following default values: + The method is a simpler alternative to the method. It creates a task with the following default values: -- Its property value is . +- Its property value is . - It uses the default task scheduler. @@ -2947,7 +2947,7 @@ Task t Status: RanToCompletion, Result: 42 ## Examples - The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. + The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. [!code-csharp[System.Threading.Tasks.Task.Run#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.run/cs/run4.cs#4)] [!code-vb[System.Threading.Tasks.Task.Run#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run4.vb#4)] @@ -3096,11 +3096,11 @@ Task t Status: RanToCompletion, Result: 42 method is a simpler alternative to the method. It creates a task with the following default values: + The method is a simpler alternative to the method. It creates a task with the following default values: -- Its cancellation token is . +- Its cancellation token is . -- Its property value is . +- Its property value is . - It uses the default task scheduler. @@ -3220,7 +3220,7 @@ Task t Status: RanToCompletion, Result: 42 The method is a simpler alternative to the method. It creates a task with the following default values: -- Its property value is . +- Its property value is . - It uses the default task scheduler. @@ -3383,7 +3383,7 @@ Task t Status: RanToCompletion, Result: 42 ## Remarks A task may be started and run only once. Any attempts to schedule a task a second time will result in an exception. - The is used to execute a task that has been created by calling one of the constructors. Typically, you do this when you need to separate the task's creation from its execution, such as when you conditionally execute tasks that you've created. For the more common case in which you don't need to separate task instantiation from execution, we recommend that you call an overload of the or method. + The is used to execute a task that has been created by calling one of the constructors. Typically, you do this when you need to separate the task's creation from its execution, such as when you conditionally execute tasks that you've created. For the more common case in which you don't need to separate task instantiation from execution, we recommend that you call an overload of the or method. For information on handling exceptions thrown by task operations, see [Exception Handling](~/docs/standard/parallel-programming/exception-handling-task-parallel-library.md). @@ -3482,7 +3482,7 @@ Task t Status: RanToCompletion, Result: 42 property does not block the calling thread until the task has completed. + Retrieving the value of the property does not block the calling thread until the task has completed. For more information and an example, see [Chaining Tasks by Using Continuation Tasks](~/docs/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks.md) and [How to: Cancel a Task and Its Children](~/docs/standard/parallel-programming/how-to-cancel-a-task-and-its-children.md). @@ -3531,7 +3531,7 @@ Task t Status: RanToCompletion, Result: 42 is preferable to using for similar functionality. For more information, see the "Waiting on Tasks" section in [Task-based Asynchronous Programming](~/docs/standard/parallel-programming/task-based-asynchronous-programming.md) and [Using TPL with Other Asynchronous Patterns](~/docs/standard/parallel-programming/using-tpl-with-other-asynchronous-patterns.md). + Using the wait functionality provided by is preferable to using for similar functionality. For more information, see the "Waiting on Tasks" section in [Task-based Asynchronous Programming](~/docs/standard/parallel-programming/task-based-asynchronous-programming.md) and [Using TPL with Other Asynchronous Patterns](~/docs/standard/parallel-programming/using-tpl-with-other-asynchronous-patterns.md). ]]> @@ -3668,7 +3668,7 @@ Task t Status: RanToCompletion, Result: 42 - The task completes successfully. -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - The interval defined by `millisecondsTimeout` elapses. In this case, the current thread resumes execution and the method returns `false`. @@ -3740,7 +3740,7 @@ Task t Status: RanToCompletion, Result: 42 ## Examples - The following example illustrates the simple use of a cancellation token to cancel waiting for a task's completion. A task is launched, calls the method to cancel any of the token source's cancellation tokens, and then delays for five seconds. Note that the task itself has not been passed the cancellation token and is not cancelable. The application thread calls the task's method to wait for the task to complete, but the wait is canceled once the cancellation token is cancelled and an is thrown. The exception handler reports the exception and then sleeps for six seconds. As the output from the example shows, that delay allows the task to complete in the state. + The following example illustrates the simple use of a cancellation token to cancel waiting for a task's completion. A task is launched, calls the method to cancel any of the token source's cancellation tokens, and then delays for five seconds. Note that the task itself has not been passed the cancellation token and is not cancelable. The application thread calls the task's method to wait for the task to complete, but the wait is canceled once the cancellation token is cancelled and an is thrown. The exception handler reports the exception and then sleeps for six seconds. As the output from the example shows, that delay allows the task to complete in the state. [!code-csharp[System.Threading.Tasks.Task.Wait#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.wait/cs/wait3.cs#3)] [!code-vb[System.Threading.Tasks.Task.Wait#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/wait3.vb#3)] @@ -3798,7 +3798,7 @@ Task t Status: RanToCompletion, Result: 42 - The task completes successfully. -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - The interval defined by `timeout` elapses. In this case, the current thread resumes execution and the method returns `false`. @@ -3870,7 +3870,7 @@ Task t Status: RanToCompletion, Result: 42 - The task completes successfully. -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - The `cancellationToken` cancellation token is canceled. In this case, the call to the method throws an . @@ -3882,7 +3882,7 @@ Task t Status: RanToCompletion, Result: 42 ## Examples - The following example calls the method to provide both a timeout value and a cancellation token that can end the wait for a task's completion. A new thread is started and executes the `CancelToken` method, which pauses and then calls the method to cancel the cancellation tokens. A task is then launched and delays for 5 seconds. The method is then called to wait for the task's completion and is provided both a brief timeout value and a cancellation token. + The following example calls the method to provide both a timeout value and a cancellation token that can end the wait for a task's completion. A new thread is started and executes the `CancelToken` method, which pauses and then calls the method to cancel the cancellation tokens. A task is then launched and delays for 5 seconds. The method is then called to wait for the task's completion and is provided both a brief timeout value and a cancellation token. [!code-csharp[System.Threading.Tasks.Task.Wait#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.wait/cs/wait4.cs#4)] [!code-vb[System.Threading.Tasks.Task.Wait#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/wait4.vb#4)] @@ -4481,7 +4481,7 @@ Task t Status: RanToCompletion, Result: 42 ## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. [!code-csharp[System.Threading.Tasks.Task.WhenAll#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/cs/WhenAll4.cs#4)] [!code-vb[System.Threading.Tasks.Task.WhenAll#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/WhenAll4.vb#4)] @@ -4551,7 +4551,7 @@ Task t Status: RanToCompletion, Result: 42 ## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. [!code-csharp[System.Threading.Tasks.Task.WhenAll#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/cs/WhenAll3.cs#3)] [!code-vb[System.Threading.Tasks.Task.WhenAll#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/WhenAll3.vb#3)] @@ -4609,7 +4609,7 @@ Task t Status: RanToCompletion, Result: 42 If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. - If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The property of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's property will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. + If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The property of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's property will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. If the `tasks` argument contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. The returned `TResult[]` will be an array of 0 elements. diff --git a/xml/System.Threading.Tasks/TaskCompletionSource`1.xml b/xml/System.Threading.Tasks/TaskCompletionSource`1.xml index 01666cdd1bd82..894078b6ab71f 100644 --- a/xml/System.Threading.Tasks/TaskCompletionSource`1.xml +++ b/xml/System.Threading.Tasks/TaskCompletionSource`1.xml @@ -420,11 +420,11 @@ ## Remarks The method returns false if the underlying object is already in one of the following three final states. -- +- -- +- -- +- This method also returns `false` if the underlying object has already been disposed. diff --git a/xml/System.Threading.Tasks/TaskFactory.xml b/xml/System.Threading.Tasks/TaskFactory.xml index f7cc7bd04ed19..40e261a3c5bef 100644 --- a/xml/System.Threading.Tasks/TaskFactory.xml +++ b/xml/System.Threading.Tasks/TaskFactory.xml @@ -35,7 +35,7 @@ - The class, which creates and objects. You can call the overloads of this method to create and execute a task that requires non-default arguments. > [!WARNING] - > Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a task with default configuration values and start it immediately. + > Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a task with default configuration values and start it immediately. - The class, which creates objects. @@ -44,23 +44,23 @@ - Create a task and start it immediately by calling the method. > [!WARNING] - > Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a task with default configuration values and start it immediately. + > Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a task with default configuration values and start it immediately. - Create a task that starts when any one of the tasks in an array has completed by calling the method. - Create a task that starts when all the tasks in an array have completed by calling the method. - The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. + The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. [!code-csharp[TPL_Factories#1](~/samples/snippets/csharp/VS_Snippets_Misc/tpl_factories/cs/program.cs#1)] [!code-vb[TPL_Factories#1](~/samples/snippets/visualbasic/VS_Snippets_Misc/tpl_factories/vb/factories_vb.vb#1)] - In most cases, you do not have to instantiate a new instance. Instead, you can use the property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. + In most cases, you do not have to instantiate a new instance. Instead, you can use the property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. ## Examples - The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. + The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. [!code-csharp[System.Threading.Tasks.Task.Factory#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.factory/cs/factory1.cs#1)] [!code-vb[System.Threading.Tasks.Task.Factory#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.factory/vb/factory1.vb#1)] @@ -399,7 +399,7 @@ ## Remarks The method executes the `continuationAction` delegate when all tasks in the `tasks` array have completed, regardless of their completion status. - Exceptions thrown by tasks in the `tasks` array are not available to the continuation task through structured exception handling. You can determine which exceptions were thrown by examining the property of each task in the `tasks` array. To use structured exception handling to handle exceptions thrown by tasks in the `tasks` array, call the method. + Exceptions thrown by tasks in the `tasks` array are not available to the continuation task through structured exception handling. You can determine which exceptions were thrown by examining the property of each task in the `tasks` array. To use structured exception handling to handle exceptions thrown by tasks in the `tasks` array, call the method. @@ -409,7 +409,7 @@ [!code-csharp[System.Threading.Tasks.Task.ContinueWhenAll#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.continuewhenall/cs/continuewhenall1.cs#1)] [!code-vb[System.Threading.Tasks.Task.ContinueWhenAll#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.continuewhenall/vb/continuewhenall1.vb#1)] - The call to the continuation task's method does not allow it to handle exceptions thrown by the antecedent tasks, so the example examines the property of each antecedent task to determine whether the task succeeded. + The call to the continuation task's method does not allow it to handle exceptions thrown by the antecedent tasks, so the example examines the property of each antecedent task to determine whether the task succeeded. ]]> @@ -3653,13 +3653,13 @@ method is the recommended way to launch a compute-bound task. Use the method only when you require fine-grained control for a long-running, compute-bound task. This includes scenarios in which you want to control the following: + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method is the recommended way to launch a compute-bound task. Use the method only when you require fine-grained control for a long-running, compute-bound task. This includes scenarios in which you want to control the following: -- Task creation options. Tasks created by the method by default are created with the option. To override this behavior, or to provide other options, call a overload. +- Task creation options. Tasks created by the method by default are created with the option. To override this behavior, or to provide other options, call a overload. -- Parameter passing. The overloads of the method do not allow you to pass a parameter to the task delegate. Overloads of the method do. +- Parameter passing. The overloads of the method do not allow you to pass a parameter to the task delegate. Overloads of the method do. -- The task scheduler. The overloads of the method use the default task scheduler. To control the task scheduler, call a overload with a `scheduler` parameter. For more information, see . +- The task scheduler. The overloads of the method use the default task scheduler. To control the task scheduler, call a overload with a `scheduler` parameter. For more information, see . ]]> @@ -3702,9 +3702,9 @@ is functionally equivalent to creating a task by using one of its constructors, and then calling the method to schedule the task for execution. + Calling is functionally equivalent to creating a task by using one of its constructors, and then calling the method to schedule the task for execution. - Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](http://blogs.msdn.com/b/pfxteam/archive/2011/10/24/10229468.aspx) in the Parallel Programming with .NET blog. + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](http://blogs.msdn.com/b/pfxteam/archive/2011/10/24/10229468.aspx) in the Parallel Programming with .NET blog. @@ -3760,12 +3760,12 @@ ## Remarks Calling `StartNew` is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](http://blogs.msdn.com/b/pfxteam/archive/2011/10/24/10229468.aspx) in the Parallel Programming with .NET blog. + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](http://blogs.msdn.com/b/pfxteam/archive/2011/10/24/10229468.aspx) in the Parallel Programming with .NET blog. ## Examples - The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. + The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. [!code-csharp[System.Threading.Tasks.TaskFactory.StartNew#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/cs/startnew2.cs#2)] [!code-vb[System.Threading.Tasks.TaskFactory.StartNew#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew2.vb#2)] @@ -3936,7 +3936,7 @@ [!code-csharp[System.Threading.Tasks.TaskFactory.StartNew#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/cs/startnew4.cs#4)] [!code-vb[System.Threading.Tasks.TaskFactory.StartNew#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.taskfactory.startnew/vb/startnew4.vb#4)] - Note that the example initializes a single random number generator, which is protected by a lock. For the need of a lock, see "The System.Random class and thread safety" in the class topic. To handle the possibility of corruption of the random number generator, a cancellation token is passed to task. If two random numbers equal zero, the method assumes that the random number generator is corrupted and sets the cancellation token. Before sorting the `chars` array that contains the six characters in a word, the method calls the method to throw an if the token has been canceled. + Note that the example initializes a single random number generator, which is protected by a lock. For the need of a lock, see "The System.Random class and thread safety" in the class topic. To handle the possibility of corruption of the random number generator, a cancellation token is passed to task. If two random numbers equal zero, the method assumes that the random number generator is corrupted and sets the cancellation token. Before sorting the `chars` array that contains the six characters in a word, the method calls the method to throw an if the token has been canceled. ]]> @@ -4156,7 +4156,7 @@ ## Remarks Calling is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can call the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](http://blogs.msdn.com/b/pfxteam/archive/2011/10/24/10229468.aspx) in the Parallel Programming with .NET blog. + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can call the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](http://blogs.msdn.com/b/pfxteam/archive/2011/10/24/10229468.aspx) in the Parallel Programming with .NET blog. @@ -4268,7 +4268,7 @@ ## Remarks Calling is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](http://blogs.msdn.com/b/pfxteam/archive/2011/10/24/10229468.aspx) in the Parallel Programming with .NET blog. + Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](http://blogs.msdn.com/b/pfxteam/archive/2011/10/24/10229468.aspx) in the Parallel Programming with .NET blog. diff --git a/xml/System.Threading.Tasks/TaskFactory`1.xml b/xml/System.Threading.Tasks/TaskFactory`1.xml index 555e7d108c05d..6faa86438c011 100644 --- a/xml/System.Threading.Tasks/TaskFactory`1.xml +++ b/xml/System.Threading.Tasks/TaskFactory`1.xml @@ -45,23 +45,23 @@ - Create a task and start it immediately by calling the method. You can call the overloads of this method to create and execute a task that requires non-default arguments. > [!WARNING] - > Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a task with default configuration values and start it immediately. + > Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a task with default configuration values and start it immediately. - Create a task that starts when any one of the tasks in an array has completed by calling the or method. - Create a task that starts when all the tasks in an array have completed by calling the or method. - The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. + The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. [!code-csharp[TPL_Factories#2](~/samples/snippets/csharp/VS_Snippets_Misc/tpl_factories/cs/factoriestresult.cs#2)] [!code-vb[TPL_Factories#2](~/samples/snippets/visualbasic/VS_Snippets_Misc/tpl_factories/vb/factoriestresult.vb#2)] - In most cases, you do not have to instantiate a new instance. Instead, you can use the static property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. + In most cases, you do not have to instantiate a new instance. Instead, you can use the static property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. ## Examples - The following example uses the static property to make two calls to the method. The first task returns a string array that is populated with the names of files in the user's MyDocuments directory, while the second returns a string array that is populated with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the arrays returned by the two tasks after they have completed execution. + The following example uses the static property to make two calls to the method. The first task returns a string array that is populated with the names of files in the user's MyDocuments directory, while the second returns a string array that is populated with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the arrays returned by the two tasks after they have completed execution. [!code-csharp[System.Threading.Tasks.Task.Factory#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.factory/cs/factory2.cs#2)] [!code-vb[System.Threading.Tasks.Task.Factory#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.factory/vb/factory2.vb#2)] diff --git a/xml/System.Threading.Tasks/TaskScheduler.xml b/xml/System.Threading.Tasks/TaskScheduler.xml index e88478720e608..fcb469bebb850 100644 --- a/xml/System.Threading.Tasks/TaskScheduler.xml +++ b/xml/System.Threading.Tasks/TaskScheduler.xml @@ -58,7 +58,7 @@ ### The global queue vs. local queues - The thread pool maintains a global FIFO (first-in, first-out) work queue for threads in each application domain. Whenever a program calls the (or ) method, the work is put on this shared queue and eventually de-queued onto the next thread that becomes available. Starting with the .NET Framework 4, this queue has been improved to use a lock-free algorithm that resembles the class. By using this lock-free implementation, the thread pool spends less time when it queues and de-queues work items. This performance benefit is available to all programs that use the thread pool. + The thread pool maintains a global FIFO (first-in, first-out) work queue for threads in each application domain. Whenever a program calls the (or ) method, the work is put on this shared queue and eventually de-queued onto the next thread that becomes available. Starting with the .NET Framework 4, this queue has been improved to use a lock-free algorithm that resembles the class. By using this lock-free implementation, the thread pool spends less time when it queues and de-queues work items. This performance benefit is available to all programs that use the thread pool. Top-level tasks, which are tasks that are not created in the context of another task, are put on the global queue just like any other work item. However, nested or child tasks, which are created in the context of another task, are handled quite differently. A child or nested task is put on a local queue that is specific to the thread on which the parent task is executing. The parent task may be a top-level task or it also may be the child of another task. When this thread is ready for more work, it first looks in the local queue. If work items are waiting there, they can be accessed quickly. The local queues are accessed in last-in, first-out order (LIFO) to preserve cache locality and reduce contention. For more information about child tasks and nested tasks, see [Attached and Detached Child Tasks](~/docs/standard/parallel-programming/attached-and-detached-child-tasks.md). @@ -70,7 +70,7 @@ ### Long-running tasks - You may want to explicitly prevent a task from being put on a local queue. For example, you may know that a particular work item will run for a relatively long time and is likely to block all other work items on the local queue. In this case, you can specify the option, which provides a hint to the scheduler that an additional thread might be required for the task so that it does not block the forward progress of other threads or work items on the local queue. By using this option you avoid the thread pool completely, including the global and local queues. + You may want to explicitly prevent a task from being put on a local queue. For example, you may know that a particular work item will run for a relatively long time and is likely to block all other work items on the local queue. In this case, you can specify the option, which provides a hint to the scheduler that an additional thread might be required for the task so that it does not block the forward progress of other threads or work items on the local queue. By using this option you avoid the thread pool completely, including the global and local queues. ### Task inlining @@ -78,11 +78,11 @@ ## Specifying a synchronization context - You can use the method to specify that a task should be scheduled to run on a particular thread. This is useful in frameworks such as Windows Forms and Windows Presentation Foundation where access to user interface objects is often restricted to code that is running on the same thread on which the UI object was created. + You can use the method to specify that a task should be scheduled to run on a particular thread. This is useful in frameworks such as Windows Forms and Windows Presentation Foundation where access to user interface objects is often restricted to code that is running on the same thread on which the UI object was created. - The following example uses the method in a Windows Presentation Foundation (WPF) app to schedule a task on the same thread that the user interface (UI) control was created on. The example creates a mosaic of images that are randomly selected from a specified directory. The WPF objects are used to load and resize the images. The raw pixels are then passed to a task that uses a loop to write the pixel data into a large single-byte array. No synchronization is required because no two tiles occupy the same array elements. The tiles can also be written in any order because their position is calculated independently of any other tile. The large array is then passed to a task that runs on the UI thread, where the pixel data is loaded into an Image control. + The following example uses the method in a Windows Presentation Foundation (WPF) app to schedule a task on the same thread that the user interface (UI) control was created on. The example creates a mosaic of images that are randomly selected from a specified directory. The WPF objects are used to load and resize the images. The raw pixels are then passed to a task that uses a loop to write the pixel data into a large single-byte array. No synchronization is required because no two tiles occupy the same array elements. The tiles can also be written in any order because their position is calculated independently of any other tile. The large array is then passed to a task that runs on the UI thread, where the pixel data is loaded into an Image control. - The example moves data off the UI thread, modifies it by using parallel loops and objects, and then passes it back to a task that runs on the UI thread. This approach is useful when you have to use the Task Parallel Library to perform operations that either are not supported by the WPF API, or are not sufficiently fast. Another way to create an image mosaic in WPF is to use a control and add images to it. The handles the work of positioning the tiles. However, this work can only be performed on the UI thread. + The example moves data off the UI thread, modifies it by using parallel loops and objects, and then passes it back to a task that runs on the UI thread. This approach is useful when you have to use the Task Parallel Library to perform operations that either are not supported by the WPF API, or are not sufficiently fast. Another way to create an image mosaic in WPF is to use a control and add images to it. The handles the work of positioning the tiles. However, this work can only be performed on the UI thread. [!code-csharp[TPL_SyncContext#01](~/samples/snippets/csharp/VS_Snippets_Misc/tpl_synccontext/cs/mainwindow.xaml.cs#01)] [!code-vb[TPL_SyncContext#01](~/samples/snippets/visualbasic/VS_Snippets_Misc/tpl_synccontext/vb/MainWindow.xaml.vb#01)] diff --git a/xml/System.Threading.Tasks/TaskStatus.xml b/xml/System.Threading.Tasks/TaskStatus.xml index 8379f37b869bf..0f67446bce351 100644 --- a/xml/System.Threading.Tasks/TaskStatus.xml +++ b/xml/System.Threading.Tasks/TaskStatus.xml @@ -29,12 +29,12 @@ property returns a member of the enumeration to indicate the task's current status. + The property returns a member of the enumeration to indicate the task's current status. ## Examples - The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether the task has completed successfully or been cancelled. For those that have completed, it displays the value returned by the task. + The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether the task has completed successfully or been cancelled. For those that have completed, it displays the value returned by the task. [!code-csharp[System.Threading.Tasks.Task.Run#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.run/cs/Run7.cs#7)] [!code-vb[System.Threading.Tasks.Task.Run#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run7.vb#7)] diff --git a/xml/System.Threading.Tasks/Task`1.xml b/xml/System.Threading.Tasks/Task`1.xml index fdc21b9a8d72f..5790424a51c71 100644 --- a/xml/System.Threading.Tasks/Task`1.xml +++ b/xml/System.Threading.Tasks/Task`1.xml @@ -44,23 +44,23 @@ ## Remarks The class represents a single operation that returns a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](~/docs/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap.md) first introduced in the .NET Framework 4. Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. - instances may be created in a variety of ways. The most common approach, which is available starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: + instances may be created in a variety of ways. The most common approach, which is available starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: [!code-csharp[System.Threading.Tasks.Task\`1#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task`1/cs/run1.cs#6)] [!code-vb[System.Threading.Tasks.Task\`1#6](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1/vb/run1.vb#6)] - An alternative, and the most common way to start a task in the [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)], is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. + An alternative, and the most common way to start a task in the [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)], is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. [!code-csharp[System.Threading.Tasks.Task\`1#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task`1/cs/startnew1.cs#7)] [!code-vb[System.Threading.Tasks.Task\`1#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1/vb/startnew1.vb#7)] For more complete examples, see [Task-based Asynchronous Programming](~/docs/standard/parallel-programming/task-based-asynchronous-programming.md). - The class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the and `Task.Factory.StartNew` methods are the preferred mechanisms for creating and scheduling computational tasks, but for scenarios where task creation and scheduling must be separated, the constructors may be used, and the task's method may then be used to schedule the task for execution at a later time. + The class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the and `Task.Factory.StartNew` methods are the preferred mechanisms for creating and scheduling computational tasks, but for scenarios where task creation and scheduling must be separated, the constructors may be used, and the task's method may then be used to schedule the task for execution at a later time. Starting with desktop apps that target the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], the culture of the thread that creates and invokes a task becomes part of the thread's context. That is, regardless of the current culture of the thread on which the task executes, the current culture of the task is the culture of the calling thread. For apps that target versions of the .NET Framework prior to the [!INCLUDE[net_v46](~/includes/net-v46-md.md)], the culture of the task is the culture of the thread on which the task executes. For more information, see the "Culture and task-based asynchronous operations" section in the topic. Note that Store apps follow the Windows Runtime in setting and getting the default culture. -For operations that do not return a value, you use the class. If you're developing with C# 7, for a more lightweight task that is a value type rather than a reference type, use the structure; it is supported starting with C# 7. +For operations that do not return a value, you use the class. If you're developing with C# 7, for a more lightweight task that is a value type rather than a reference type, use the structure; it is supported starting with C# 7. ]]> @@ -100,14 +100,14 @@ For operations that do not return a value, you use the object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ## Examples - The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. + The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. - Object instantiation is separated from object execution in this example so that the example can ensure that each file exists. If they do not, it displays the name of the missing file. Otherwise, it calls the method to launch each task. + Object instantiation is separated from object execution in this example so that the example can ensure that each file exists. If they do not, it displays the name of the missing file. Otherwise, it calls the method to launch each task. [!code-csharp[System.Threading.Tasks.Task.ctor#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/cs/run3.cs#2)] [!code-vb[System.Threading.Tasks.Task.ctor#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/run3.vb#2)] @@ -154,7 +154,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -196,7 +196,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -239,7 +239,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -284,7 +284,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -329,7 +329,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -374,7 +374,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -422,7 +422,7 @@ For operations that do not return a value, you use the object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + Rather than calling this constructor, the most common way to instantiate a object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. ]]> @@ -620,12 +620,12 @@ For operations that do not return a value, you use the object is used to define a timeout value of 100 milliseconds. If the event fires, the method is called, and the cancellation token is used to request cancellation of the tasks. + A cancellation token is passed to both the antecedent and the continuation task. A object is used to define a timeout value of 100 milliseconds. If the event fires, the method is called, and the cancellation token is used to request cancellation of the tasks. [!code-csharp[System.Threading.Tasks.Task\`1.ContinueWith#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task`1.continuewith/cs/continue1.cs#1)] [!code-vb[System.Threading.Tasks.Task\`1.ContinueWith#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task`1.continuewith/vb/continue1.vb#1)] - Typically, supplying a value of about 100,000 causes the timeout interval to expire and the event to fire, and the cancellation request to be set. + Typically, supplying a value of about 100,000 causes the timeout interval to expire and the event to fire, and the cancellation request to be set. ]]> @@ -1550,7 +1550,7 @@ For operations that do not return a value, you use the will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - The `continuationFunction`, when executed, should return a . This task's completion state will be transferred to the task returned from the call. + The `continuationFunction`, when executed, should return a . This task's completion state will be transferred to the task returned from the call. ]]> @@ -1592,21 +1592,21 @@ For operations that do not return a value, you use the class that is identical to the one created by calling the parameterless constructor. It has the following property values: + This property returns a default instance of the class that is identical to the one created by calling the parameterless constructor. It has the following property values: |Property|Value| |--------------|-----------| -||| -||| -||| -||`null`, or | +||| +||| +||| +||`null`, or | - The most common use of this property is to create and start a new task in a single call to the method. + The most common use of this property is to create and start a new task in a single call to the method. > [!NOTE] -> Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a object with default configuration values. +> Starting with the [!INCLUDE[net_v45](~/includes/net-v45-md.md)], the method provides the easiest way to create a object with default configuration values. - The following example uses the static property to make three calls to the method. The first starts a `Task` object, which executes a lambda expression that returns 1. The second starts a `Task` object, which executes a lambda expression that instantiates a new `Test` instance. The third starts a `Task` object, which enumerates the files in the C:\Users\Public\Pictures\Sample Pictures\ directory. (Note that successful execution of the example requires that the directory exist and that it contain files. + The following example uses the static property to make three calls to the method. The first starts a `Task` object, which executes a lambda expression that returns 1. The second starts a `Task` object, which executes a lambda expression that instantiates a new `Test` instance. The third starts a `Task` object, which enumerates the files in the C:\Users\Public\Pictures\Sample Pictures\ directory. (Note that successful execution of the example requires that the directory exist and that it contain files. [!code-csharp[TPL#10](~/samples/snippets/csharp/VS_Snippets_Misc/tpl/cs/returnavalue10.cs#10)] [!code-vb[TPL#10](~/samples/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/10_returnavalue.vb#10)] @@ -1700,7 +1700,7 @@ For operations that do not return a value, you use the object for each file in the directory and retrieves the value of its property. If a directory contains no files, it simply calls the method to create a task whose property is zero (0). When the tasks finish, the total number of bytes in all a directory's files is available from the property. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. If the directory contains files, it executes a lambda expression that instantiates a object for each file in the directory and retrieves the value of its property. If a directory contains no files, it simply calls the method to create a task whose property is zero (0). When the tasks finish, the total number of bytes in all a directory's files is available from the property. [!code-csharp[System.Threading.Tasks.Task.FromResult#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/cs/fromresult1.cs#1)] [!code-vb[System.Threading.Tasks.Task.FromResult#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb#1)] diff --git a/xml/System.Threading/AbandonedMutexException.xml b/xml/System.Threading/AbandonedMutexException.xml index e905a179cb359..93123b4d77dae 100644 --- a/xml/System.Threading/AbandonedMutexException.xml +++ b/xml/System.Threading/AbandonedMutexException.xml @@ -406,7 +406,7 @@ method, the returned is the abandoned mutex with the lowest index in the array of objects that was passed to , or `null` if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns `null`. + If the exception is thrown on a call to the method, the returned is the abandoned mutex with the lowest index in the array of objects that was passed to , or `null` if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns `null`. ]]> @@ -442,12 +442,12 @@ method, this property returns the index of the abandoned mutex with the lowest index in the array of objects that was passed to , or –1 if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns –1. + If the exception is thrown on a call to the method, this property returns the index of the abandoned mutex with the lowest index in the array of objects that was passed to , or –1 if the abandoned mutex could not be identified. If the exception is thrown on a call to or , this property always returns –1. ## Examples - The following code example executes a thread that abandons five mutexes. The abandoned mutexes are used to demonstrate the effects on the , , and method calls. The value of the property is displayed for the call. + The following code example executes a thread that abandons five mutexes. The abandoned mutexes are used to demonstrate the effects on the , , and method calls. The value of the property is displayed for the call. > [!NOTE] > The call to is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. diff --git a/xml/System.Threading/AsyncFlowControl.xml b/xml/System.Threading/AsyncFlowControl.xml index 765c7cc1a30a4..136efbefa27bb 100644 --- a/xml/System.Threading/AsyncFlowControl.xml +++ b/xml/System.Threading/AsyncFlowControl.xml @@ -29,7 +29,7 @@ method, which returns an structure. The method of the returned structure can be used to undo the flow suppression. The structure must be used on the same thread on which it was created. + An execution context contains all execution-related information for a logical thread. The flow of the execution context to other threads can be prevented by using the method, which returns an structure. The method of the returned structure can be used to undo the flow suppression. The structure must be used on the same thread on which it was created. ]]> @@ -203,7 +203,7 @@ if the two structures are equal; otherwise, . - .]]> + .]]> @@ -239,7 +239,7 @@ if the structures are not equal; otherwise, . - .]]> + .]]> @@ -276,7 +276,7 @@ method returns an structure that is used to restore the flow. + The method returns an structure that is used to restore the flow. The method must be called only on the structure returned by its associated method. diff --git a/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml b/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml index 9ad9852c92d6d..e53939da0be17 100644 --- a/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml +++ b/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml @@ -122,7 +122,7 @@ property is changed explicitly. + The property value is `false` if the property is changed explicitly. ]]> diff --git a/xml/System.Threading/AutoResetEvent.xml b/xml/System.Threading/AutoResetEvent.xml index ad7a9c4d1091e..51224998f70f6 100644 --- a/xml/System.Threading/AutoResetEvent.xml +++ b/xml/System.Threading/AutoResetEvent.xml @@ -52,7 +52,7 @@ For more information about thread synchronization mechanisms, see [AutoResetEvent](~/docs/standard/threading/autoresetevent.md) in the conceptual documentation. - Beginning with the .NET Framework version 2.0, derives from the new class. An is functionally equivalent to an created with . + Beginning with the .NET Framework version 2.0, derives from the new class. An is functionally equivalent to an created with . > [!NOTE] > Unlike the class, the class provides access to named system synchronization events. @@ -110,7 +110,7 @@ The program logic guarantees that the `ThreadProc` method will never read the same value two times. It does not guarantee that the `ThreadProc` method will read every value written by `Main`. That guarantee would require a second lock. - After each write operation, `Main` yields by calling the method, to give the second thread a chance to execute. Otherwise, on a single-processor computer `Main` would write many values between any two read operations. + After each write operation, `Main` yields by calling the method, to give the second thread a chance to execute. Otherwise, on a single-processor computer `Main` would write many values between any two read operations. [!code-cpp[System.Threading.AutoResetEvent#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/CPP/class1.cpp#1)] [!code-csharp[System.Threading.AutoResetEvent#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/CS/class1.cs#1)] diff --git a/xml/System.Threading/CancellationToken.xml b/xml/System.Threading/CancellationToken.xml index 1c03dda1fab86..6b27f6803026f 100644 --- a/xml/System.Threading/CancellationToken.xml +++ b/xml/System.Threading/CancellationToken.xml @@ -38,7 +38,7 @@ enables cooperative cancellation between threads, thread pool work items, or objects. You create a cancellation token by instantiating a object, which manages cancellation tokens retrieved from its property. You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. The token cannot be used to initiate cancellation. When the owning object calls , the property on every copy of the cancellation token is set to `true`. The objects that receive the notification can respond in whatever manner is appropriate. + A enables cooperative cancellation between threads, thread pool work items, or objects. You create a cancellation token by instantiating a object, which manages cancellation tokens retrieved from its property. You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. The token cannot be used to initiate cancellation. When the owning object calls , the property on every copy of the cancellation token is set to `true`. The objects that receive the notification can respond in whatever manner is appropriate. For more information and code examples see [Cancellation in Managed Threads](~/docs/standard/threading/cancellation-in-managed-threads.md). @@ -47,7 +47,7 @@ ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. - To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. + To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. [!code-csharp[System.Threading.CancellationTokenSource.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.cancellationtokensource.class/cs/cancel1.cs#1)] [!code-vb[System.Threading.CancellationTokenSource.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.cancellationtokensource.class/vb/cancel1.vb#1)] @@ -132,7 +132,7 @@ returns `false`, it is guaranteed that the token will never transition into a canceled state, meaning that will never return `true`. A cancellation token that cannot be canceled is returned by the static property. + If returns `false`, it is guaranteed that the token will never transition into a canceled state, meaning that will never return `true`. A cancellation token that cannot be canceled is returned by the static property. You can optionally use this property to determine whether a cancellation token can be canceled before examing the value of the property to determine whether it has been canceled. @@ -294,7 +294,7 @@ [!code-csharp[System.Threading.Tasks.CancellationToken.IsCancellationRequested#12](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.Threading.Tasks.CancellationToken.IsCancellationRequested/cs/cancellation.cs#12)] [!code-vb[System.Threading.Tasks.CancellationToken.IsCancellationRequested#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.Threading.Tasks.CancellationToken.IsCancellationRequested/vb/cancelthreads.vb#12)] - The example instantiates a object, which controls access to the cancellation token. It then defines two thread procedures. The first is defined as a lambda expression that pools the keyboard and, when the "C" key is pressed, calls to set the cancellation token to the cancelled state. The second is a parameterized method, `ServerClass.StaticMethod`, that executes a loop until the property is `true`. + The example instantiates a object, which controls access to the cancellation token. It then defines two thread procedures. The first is defined as a lambda expression that pools the keyboard and, when the "C" key is pressed, calls to set the cancellation token to the cancelled state. The second is a parameterized method, `ServerClass.StaticMethod`, that executes a loop until the property is `true`. The main thread then starts the two threads and blocks until the thread that executes the `ServerClass.StaticMethod` method terminates. diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index 2003430406d8b..c8db5f263c731 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -46,11 +46,11 @@ - Instantiate a object, which manages and sends cancellation notification to the individual cancellation tokens. -- Pass the token returned by the property to each task or thread that listens for cancellation. +- Pass the token returned by the property to each task or thread that listens for cancellation. -- Call the method from operations that receive the cancellation token. Provide a mechanism for each task or thread to respond to a cancellation request. Whether you choose to cancel an operation, and exactly how you do it, depends on your application logic. +- Call the method from operations that receive the cancellation token. Provide a mechanism for each task or thread to respond to a cancellation request. Whether you choose to cancel an operation, and exactly how you do it, depends on your application logic. -- Call the method to provide notification of cancellation. This sets the property on every copy of the cancellation token to `true`. +- Call the method to provide notification of cancellation. This sets the property on every copy of the cancellation token to `true`. - Call the method when you are finished with the object. @@ -64,7 +64,7 @@ ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. - To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. + To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. [!code-csharp[System.Threading.CancellationTokenSource.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.cancellationtokensource.class/cs/cancel1.cs#1)] [!code-vb[System.Threading.CancellationTokenSource.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.cancellationtokensource.class/vb/cancel1.vb#1)] @@ -227,7 +227,7 @@ ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. - To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. + To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token which is passed to a object. The object in turn passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not because it has been cancelled, the call to the method throws an exception. [!code-csharp[System.Threading.CancellationTokenSource.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.cancellationtokensource.class/cs/cancel1.cs#1)] [!code-vb[System.Threading.CancellationTokenSource.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.cancellationtokensource.class/vb/cancel1.vb#1)] diff --git a/xml/System.Threading/CompressedStack.xml b/xml/System.Threading/CompressedStack.xml index 57b89eab26565..e2481029ccbae 100644 --- a/xml/System.Threading/CompressedStack.xml +++ b/xml/System.Threading/CompressedStack.xml @@ -31,7 +31,7 @@ ## Remarks The compressed stack is a compact representation of all the code access security information on the call stack, such as and actions. For example, if a action is two stack frames up from the current frame and there are no other code access security annotations between there and the current frame, the compressed stack records only that information, without having to serialize the entire call stack. - The class is used internally by the class. For example, the method captures the compressed stack for the current call stack, along with impersonation and culture information. The class is used in turn by the class to flow context across threads, for example when scheduling thread pool tasks. + The class is used internally by the class. For example, the method captures the compressed stack for the current call stack, along with impersonation and culture information. The class is used in turn by the class to flow context across threads, for example when scheduling thread pool tasks. This class is not used in ordinary application programming. @@ -153,7 +153,7 @@ If security is enabled, the current compressed stack is returned. If security is disabled, returns an empty object. > [!NOTE] -> This method uses to prevent it from being called from untrusted code; only the immediate caller is required to have permission. For important limitations on using the `LinkDemand` member, see [Demand vs. LinkDemand](http://msdn.microsoft.com/en-us/1ab877f2-70f4-4e0d-8116-943999dfe8f5). +> This method uses to prevent it from being called from untrusted code; only the immediate caller is required to have permission. For important limitations on using the `LinkDemand` member, see [Demand vs. LinkDemand](http://msdn.microsoft.com/en-us/1ab877f2-70f4-4e0d-8116-943999dfe8f5). > [!NOTE] > This member also makes a link demand for the ECMA public key, which is not a valid cryptographic key but a pseudo key. Within the .NET Framework the link demand for the ECMA pseudo key is automatically converted to a link demand for the Microsoft public key. The security exception is based on the Microsoft public key, not the ECMA pseudo key. diff --git a/xml/System.Threading/ContextCallback.xml b/xml/System.Threading/ContextCallback.xml index c42c11f035734..fef0d4910e1a1 100644 --- a/xml/System.Threading/ContextCallback.xml +++ b/xml/System.Threading/ContextCallback.xml @@ -37,7 +37,7 @@ is used by the and the methods. represents the method to be run in the provided context. Upon completion of the method execution, the context is restored to its previous state. + is used by the and the methods. represents the method to be run in the provided context. Upon completion of the method execution, the context is restored to its previous state. Create the delegate by passing your callback method to the constructor. Your method must have the signature shown here. diff --git a/xml/System.Threading/EventWaitHandle.xml b/xml/System.Threading/EventWaitHandle.xml index 71ab7b30a2ec6..3371288c10c3c 100644 --- a/xml/System.Threading/EventWaitHandle.xml +++ b/xml/System.Threading/EventWaitHandle.xml @@ -32,18 +32,18 @@ class allows threads to communicate with each other by signaling. Typically, one or more threads block on an until an unblocked thread calls the method, releasing one or more of the blocked threads. A thread can signal an and then block on it, by calling the `static` (`Shared` in Visual Basic) method. + The class allows threads to communicate with each other by signaling. Typically, one or more threads block on an until an unblocked thread calls the method, releasing one or more of the blocked threads. A thread can signal an and then block on it, by calling the `static` (`Shared` in Visual Basic) method. > [!NOTE] > The class provides access to named system synchronization events. - The behavior of an that has been signaled depends on its reset mode. An created with the flag resets automatically when signaled, after releasing a single waiting thread. An created with the flag remains signaled until its method is called. + The behavior of an that has been signaled depends on its reset mode. An created with the flag resets automatically when signaled, after releasing a single waiting thread. An created with the flag remains signaled until its method is called. Automatic reset events provide exclusive access to a resource. If an automatic reset event is signaled when no threads are waiting, it remains signaled until a thread attempts to wait on it. The event releases the thread and immediately resets, blocking subsequent threads. Manual reset events are like gates. When the event is not signaled, threads that wait on it will block. When the event is signaled, all waiting threads are released, and the event remains signaled (that is, subsequent waits do not block) until its method is called. Manual reset events are useful when one thread must complete an activity before other threads can proceed. - objects can be used with the `static`(`Shared` in Visual Basic) and methods. + objects can be used with the `static`(`Shared` in Visual Basic) and methods. For more information about thread synchronization mechanisms, see [EventWaitHandle, AutoResetEvent, CountdownEvent, ManualResetEvent](~/docs/standard/threading/eventwaithandle-autoresetevent-countdownevent-manualresetevent.md). @@ -52,7 +52,7 @@ ## Examples The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. - The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. + The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. [!code-cpp[System.Threading.WaitHandle.SignalAndWait#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CPP/source.cpp#1)] [!code-csharp[System.Threading.WaitHandle.SignalAndWait#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CS/source.cs#1)] @@ -108,7 +108,7 @@ ## Examples The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. - The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses ENTER key. The example then queues another five threads and releases them all using an created with the flag. + The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses ENTER key. The example then queues another five threads and releases them all using an created with the flag. [!code-cpp[System.Threading.WaitHandle.SignalAndWait#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CPP/source.cpp#1)] [!code-csharp[System.Threading.WaitHandle.SignalAndWait#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CS/source.cs#1)] @@ -331,9 +331,9 @@ method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + The method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . - The user must have rights to call this method, and the event must have been opened with the flag. + The user must have rights to call this method, and the event must have been opened with the flag. @@ -404,9 +404,9 @@ Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. - Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. + Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. @@ -470,7 +470,7 @@ flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. + The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. The method tries to open an existing named system event. If the system event does not exist, this method throws an exception instead of creating the system event. To create the system event when it does not already exist, use one of the constructors that has a `name` parameter. @@ -581,19 +581,19 @@ with (including ), the method releases a single thread. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it, or until its method is called. + For an with (including ), the method releases a single thread. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it, or until its method is called. > [!IMPORTANT] -> There is no guarantee that every call to the method will release a thread from an whose reset mode is . If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It is as if the second call did not happen. Also, if is called when there are no threads waiting and the is already signaled, the call has no effect. +> There is no guarantee that every call to the method will release a thread from an whose reset mode is . If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It is as if the second call did not happen. Also, if is called when there are no threads waiting and the is already signaled, the call has no effect. - For an with (including ), calling the method leaves the wait handle in a signaled state until its method is called. + For an with (including ), calling the method leaves the wait handle in a signaled state until its method is called. ## Examples The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. - The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. + The example starts five threads and allows them to block on an created with the flag, then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. [!code-cpp[System.Threading.WaitHandle.SignalAndWait#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CPP/source.cpp#1)] [!code-csharp[System.Threading.WaitHandle.SignalAndWait#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CS/source.cs#1)] @@ -631,7 +631,7 @@ rights to call this method, and the event must have been opened with the flag. + The user must have rights to call this method, and the event must have been opened with the flag. @@ -707,7 +707,7 @@ If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. @@ -764,7 +764,7 @@ If you are uncertain whether a named synchronization event exists, use this method overload instead of the method overload, which throws an exception if the synchronization event does not exist. - The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. + The `rights` parameter must include the flag to allow threads to wait on the event, and the flag to allow threads to call the and methods. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. diff --git a/xml/System.Threading/ExecutionContext.xml b/xml/System.Threading/ExecutionContext.xml index 782001a34cb27..020577309f219 100644 --- a/xml/System.Threading/ExecutionContext.xml +++ b/xml/System.Threading/ExecutionContext.xml @@ -37,7 +37,7 @@ The class provides the functionality for user code to capture and transfer this context across user-defined asynchronous points. The common language runtime ensures that the is consistently transferred across runtime-defined asynchronous points within the managed process. - An execution context is the managed equivalent of a COM apartment. Within an application domain, the entire execution context must be transferred whenever a thread is transferred. This situation occurs during transfers made by the method, most thread pool operations, and Windows Forms thread marshaling through the Windows message pump. It does not occur in unsafe thread pool operations (such as the method), which do not transfer the compressed stack. Wherever the compressed stack flows, the managed principal, synchronization, locale, and user context also flow. The class provides the and methods to get the execution context and the method to set the execution context for the current thread. + An execution context is the managed equivalent of a COM apartment. Within an application domain, the entire execution context must be transferred whenever a thread is transferred. This situation occurs during transfers made by the method, most thread pool operations, and Windows Forms thread marshaling through the Windows message pump. It does not occur in unsafe thread pool operations (such as the method), which do not transfer the compressed stack. Wherever the compressed stack flows, the managed principal, synchronization, locale, and user context also flow. The class provides the and methods to get the execution context and the method to set the execution context for the current thread. An that is associated with a thread cannot be set on another thread. Attempting to do so will result in an exception being thrown. To propagate the from one thread to another, make a copy of the . @@ -391,7 +391,7 @@ You must use the method on the returned structure to restore the flow of the . - This method is protected with a for permission. A fully trusted component can call this method to suppress the flow of the during asynchronous calls. While the flow is suppressed, the method returns `null`. + This method is protected with a for permission. A fully trusted component can call this method to suppress the flow of the during asynchronous calls. While the flow is suppressed, the method returns `null`. ]]> diff --git a/xml/System.Threading/HostExecutionContext.xml b/xml/System.Threading/HostExecutionContext.xml index 6402b4f439fb2..7f761732b5b02 100644 --- a/xml/System.Threading/HostExecutionContext.xml +++ b/xml/System.Threading/HostExecutionContext.xml @@ -129,7 +129,7 @@ method call. + The copy can be used as the parameter to a method call. ]]> diff --git a/xml/System.Threading/HostExecutionContextManager.xml b/xml/System.Threading/HostExecutionContextManager.xml index 2d278a6fb1653..fcfa0efe51b5b 100644 --- a/xml/System.Threading/HostExecutionContextManager.xml +++ b/xml/System.Threading/HostExecutionContextManager.xml @@ -25,7 +25,7 @@ has a reference to a in its property, then the common language runtime calls the manager every time a call to the method occurs, to allow the host to participate in the flow of the execution context. + If the current has a reference to a in its property, then the common language runtime calls the manager every time a call to the method occurs, to allow the host to participate in the flow of the execution context. ]]> @@ -175,7 +175,7 @@ method sets the host execution context for the current . A that has been used as the argument to another method call cannot be passed in as the parameter for this method. Instead, use the method to create a copy of a object and then use the copy to set the host execution context. + The method sets the host execution context for the current . A that has been used as the argument to another method call cannot be passed in as the parameter for this method. Instead, use the method to create a copy of a object and then use the copy to set the host execution context. Call the method using the object returned by this method to restore the to its previous state. diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index ad29dd43f6d86..1bef47a447b59 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -96,7 +96,7 @@ and `value` is 1, the result is ; if `value` is 2, the result is ( + 1); and so on. No exception is thrown. + This method handles an overflow condition by wrapping: if the value at `location1` is and `value` is 1, the result is ; if `value` is 2, the result is ( + 1); and so on. No exception is thrown. ]]> @@ -144,9 +144,9 @@ and `value` is 1, the result is ; if `value` is 2, the result is ( + 1); and so on. No exception is thrown. + This method handles an overflow condition by wrapping: if the value at `location1` is and `value` is 1, the result is ; if `value` is 2, the result is ( + 1); and so on. No exception is thrown. - The method and the 64-bit overloads of the , , and methods are truly atomic only on systems where a is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data. Thus, to be thread safe on 32-bit systems, any access to a 64-bit value must be made through the members of the class. + The method and the 64-bit overloads of the , , and methods are truly atomic only on systems where a is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data. Thus, to be thread safe on 32-bit systems, any access to a 64-bit value must be made through the members of the class. ]]> @@ -416,7 +416,7 @@ Beginning with .NET Framework version 2.0, the method overload provides a type-safe alternative for reference types. > [!NOTE] -> The objects are compared for reference equality, rather than . As a result, two boxed instances of the same value type (for example, the integer 3) always appear to be unequal, and no operation is performed. Do not use this overload with value types. +> The objects are compared for reference equality, rather than . As a result, two boxed instances of the same value type (for example, the integer 3) always appear to be unequal, and no operation is performed. Do not use this overload with value types. ]]> @@ -583,7 +583,7 @@ , `location` - 1 = . No exception is thrown. + This method handles an overflow condition by wrapping: If `location` = , `location` - 1 = . No exception is thrown. @@ -593,7 +593,7 @@ [!code-csharp[System.Threading.Interlocked.Decrement#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement1.cs#1)] [!code-vb[System.Threading.Interlocked.Decrement#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.decrement/vb/decrement1.vb#1)] - The following example is similar to the previous one, except that it uses the instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. + The following example is similar to the previous one, except that it uses the instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. [!code-csharp[System.Threading.Interlocked.Decrement#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement2.cs#2)] [!code-vb[System.Threading.Interlocked.Decrement#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.decrement/vb/decrement2.vb#2)] @@ -637,9 +637,9 @@ , `location` - 1 = . No exception is thrown. + This method handles an overflow condition by wrapping: if `location` = , `location` - 1 = . No exception is thrown. - The method and the 64-bit overloads of the , , and methods are truly atomic only on systems where a is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data. Thus, to be thread safe on 32-bit systems, any access to a 64-bit value must be made through the members of the class. + The method and the 64-bit overloads of the , , and methods are truly atomic only on systems where a is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data. Thus, to be thread safe on 32-bit systems, any access to a 64-bit value must be made through the members of the class. ]]> @@ -1015,7 +1015,7 @@ , `location` + 1 = . No exception is thrown. + This method handles an overflow condition by wrapping: if `location` = , `location` + 1 = . No exception is thrown. @@ -1025,7 +1025,7 @@ [!code-csharp[System.Threading.Interlocked.Increment2#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment3.cs#3)] [!code-vb[System.Threading.Interlocked.Increment2#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.increment2/vb/Increment3.vb#3)] - The following example is similar to the previous one, except that it uses the instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. + The following example is similar to the previous one, except that it uses the instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. [!code-csharp[System.Threading.Interlocked.Increment2#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment4.cs#4)] [!code-vb[System.Threading.Interlocked.Increment2#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.increment2/vb/Increment4.vb#4)] @@ -1074,9 +1074,9 @@ , `location` + 1 = . No exception is thrown. + This method handles an overflow condition by wrapping: if `location` = , `location` + 1 = . No exception is thrown. - The method and the 64-bit overloads of the , , and methods are truly atomic only on systems where a is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data. Thus, to be thread safe on 32-bit systems, any access to a 64-bit value must be made through the members of the class. + The method and the 64-bit overloads of the , , and methods are truly atomic only on systems where a is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data. Thus, to be thread safe on 32-bit systems, any access to a 64-bit value must be made through the members of the class. ]]> @@ -1113,7 +1113,7 @@ class in the [!INCLUDE[net_v45](~/includes/net-v45-md.md)] as a convenience; it's a wrapper for the method. + This method was added to the class in the [!INCLUDE[net_v45](~/includes/net-v45-md.md)] as a convenience; it's a wrapper for the method. is required only on multiprocessor systems that have weak memory ordering (for example, a system that employs multiple Intel Itanium processors). @@ -1177,7 +1177,7 @@ ## Remarks The method is unnecessary on 64-bit systems, because 64-bit read operations are already atomic. On 32-bit systems, 64-bit read operations are not atomic unless performed using . - The method and the 64-bit overloads of the , , and methods are truly atomic only on systems where a is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data. Thus, to be thread safe on 32-bit systems, any access to a 64-bit value must be made through the members of the class. + The method and the 64-bit overloads of the , , and methods are truly atomic only on systems where a is 64 bits long. On other systems, these methods are atomic with respect to each other, but not with respect to other means of accessing the data. Thus, to be thread safe on 32-bit systems, any access to a 64-bit value must be made through the members of the class. > [!NOTE] > is a platform-specific type. diff --git a/xml/System.Threading/LazyThreadSafetyMode.xml b/xml/System.Threading/LazyThreadSafetyMode.xml index 123de457b8a29..0a6723de1731e 100644 --- a/xml/System.Threading/LazyThreadSafetyMode.xml +++ b/xml/System.Threading/LazyThreadSafetyMode.xml @@ -30,9 +30,9 @@ ## Remarks Use this enumeration to specify the `mode` parameter of constructors. The effects of all constructors on thread synchronization can be described in terms of this enumeration, whether or not they have `mode` parameters. - A instance is initialized either by a user-specified initialization method or by the default constructor for `T`. The initialization method is specified by the `valueFactory` parameter of a constructor. The method returns an instance of `T`, which is the type that is lazily instantiated by the instance of . If a constructor does not have a `valueFactory` parameter, the default constructor for `T` is used to initialize the instance. In either case, initialization occurs the first time you call the property. + A instance is initialized either by a user-specified initialization method or by the default constructor for `T`. The initialization method is specified by the `valueFactory` parameter of a constructor. The method returns an instance of `T`, which is the type that is lazily instantiated by the instance of . If a constructor does not have a `valueFactory` parameter, the default constructor for `T` is used to initialize the instance. In either case, initialization occurs the first time you call the property. - In addition to specifying the thread safety of a instance, this enumeration affects exception caching. When exceptions are cached for a instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the property, that exception is cached and rethrown on all subsequent calls to the property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur. + In addition to specifying the thread safety of a instance, this enumeration affects exception caching. When exceptions are cached for a instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the property, that exception is cached and rethrown on all subsequent calls to the property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur. When you specify the PublicationOnly mode, exceptions are never cached. When you specify None or ExecutionAndPublication, caching depends on whether you specify an initialization method or allow the default constructor for `T` to be used. Specifying an initialization method enables exception caching for these two modes. The initialization method can be very simple. For example, it might call the default constructor for `T`: `new Lazy(() => new Contents(), mode)` in C#, or `New Lazy(Of Contents)(Function() New Contents())` in Visual Basic. If you use a constructor that does not specify an initialization method, exceptions that are thrown by the default constructor for `T` are not cached. The following table summarizes exception caching behavior. diff --git a/xml/System.Threading/LockCookie.xml b/xml/System.Threading/LockCookie.xml index 31ae89762042a..621206f83caf9 100644 --- a/xml/System.Threading/LockCookie.xml +++ b/xml/System.Threading/LockCookie.xml @@ -173,7 +173,7 @@ if is equal to ; otherwise, . - .]]> + .]]> @@ -209,7 +209,7 @@ if is not equal to ; otherwise, . - .]]> + .]]> diff --git a/xml/System.Threading/LockRecursionException.xml b/xml/System.Threading/LockRecursionException.xml index 3f1f27910bdca..681e81a0337e8 100644 --- a/xml/System.Threading/LockRecursionException.xml +++ b/xml/System.Threading/LockRecursionException.xml @@ -122,7 +122,7 @@ property of the new exception with the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor must make sure that this string has been localized for the current system culture. + This constructor initializes the property of the new exception with the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor must make sure that this string has been localized for the current system culture. The following table shows the initial property values for an instance of . diff --git a/xml/System.Threading/ManualResetEvent.xml b/xml/System.Threading/ManualResetEvent.xml index a060d9f05211d..32dd05d601587 100644 --- a/xml/System.Threading/ManualResetEvent.xml +++ b/xml/System.Threading/ManualResetEvent.xml @@ -32,7 +32,7 @@ derives from the new class. A is functionally equivalent to an created with . + In the .NET Framework version 2.0, derives from the new class. A is functionally equivalent to an created with . > [!NOTE] > Unlike the class, the class provides access to named system synchronization events. diff --git a/xml/System.Threading/Monitor.xml b/xml/System.Threading/Monitor.xml index 2bee8b9875e8c..6c5630ff73b67 100644 --- a/xml/System.Threading/Monitor.xml +++ b/xml/System.Threading/Monitor.xml @@ -32,7 +32,7 @@ class allows you to synchronize access to a region of code by taking and releasing a lock on a particular object by calling the , , and methods. Object locks provide the ability to restrict access to a block of code, commonly called a critical section. While a thread owns the lock for an object, no other thread can acquire that lock. You can also use the class to ensure that no other thread is allowed to access a section of application code being executed by the lock owner, unless the other thread is executing the code using a different locked object. + The class allows you to synchronize access to a region of code by taking and releasing a lock on a particular object by calling the , , and methods. Object locks provide the ability to restrict access to a block of code, commonly called a critical section. While a thread owns the lock for an object, no other thread can acquire that lock. You can also use the class to ensure that no other thread is allowed to access a section of application code being executed by the lock owner, unless the other thread is executing the code using a different locked object. In this article: @@ -83,7 +83,7 @@ [!code-csharp[Conceptual.Monitors#2](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.monitors/cs/badlock1.cs#2)] [!code-vb[Conceptual.Monitors#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.monitors/vb/badlock1.vb#2)] - Each task throws a exception because the `nTasks` variable is boxed before the call to the method in each task. In other words, each method call is passed a separate variable that is independent of the others. `nTasks` is boxed again in the call to the method. Once again, this creates ten new boxed variables, which are independent of each other, `nTasks`, and the ten boxed variables created in the call to the method. The exception is thrown, then, because our code is attempting to release a lock on a newly created variable that was not previously locked. + Each task throws a exception because the `nTasks` variable is boxed before the call to the method in each task. In other words, each method call is passed a separate variable that is independent of the others. `nTasks` is boxed again in the call to the method. Once again, this creates ten new boxed variables, which are independent of each other, `nTasks`, and the ten boxed variables created in the call to the method. The exception is thrown, then, because our code is attempting to release a lock on a newly created variable that was not previously locked. Although you can box a value type variable before calling and , as shown in the following example, and pass the same boxed object to both methods, there is no advantage to doing this. Changes to the unboxed variable are not reflected in the boxed copy, and there is no way to change the value of the boxed copy. @@ -99,7 +99,7 @@ Use the and methods to mark the beginning and end of a critical section. > [!NOTE] -> The functionality provided by the and methods is identical to that provided by the [lock](~/docs/csharp/language-reference/keywords/lock-statement.md) statement in C# and the [SyncLock](~/docs/visual-basic/language-reference/statements/synclock-statement.md) statement in Visual Basic, except that the language constructs wrap the method overload and the method in a `try`…`finally` block to ensure that the monitor is released. +> The functionality provided by the and methods is identical to that provided by the [lock](~/docs/csharp/language-reference/keywords/lock-statement.md) statement in C# and the [SyncLock](~/docs/visual-basic/language-reference/statements/synclock-statement.md) statement in Visual Basic, except that the language constructs wrap the method overload and the method in a `try`…`finally` block to ensure that the monitor is released. If the critical section is a set of contiguous instructions, then the lock acquired by the method guarantees that only a single thread can execute the enclosed code with the locked object. In this case, we recommend that you place that code in a `try` block and place the call to the method in a `finally` block. This ensures that the lock is released even if an exception occurs. The following code fragment illustrates this pattern. @@ -108,7 +108,7 @@ This facility is typically used to synchronize access to a static or instance method of a class. - If a critical section spans an entire method, the locking facility can be achieved by placing the on the method, and specifying the value in the constructor of . When you use this attribute, the and method calls are not needed. The following code fragment illustrates this pattern: + If a critical section spans an entire method, the locking facility can be achieved by placing the on the method, and specifying the value in the constructor of . When you use this attribute, the and method calls are not needed. The following code fragment illustrates this pattern: [!code-csharp[System.Threading.Monitor.Class#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.monitor.class/cs/Pattern2.cs#3)] [!code-vb[System.Threading.Monitor.Class#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.monitor.class/vb/Pattern2.vb#3)] @@ -119,9 +119,9 @@ ## Pulse, PulseAll, and Wait - Once a thread owns the lock and has entered the critical section that the lock protects, it can call the , , and methods. + Once a thread owns the lock and has entered the critical section that the lock protects, it can call the , , and methods. - releases the lock if it is held, allows a waiting thread or threads to obtain the lock and enter the critical section, and waits to be notified by a call to the or method. When is notified, it returns and obtains the lock again. + releases the lock if it is held, allows a waiting thread or threads to obtain the lock and enter the critical section, and waits to be notified by a call to the or method. When is notified, it returns and obtains the lock again. Both and signal for the next thread in the wait queue to proceed. @@ -141,18 +141,18 @@ [!code-csharp[System.Threading.Monitor.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.monitor.class/cs/example1.cs#1)] [!code-vb[System.Threading.Monitor.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.monitor.class/vb/example1.vb#1)] - Because they can be accessed from any task running on a thread pool thread, access to the variables `total` and `n` must also be synchronized. The method is used for this purpose. + Because they can be accessed from any task running on a thread pool thread, access to the variables `total` and `n` must also be synchronized. The method is used for this purpose. - The following example demonstrates the combined use of the class (implemented with the `lock` or `SyncLock` language construct), the class, and the class. It defines two `internal` (in C#) or `Friend` (in Visual Basic) classes, `SyncResource` and `UnSyncResource`, that respectively provide synchronized and unsynchronized access to a resource. To ensure that the example illustrates the difference between the synchronized and unsynchronized access (which could be the case if each method call completes rapidly), the method includes a random delay: for threads whose property is even, the method calls to introduce a delay of 2,000 milliseconds. Note that, because the `SyncResource` class is not public, none of the client code takes a lock on the synchronized resource; the internal class itself takes the lock. This prevents malicious code from taking a lock on a public object. + The following example demonstrates the combined use of the class (implemented with the `lock` or `SyncLock` language construct), the class, and the class. It defines two `internal` (in C#) or `Friend` (in Visual Basic) classes, `SyncResource` and `UnSyncResource`, that respectively provide synchronized and unsynchronized access to a resource. To ensure that the example illustrates the difference between the synchronized and unsynchronized access (which could be the case if each method call completes rapidly), the method includes a random delay: for threads whose property is even, the method calls to introduce a delay of 2,000 milliseconds. Note that, because the `SyncResource` class is not public, none of the client code takes a lock on the synchronized resource; the internal class itself takes the lock. This prevents malicious code from taking a lock on a public object. [!code-csharp[Conceptual.Monitors#1](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.monitors/cs/source.cs#1)] [!code-vb[Conceptual.Monitors#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.monitors/vb/source.vb#1)] - The example defines a variable, `numOps`, that defines the number of threads that will attempt to access the resource. The application thread calls the method for synchronized and unsynchronized access five times each. The method has a single parameter, a delegate that accepts no parameters and returns no value. For synchronized access, it invokes the `SyncUpdateResource` method; for unsynchronized access, it invokes the `UnSyncUpdateResource` method. After each set of method calls, the application thread calls the [AutoResetEvent.WaitOne](xref:System.Threading.WaitHandle.WaitOne*) method so that it blocks until the instance is signaled. + The example defines a variable, `numOps`, that defines the number of threads that will attempt to access the resource. The application thread calls the method for synchronized and unsynchronized access five times each. The method has a single parameter, a delegate that accepts no parameters and returns no value. For synchronized access, it invokes the `SyncUpdateResource` method; for unsynchronized access, it invokes the `UnSyncUpdateResource` method. After each set of method calls, the application thread calls the [AutoResetEvent.WaitOne](xref:System.Threading.WaitHandle.WaitOne*) method so that it blocks until the instance is signaled. - Each call to the `SyncUpdateResource` method calls the internal `SyncResource.Access` method and then calls the method to decrement the `numOps` counter. The method Is used to decrement the counter, because otherwise you cannot be certain that a second thread will access the value before a first thread's decremented value has been stored in the variable. When the last synchronized worker thread decrements the counter to zero, indicating that all synchronized threads have completed accessing the resource, the `SyncUpdateResource` method calls the method, which signals the main thread to continue execution. + Each call to the `SyncUpdateResource` method calls the internal `SyncResource.Access` method and then calls the method to decrement the `numOps` counter. The method Is used to decrement the counter, because otherwise you cannot be certain that a second thread will access the value before a first thread's decremented value has been stored in the variable. When the last synchronized worker thread decrements the counter to zero, indicating that all synchronized threads have completed accessing the resource, the `SyncUpdateResource` method calls the method, which signals the main thread to continue execution. - Each call to the `UnSyncUpdateResource` method calls the internal `UnSyncResource.Access` method and then calls the method to decrement the `numOps` counter. Once again, the method Is used to decrement the counter to ensure that a second thread does not access the value before a first thread's decremented value has been assigned to the variable. When the last unsynchronized worker thread decrements the counter to zero, indicating that no more unsynchronized threads need to access the resource, the `UnSyncUpdateResource` method calls the method, which signals the main thread to continue execution. + Each call to the `UnSyncUpdateResource` method calls the internal `UnSyncResource.Access` method and then calls the method to decrement the `numOps` counter. Once again, the method Is used to decrement the counter to ensure that a second thread does not access the value before a first thread's decremented value has been assigned to the variable. When the last unsynchronized worker thread decrements the counter to zero, indicating that no more unsynchronized threads need to access the resource, the `UnSyncUpdateResource` method calls the method, which signals the main thread to continue execution. As the output from the example shows, synchronized access ensures that the calling thread exits the protected resource before another thread can access it; each thread waits on its predecessor. On the other hand, without the lock, the `UnSyncResource.Access` method is called in the order in which threads reach it. diff --git a/xml/System.Threading/Mutex.xml b/xml/System.Threading/Mutex.xml index 360be9bb308fa..cf5e354386565 100644 --- a/xml/System.Threading/Mutex.xml +++ b/xml/System.Threading/Mutex.xml @@ -41,7 +41,7 @@ > [!IMPORTANT] > This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - You can use the method to request ownership of a mutex. The calling thread blocks until one of the following occurs: + You can use the method to request ownership of a mutex. The calling thread blocks until one of the following occurs: - The mutex is signaled to indicate that it is not owned. When this happens, the method returns `true`, and the calling thread assumes ownership of the mutex and accesses the resource protected by the mutex. When it has finished accessing the resource, the thread must call the method to release ownership of the mutex. The first example in the Examples section illustrates this pattern. @@ -51,7 +51,7 @@ The thread that owns a mutex can request the same mutex in repeated calls to without blocking its execution. However, the thread must call the method the same number of times to release ownership of the mutex. - Because the class inherits from , you can also call the static and methods to synchronize access to a protected resource. + Because the class inherits from , you can also call the static and methods to synchronize access to a protected resource. If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the abandoned mutex. Before version 2.0 of the .NET Framework, no exception was thrown. @@ -220,7 +220,7 @@ This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. @@ -296,7 +296,7 @@ This constructor initializes a object that represents a named system mutex. You can create multiple objects that represent the same named system mutex. - If the named mutex has already been created with access control security, and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security, and the caller does not have rights, an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. @@ -367,7 +367,7 @@ > [!NOTE] > The caller has full control over the newly created object even if `mutexSecurity` denies or fails to grant some access rights to the current user. However, if the current user attempts to get another object to represent the same named mutex, using either a constructor or the method, Windows access control security is applied. - If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. + If the named mutex has already been created with access control security, and the caller does not have , an exception is thrown. To open an existing named mutex with only those permissions needed for synchronizing thread activities, see the method. If you specify `null` or an empty string for `name`, a local mutex is created, as if you had called the constructor. In this case, `createdNew` is always `true`. @@ -421,9 +421,9 @@ method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + The method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . - The user must have to call this method, and the mutex must have been opened with . + The user must have to call this method, and the mutex must have been opened with . @@ -488,9 +488,9 @@ Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. - Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. + Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. This method does not request ownership of the mutex. @@ -551,7 +551,7 @@ flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. + The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. The method tries to open an existing named mutex. If the system mutex does not exist, this method throws an exception instead of creating the system object. To create the system mutex when it does not already exist, use one of the constructors that has a `name` parameter. @@ -676,7 +676,7 @@ rights to call this method, and the mutex must have been opened with . + The user must have rights to call this method, and the mutex must have been opened with . @@ -748,7 +748,7 @@ Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to wait on the mutex, and specifying the flag allows a thread to call the method. This method does not request ownership of the mutex. @@ -800,7 +800,7 @@ If you are uncertain whether a named mutex exists, use this method overload instead of the method overload, which throws an exception if the mutex does not exist. - The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. + The `rights` parameter must include the flag to allow threads to wait on the mutex, and the flag to allow threads to call the method. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system mutex. diff --git a/xml/System.Threading/Overlapped.xml b/xml/System.Threading/Overlapped.xml index 77515de6fe2df..7213d8c787748 100644 --- a/xml/System.Threading/Overlapped.xml +++ b/xml/System.Threading/Overlapped.xml @@ -101,7 +101,7 @@ property to get the handle of any managed synchronization event that derives from the class. + Use the property to get the handle of any managed synchronization event that derives from the class. Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. @@ -143,7 +143,7 @@ class, use the property to get a object, and then call the method. + To get the handle of a managed synchronization object that derives from the class, use the property to get a object, and then call the method. Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. @@ -213,7 +213,7 @@ ## Remarks This property cannot be used on 64-bit platforms. Use the property instead. - Use the property to get the handle of any managed synchronization event that derives from the class. + Use the property to get the handle of any managed synchronization event that derives from the class. ]]> @@ -252,7 +252,7 @@ class, use the property to get a object, and then call the method. + To get the handle of a managed synchronization object that derives from the class, use the property to get a object, and then call the method. ]]> diff --git a/xml/System.Threading/ParameterizedThreadStart.xml b/xml/System.Threading/ParameterizedThreadStart.xml index 6e2638c8ecf85..6f044b821e0d1 100644 --- a/xml/System.Threading/ParameterizedThreadStart.xml +++ b/xml/System.Threading/ParameterizedThreadStart.xml @@ -39,11 +39,11 @@ ## Remarks When a managed thread is created, the method that executes on the thread is represented by: -- A delegate that is passed to the constructor. Any method that has no parameters and that returns `void` in C# or is a `Sub` procedure in Visual Basic can represent the delegate. +- A delegate that is passed to the constructor. Any method that has no parameters and that returns `void` in C# or is a `Sub` procedure in Visual Basic can represent the delegate. -- A delegate that is passed to the constructor. Any method that has a single parameter of type and that returns void in C# or is a Sub procedure in Visual Basic can represent the delegate. +- A delegate that is passed to the constructor. Any method that has a single parameter of type and that returns void in C# or is a Sub procedure in Visual Basic can represent the delegate. - The thread does not begin executing until the method is called. The or delegate is invoked on the thread, and execution begins at the first line of the method represented by the delegate. In the case of the delegate, the object that is passed to the method is passed to the delegate. + The thread does not begin executing until the method is called. The or delegate is invoked on the thread, and execution begins at the first line of the method represented by the delegate. In the case of the delegate, the object that is passed to the method is passed to the delegate. > [!NOTE] > Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. @@ -51,7 +51,7 @@ > [!NOTE] > When you create a delegate for an instance method in C++, the first parameter of the constructor is the instance variable. For a static method, the first parameter of the constructor is zero. For a static method, the delegate constructor requires only one parameter: the address of the callback method, qualified by the class name. - The delegate and the method overload make it easy to pass data to a thread procedure, but this technique is not type safe because any object can be passed to . A more robust way to pass data to a thread procedure is to put both the thread procedure and the data fields into a worker object. For more information, see [Creating Threads and Passing Data at Start Time](~/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md). + The delegate and the method overload make it easy to pass data to a thread procedure, but this technique is not type safe because any object can be passed to . A more robust way to pass data to a thread procedure is to put both the thread procedure and the data fields into a worker object. For more information, see [Creating Threads and Passing Data at Start Time](~/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md). The delegate supports only a single parameter. You can pass multiple data items to the by making that parameter one of the following: diff --git a/xml/System.Threading/ReaderWriterLock.xml b/xml/System.Threading/ReaderWriterLock.xml index eb1a2817146b0..e93a89eb381f9 100644 --- a/xml/System.Threading/ReaderWriterLock.xml +++ b/xml/System.Threading/ReaderWriterLock.xml @@ -53,7 +53,7 @@ If the time-out interval expires and the lock request has not been granted, the method returns control to the calling thread by throwing an . A thread can catch this exception and determine what action to take next. - Time-outs are expressed in milliseconds. If you use a to specify the time-out, the value used is the total number of whole milliseconds represented by the . The following table shows the valid time-out values in milliseconds. + Time-outs are expressed in milliseconds. If you use a to specify the time-out, the value used is the total number of whole milliseconds represented by the . The following table shows the valid time-out values in milliseconds. |Value|Description| |-----------|-----------------| diff --git a/xml/System.Threading/ReaderWriterLockSlim.xml b/xml/System.Threading/ReaderWriterLockSlim.xml index 2feb546252e1a..0cb1860ca5200 100644 --- a/xml/System.Threading/ReaderWriterLockSlim.xml +++ b/xml/System.Threading/ReaderWriterLockSlim.xml @@ -36,7 +36,7 @@ > [!NOTE] > is similar to , but it has simplified rules for recursion and for upgrading and downgrading lock state. avoids many cases of potential deadlock. In addition, the performance of is significantly better than . is recommended for all new development. - By default, new instances of are created with the flag and do not allow recursion. This default policy is recommended for all new development, because recursion introduces unnecessary complications and makes your code more prone to deadlocks. To simplify migration from existing projects that use or , you can use the flag to create instances of that allow recursion. + By default, new instances of are created with the flag and do not allow recursion. This default policy is recommended for all new development, because recursion introduces unnecessary complications and makes your code more prone to deadlocks. To simplify migration from existing projects that use or , you can use the flag to create instances of that allow recursion. A thread can enter the lock in three modes: read mode, write mode, and upgradeable read mode. (In the rest of this topic, "upgradeable read mode" is referred to as "upgradeable mode", and the phrase "enter `x` mode" is used in preference to the longer phrase "enter the lock in `x` mode".) @@ -76,7 +76,7 @@ After downgrading to read mode, a thread cannot reenter upgradeable mode until it has exited from read mode. ## Entering the Lock Recursively - You can create a that supports recursive lock entry by using the constructor that specifies lock policy, and specifying . + You can create a that supports recursive lock entry by using the constructor that specifies lock policy, and specifying . > [!NOTE] > The use of recursion is not recommended for new development, because it introduces unnecessary complications and makes your code more prone to deadlocks. @@ -188,7 +188,7 @@ that is initialized with this constructor does not allow recursion. That is, the property returns . + A that is initialized with this constructor does not allow recursion. That is, the property returns . For more information about recursion policy and its effects, see the enumeration and the class. @@ -251,7 +251,7 @@ and a thread has entered the lock in read mode, is thrown if the thread tries to reenter the lock in read mode. Similarly, if a thread has entered the lock in write mode, is thrown if the thread tries to reenter the lock in any mode. + Recursion policy determines the restrictions on threads that enter the lock more than once. For example, if a lock was created with and a thread has entered the lock in read mode, is thrown if the thread tries to reenter the lock in read mode. Similarly, if a thread has entered the lock in write mode, is thrown if the thread tries to reenter the lock in any mode. > [!NOTE] > A thread in upgradeable mode can upgrade to write mode or downgrade to read mode regardless of the lock recursion policy setting. @@ -265,7 +265,7 @@ ## Examples The following example shows two exception scenarios, one that depends on the setting and one that does not. - In the first scenario, the thread enters read mode and then tries to enter read mode recursively. If the is created by using the default constructor, which sets recursion policy to , an exception is thrown. If is used to create the , no exception is thrown. + In the first scenario, the thread enters read mode and then tries to enter read mode recursively. If the is created by using the default constructor, which sets recursion policy to , an exception is thrown. If is used to create the , no exception is thrown. In the second scenario, the thread enters read mode and then tries to enter write mode. is thrown regardless of the lock recursion policy. @@ -921,7 +921,7 @@ and a thread has entered the lock in read mode, is thrown if the thread tries to reenter the lock in read mode. + Recursion policy determines the restrictions on threads that enter the lock more than once. For example, if a lock was created with and a thread has entered the lock in read mode, is thrown if the thread tries to reenter the lock in read mode. > [!NOTE] > A thread in upgradeable mode can upgrade to write mode or downgrade to read mode regardless of the lock recursion policy setting. diff --git a/xml/System.Threading/Semaphore.xml b/xml/System.Threading/Semaphore.xml index 398ec1ba437f4..b85d19c1966eb 100644 --- a/xml/System.Threading/Semaphore.xml +++ b/xml/System.Threading/Semaphore.xml @@ -49,7 +49,7 @@ ## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. [!code-cpp[System.Threading.Semaphore2#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore2/CPP/source.cpp#1)] [!code-csharp[System.Threading.Semaphore2#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.Semaphore2/CS/source.cs#1)] @@ -104,7 +104,7 @@ ## Examples - The following example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. + The following example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. [!code-cpp[System.Threading.Semaphore2#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Semaphore2/CPP/source.cpp#1)] [!code-csharp[System.Threading.Semaphore2#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.Semaphore2/CS/source.cs#1)] @@ -374,9 +374,9 @@ method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . + The method uses the following combination of flags (combined using the bitwise OR operation) to search for permissions: , , and . - The user must have rights to call this method, and the semaphore must have been opened with rights. + The user must have rights to call this method, and the semaphore must have been opened with rights. On a local semaphore, access control security is irrelevant. If the object does not represent a named system semaphore, this method returns a object that grants all rights to any user. @@ -443,9 +443,9 @@ Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. - Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. + Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. @@ -506,7 +506,7 @@ flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. + The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. The method tries to open an existing named semaphore. If the system semaphore does not exist, this method throws an exception instead of creating the system semaphore. To create the system semaphore when it does not already exist, use one of the constructors that has a `name` parameter. @@ -588,12 +588,12 @@ If a is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. - If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. + If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. ## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. @@ -655,12 +655,12 @@ If a is thrown by the method, it does not necessarily indicate a problem with the calling thread. A programming error in another thread might have caused that thread to exit the semaphore more times than it entered. - If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. + If the current object represents a named system semaphore, the user must have rights and the semaphore must have been opened with rights. ## Examples - The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. + The following code example creates a semaphore with a maximum count of three and an initial count of zero. The example starts five threads, which block waiting for the semaphore. The main thread uses the method overload to increase the semaphore count to its maximum, allowing three threads to enter the semaphore. Each thread uses the method to wait for one second, to simulate work, and then calls the method overload to release the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread, to make the output easier to read. @@ -706,7 +706,7 @@ ## Remarks You can set access control security only on objects that represent named system semaphores. - The user must have rights to call this method, and the semaphore must have been opened with rights. + The user must have rights to call this method, and the semaphore must have been opened with rights. @@ -776,7 +776,7 @@ If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. - This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. + This method overload is equivalent to calling the method overload and specifying and rights, combined by using the bitwise OR operation. Specifying the flag allows a thread to enter the semaphore, and specifying the flag allows a thread to call the method. ]]> @@ -825,7 +825,7 @@ If you are uncertain whether a named semaphore exists, use this method overload instead of the method overload, which throws an exception if the semaphore does not exist. - The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. + The `rights` parameter must include the flag to allow threads to enter the semaphore, and the flag to allow threads to call the method. Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system semaphore. diff --git a/xml/System.Threading/SemaphoreFullException.xml b/xml/System.Threading/SemaphoreFullException.xml index e8c1d8b18f4f3..4db8708618531 100644 --- a/xml/System.Threading/SemaphoreFullException.xml +++ b/xml/System.Threading/SemaphoreFullException.xml @@ -36,10 +36,10 @@ method at this point, a is thrown. + The count on a semaphore is decremented each time a thread enters the semaphore, and incremented when a thread releases the semaphore. When the count is zero, subsequent requests block until other threads release the semaphore. When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created. If a programming error causes a thread to call the method at this point, a is thrown. > [!NOTE] -> The class does not enforce thread identity on calls to the and methods. It is not necessary for the same thread that called to call . +> The class does not enforce thread identity on calls to the and methods. It is not necessary for the same thread that called to call . does not necessarily indicate a problem with the code where the exception occurred. Consider the following scenario: Thread A and thread B enter a semaphore that has a maximum count of two. A programming error in thread B causes it to call twice, so that the count on the semaphore is full. As a result, when thread A eventually calls , a is thrown. diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index 7a7ea779f78a8..853ef7dd955bb 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -137,9 +137,9 @@ You can do either of the following to ensure that all of the threads executing in an application share the same culture and UI culture: -- You can pass a object that represents that culture to the delegate or the method. +- You can pass a object that represents that culture to the delegate or the method. -- For apps running on the [!INCLUDE[net_v45](~/includes/net-v45-md.md)] and later versions, you can define the culture and UI culture that is to be assigned to all threads created in an application domain by setting the value of the and properties. Note that this is a per-application domain setting. +- For apps running on the [!INCLUDE[net_v45](~/includes/net-v45-md.md)] and later versions, you can define the culture and UI culture that is to be assigned to all threads created in an application domain by setting the value of the and properties. Note that this is a per-application domain setting. For more information and examples, see the "Culture and threads" section of the class topic. @@ -752,7 +752,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. An attempt to use the property to set the apartment state of a thread whose apartment state has already been set is ignored. However, the method throws a in this case. > [!IMPORTANT] -> In the .NET Framework version 2.0, new threads are initialized as if their apartment state has not been set before they are started. The main application thread is initialized to by default. You can no longer set the main application thread to by setting the property on the first line of code. Use the instead. +> In the .NET Framework version 2.0, new threads are initialized as if their apartment state has not been set before they are started. The main application thread is initialized to by default. You can no longer set the main application thread to by setting the property on the first line of code. Use the instead. In the .NET Framework version 2.0, you can specify the COM threading model for a C++ application using the [/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)](http://msdn.microsoft.com/library/4907e9ef-5031-446c-aecf-0a0b32fae1e8) linker option. @@ -932,7 +932,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. object that is returned by this property, together with its associated objects, determine the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default culture is determined, and how users set culture information for their computers. + The object that is returned by this property, together with its associated objects, determine the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default culture is determined, and how users set culture information for their computers. Beginning with the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)], you can set the property to a neutral culture. This is because the behavior of the class has changed: When it represents a neutral culture, its property values (in particular, the , , , , and properties) now reflect the specific culture that is associated with the neutral culture. In earlier versions of the .NET Framework, the property threw a exception when a neutral culture was assigned. @@ -1030,7 +1030,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. [!code-csharp[System.Threading.Thread.CurrentThread#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.thread.currentthread/cs/currentthread2.cs#1)] [!code-vb[System.Threading.Thread.CurrentThread#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.thread.currentthread/vb/currentthread2.vb#1)] - Each child task generates 1 million random numbers between 1 and 1 million and returns their mean. The parent task calls the method to ensure that the child tasks have completed before displaying the mean returned by each task and calculating the mean of means. + Each child task generates 1 million random numbers between 1 and 1 million and returns their mean. The parent task calls the method to ensure that the child tasks have completed before displaying the mean returned by each task and calculating the mean of means. Note that while the application runs on a foreground thread, each task runs on a thread pool thread. @@ -1071,12 +1071,12 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default UI culture is determined. + The UI culture specifies the resources an application needs to support user input and output, and by default is the same as the operating system culture. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default UI culture is determined. - The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. + The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. > [!NOTE] -> The method throws for the neutral cultures "zh-Hant" ("zh-CHT") and "zh-Hans" ("zh-CHS"). +> The method throws for the neutral cultures "zh-Hant" ("zh-CHT") and "zh-Hans" ("zh-CHS"). @@ -1134,7 +1134,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. Such applications can use the method to prevent the CLR from doing automatic reclamation of runtime callable wrappers. - When this method has been called on a thread, automatic cleanup cannot be re-enabled for that thread. When your application is ready to clean up runtime callable wrappers, use the method to instruct the runtime to clean up all runtime callable wrappers in the current context. Message pumping occurs while the method executes. + When this method has been called on a thread, automatic cleanup cannot be re-enabled for that thread. When your application is ready to clean up runtime callable wrappers, use the method to instruct the runtime to clean up all runtime callable wrappers in the current context. Message pumping occurs while the method executes. ]]> @@ -1361,7 +1361,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. > [!IMPORTANT] > The .NET Framework provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](~/docs/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots.md). - After any thread calls `FreeNamedDataSlot`, any other thread that calls with the same name will allocate a new slot associated with the name. Subsequent calls to `GetNamedDataSlot` by any thread will return the new slot. However, any thread that still has a returned by an earlier call to `GetNamedDataSlot` can continue to use the old slot. + After any thread calls `FreeNamedDataSlot`, any other thread that calls with the same name will allocate a new slot associated with the name. Subsequent calls to `GetNamedDataSlot` by any thread will return the new slot. However, any thread that still has a returned by an earlier call to `GetNamedDataSlot` can continue to use the old slot. A slot that has been associated with a name is released only when every `LocalDataStoreSlot` that was obtained prior to the call to `FreeNamedDataSlot` has been released and garbage-collected. @@ -1426,7 +1426,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. ## Examples - The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. + The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. After the thread is started, the method is used again. This time it throws because the thread has already been started. @@ -1962,7 +1962,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. > [!WARNING] > You should never call the method of the object that represents the current thread from the current thread. This causes your app to hang because the current thread waits upon itself indefinitely, - This method changes the state of the calling thread to include . You cannot invoke `Join` on a thread that is in the state. + This method changes the state of the calling thread to include . You cannot invoke `Join` on a thread that is in the state. ]]> @@ -2014,11 +2014,11 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. [!code-csharp[System.Threading.Thread.Join#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.thread.join/cs/join1b.cs#2)] [!code-vb[System.Threading.Thread.Join#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.thread.join/vb/join1b.vb#2)] - If is specified for the `millisecondsTimeout` parameter, this method behaves identically to the method overload, except for the return value. + If is specified for the `millisecondsTimeout` parameter, this method behaves identically to the method overload, except for the return value. If the thread has already terminated when is called, the method returns immediately. - This method changes the state of the calling thread to include . You cannot invoke `Join` on a thread that is in the state. + This method changes the state of the calling thread to include . You cannot invoke `Join` on a thread that is in the state. ]]> @@ -2064,11 +2064,11 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. [!code-csharp[System.Threading.Thread.Join#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.thread.join/cs/join1c.cs#3)] [!code-vb[System.Threading.Thread.Join#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.thread.join/vb/join1c.vb#3)] - If is specified for `timeout`, this method behaves identically to the method overload, except for the return value. + If is specified for `timeout`, this method behaves identically to the method overload, except for the return value. If the thread has already terminated when is called, the method returns immediately. - This method changes the state of the current thread to include . You cannot invoke `Join` on a thread that is in the state. + This method changes the state of the current thread to include . You cannot invoke `Join` on a thread that is in the state. @@ -2268,7 +2268,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. ## Examples - The following example shows the result of changing the priority of a thread. Three threads are created, the priority of one thread is set to , and the priority of a second is set to . Each thread increments a variable in a `while` loop and runs for a set time. + The following example shows the result of changing the priority of a thread. Three threads are created, the priority of one thread is set to , and the priority of a second is set to . Each thread increments a variable in a `while` loop and runs for a set time. [!code-csharp[System.Threading.ThreadPriority#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.Threading.ThreadPriority/cs/Example1.cs#1)] [!code-vb[System.Threading.ThreadPriority#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.Threading.ThreadPriority/vb/Example1.vb#1)] @@ -2404,17 +2404,17 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. if their apartment state has not been set before they are started. Apartment state must be set before a thread is started. + New threads are initialized as if their apartment state has not been set before they are started. Apartment state must be set before a thread is started. > [!NOTE] -> The main application thread is initialized to by default. The only way to set the apartment state of the main application thread to is to apply the attribute to the entry point method. +> The main application thread is initialized to by default. The only way to set the apartment state of the main application thread to is to apply the attribute to the entry point method. The method, along with the method and the method, replaces the property. ## Examples - The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. + The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. After the thread is started, the method is used again. This time it throws because the thread has already been started. @@ -2583,7 +2583,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. ## Remarks The thread will not be scheduled for execution by the operating system for the amount of time specified. This method changes the state of the thread to include . - You can specify for the `millisecondsTimeout` parameter to suspend the thread indefinitely. However, we recommend that you use other classes such as , , , or instead to sychronize threads or manage resources. + You can specify for the `millisecondsTimeout` parameter to suspend the thread indefinitely. However, we recommend that you use other classes such as , , , or instead to sychronize threads or manage resources. The system clock ticks at a specific rate called the clock resolution. The actual timeout might not be exactly the specified timeout, because the specified timeout will be adjusted to coincide with clock ticks. For more information on clock resolution and the waiting time, see the [Sleep function](http://msdn.microsoft.com/library/windows/desktop/ms686298.aspx) topic. This method calls the [Sleep function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686298.aspx) from the Windows system APIs. @@ -2640,7 +2640,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. ## Remarks The thread will not be scheduled for execution by the operating system for the amount of time specified. This method changes the state of the thread to include . - You can specify for the `timeout` parameter to suspend the thread indefinitely. However, we recommend that you use other classes such as , , , or instead to sychronize threads or manage resources. + You can specify for the `timeout` parameter to suspend the thread indefinitely. However, we recommend that you use other classes such as , , , or instead to sychronize threads or manage resources. This overload of uses the total number of whole milliseconds in `timeout`. Fractional milliseconds are discarded. @@ -2703,7 +2703,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. Contrast this with the method. A thread that calls yields the rest of its current slice of processor time, even if the specified interval is zero. Specifying a non-zero interval for removes the thread from consideration by the thread scheduler until the time interval has elapsed. - is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the .NET Framework; for example, call or a statement that wraps (`lock` in C# or `SyncLock` in Visual Basic). + is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the .NET Framework; for example, call or a statement that wraps (`lock` in C# or `SyncLock` in Visual Basic). > [!CAUTION] > In the rare case where it is advantageous to avoid a context switch, such as when you know that a state change is imminent, make a call to the method in your loop. The code executes is designed to prevent problems that can occur on computers with multiple processors. For example, on computers with multiple Intel processors employing Hyper-Threading technology, prevents processor starvation in certain situations. @@ -2741,7 +2741,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. state, the operating system can schedule it for execution. The thread begins executing at the first line of the method represented by the or delegate supplied to the thread constructor. Note that the call to does not block the calling thread. + Once a thread is in the state, the operating system can schedule it for execution. The thread begins executing at the first line of the method represented by the or delegate supplied to the thread constructor. Note that the call to does not block the calling thread. > [!NOTE] > If this overload is used with a thread created using a delegate, `null` is passed to the method executed by the thread. @@ -2795,7 +2795,7 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. state, the operating system can schedule it for execution. The thread begins executing at the first line of the method represented by the or delegate supplied to the thread constructor. Note that the call to does not block the calling thread. + Once a thread is in the state, the operating system can schedule it for execution. The thread begins executing at the first line of the method represented by the or delegate supplied to the thread constructor. Note that the call to does not block the calling thread. Once the thread terminates, it cannot be restarted with another call to `Start`. @@ -3087,17 +3087,17 @@ Main thread: ThreadProc.Join has returned. Press Enter to end program. if their apartment state has not been set before they are started. Apartment state must be set before a thread is started. + New threads are initialized as if their apartment state has not been set before they are started. Apartment state must be set before a thread is started. > [!NOTE] -> The main application thread is initialized to by default. The only way to set the apartment state of the main application thread to is to apply the attribute to the entry point method. +> The main application thread is initialized to by default. The only way to set the apartment state of the main application thread to is to apply the attribute to the entry point method. The method, along with the method and the method, replaces the property. ## Examples - The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. + The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. After the thread is started, the method is used again. This time it throws because the thread has already been started. diff --git a/xml/System.Threading/ThreadAbortException.xml b/xml/System.Threading/ThreadAbortException.xml index ac3fffdf0222d..4d85473ba469a 100644 --- a/xml/System.Threading/ThreadAbortException.xml +++ b/xml/System.Threading/ThreadAbortException.xml @@ -30,10 +30,10 @@ method to destroy a thread, the common language runtime throws a . is a special exception that can be caught, but it will automatically be raised again at the end of the `catch` block. When this exception is raised, the runtime executes all the `finally` blocks before ending the thread. Because the thread can do an unbounded computation in the `finally` blocks or call to cancel the abort, there is no guarantee that the thread will ever end. If you want to wait until the aborted thread has ended, you can call the method. is a blocking call that does not return until the thread actually stops executing. + When a call is made to the method to destroy a thread, the common language runtime throws a . is a special exception that can be caught, but it will automatically be raised again at the end of the `catch` block. When this exception is raised, the runtime executes all the `finally` blocks before ending the thread. Because the thread can do an unbounded computation in the `finally` blocks or call to cancel the abort, there is no guarantee that the thread will ever end. If you want to wait until the aborted thread has ended, you can call the method. is a blocking call that does not return until the thread actually stops executing. > [!NOTE] -> When the common language runtime (CLR) stops background threadsafter all foreground threads in a managed executable have ended, it does not use . Therefore, you cannot use to detect when background threads are being terminated by the CLR. +> When the common language runtime (CLR) stops background threadsafter all foreground threads in a managed executable have ended, it does not use . Therefore, you cannot use to detect when background threads are being terminated by the CLR. uses the HRESULT COR_E_THREADABORTED, which has the value 0x80131530. diff --git a/xml/System.Threading/ThreadPool.xml b/xml/System.Threading/ThreadPool.xml index b6c3fb4788e0c..2add2f106c5cb 100644 --- a/xml/System.Threading/ThreadPool.xml +++ b/xml/System.Threading/ThreadPool.xml @@ -30,7 +30,7 @@ - When you create a or object to perform some task asynchronously, by default the task is scheduled to run on a thread pool thread. -- Asynchronous timers use the thread pool. Thread pool threads execute callbacks from the class and raise events from the class. +- Asynchronous timers use the thread pool. Thread pool threads execute callbacks from the class and raise events from the class. - When you use registered wait handles, a system thread monitors the status of the wait handles. When a wait operation completes, a worker thread from the thread pool executes the corresponding callback function. @@ -80,7 +80,7 @@ [!code-csharp[System.Threading.ThreadPool QueueUserWorkItem0#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/CS/source.cs#1)] [!code-vb[System.Threading.ThreadPool QueueUserWorkItem0#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/VB/source.vb#1)] - If you comment out the call to the method, the main thread exits before method runs on the thread pool thread. The thread pool uses background threads, which do not keep the application running if all foreground threads have terminated. (This is a simple example of a race condition.) + If you comment out the call to the method, the main thread exits before method runs on the thread pool thread. The thread pool uses background threads, which do not keep the application running if all foreground threads have terminated. (This is a simple example of a race condition.) ]]> @@ -391,7 +391,7 @@ > Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. ## Version Information - In the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. + In the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. @@ -456,7 +456,7 @@ > Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. ## Version Information - In the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. + In the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. @@ -521,7 +521,7 @@ that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: @@ -534,14 +534,14 @@ > [!IMPORTANT] > Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Win32 API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. - To cancel the wait operation, call the method. + To cancel the wait operation, call the method. The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. ## Version Information - Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. + Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. ]]> @@ -595,7 +595,7 @@ that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: @@ -608,14 +608,14 @@ > [!IMPORTANT] > Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Win32 API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. - To cancel the wait operation, call the method. + To cancel the wait operation, call the method. The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. ## Version Information - Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. + Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. ]]> @@ -669,7 +669,7 @@ that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: @@ -682,14 +682,14 @@ > [!IMPORTANT] > Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Win32 API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. - To cancel the wait operation, call the method. + To cancel the wait operation, call the method. The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. ## Version Information - Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. + Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. ]]> @@ -747,7 +747,7 @@ that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. The method queues the specified delegate to the thread pool. A worker thread will execute the delegate when one of the following occurs: @@ -760,14 +760,14 @@ > [!IMPORTANT] > Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Win32 API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. Instead of a , use a with a maximum count of 1. - To cancel the wait operation, call the method. + To cancel the wait operation, call the method. The wait thread uses the Win32 `WaitForMultipleObjects` function to monitor registered wait operations. Therefore, if you must use the same native operating system handle in multiple calls to , you must duplicate the handle using the Win32 `DuplicateHandle` function. Note that you should not pulse an event object passed to , because the wait thread might not detect that the event is signaled before it is reset. Before returning, the function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore is decreased by one. ## Version Information - Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. + Starting with the .NET Framework version 2.0, the property value is propagated to worker threads queued using the method. In earlier versions, the principal information is not propagated. @@ -829,7 +829,7 @@ property. In addition, you cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the corresponding minimum number of worker threads or I/O completion threads. To determine the minimum thread pool size, call the method. + You cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the number of processors on the computer. To determine how many processors are present, retrieve the value of the property. In addition, you cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the corresponding minimum number of worker threads or I/O completion threads. To determine the minimum thread pool size, call the method. If the common language runtime is hosted, for example by Internet Information Services (IIS) or SQL Server, the host can limit or prevent changes to the thread pool size. @@ -1064,7 +1064,7 @@ Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Win32 API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. ]]> @@ -1126,7 +1126,7 @@ Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Win32 API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. ]]> @@ -1188,7 +1188,7 @@ Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Win32 API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. ]]> @@ -1254,7 +1254,7 @@ Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Win32 API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. - When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. + When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. ]]> diff --git a/xml/System.Threading/ThreadStart.xml b/xml/System.Threading/ThreadStart.xml index 750564be36371..bef67aba29505 100644 --- a/xml/System.Threading/ThreadStart.xml +++ b/xml/System.Threading/ThreadStart.xml @@ -34,7 +34,7 @@ delegate or a delegate that is passed to the constructor. The thread does not begin executing until the method is called. Execution begins at the first line of the method represented by the or delegate. + When a managed thread is created, the method that executes on the thread is represented by a delegate or a delegate that is passed to the constructor. The thread does not begin executing until the method is called. Execution begins at the first line of the method represented by the or delegate. > [!NOTE] > Visual Basic and C# users can omit the or delegate constructor when creating a thread. In Visual Basic, use the `AddressOf` operator when passing your method to the constructor; for example, `Dim t As New Thread(AddressOf ThreadProc)`. In C#, simply specify the name of the thread procedure. The compiler selects the correct delegate constructor. @@ -49,7 +49,7 @@ ## Examples The following code example shows the syntax for creating and using a delegate with an instance method and with a static method. - For another simple example that demonstrates how to create a delegate, see the method overload. For more information about thread creation, see [Creating Threads and Passing Data at Start Time](~/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md). + For another simple example that demonstrates how to create a delegate, see the method overload. For more information about thread creation, see [Creating Threads and Passing Data at Start Time](~/docs/standard/threading/creating-threads-and-passing-data-at-start-time.md). [!code-cpp[System.Threading.ThreadStart2#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadStart2/CPP/source.cpp#1)] [!code-csharp[System.Threading.ThreadStart2#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.ThreadStart2/CS/source.cs#1)] diff --git a/xml/System.Threading/ThreadState.xml b/xml/System.Threading/ThreadState.xml index 36ef9cb0d3645..7fc133606759c 100644 --- a/xml/System.Threading/ThreadState.xml +++ b/xml/System.Threading/ThreadState.xml @@ -38,14 +38,14 @@ defines a set of all possible execution states for threads. Once a thread is created, it is in at least one of the states until it terminates. Threads created within the common language runtime are initially in the `Unstarted` state, while external threads that come into the runtime are already in the `Running` state. An `Unstarted` thread is transitioned into the `Running` state by calling . Not all combinations of `ThreadState` values are valid; for example, a thread cannot be in both the `Aborted` and `Unstarted` states. > [!IMPORTANT] -> There are two thread state enumerations, and . +> There are two thread state enumerations, and . The following table shows the actions that cause a change of state. |Action|ThreadState| |------------|-----------------| |A thread is created within the common language runtime.|Unstarted| -|Another thread calls the method on the new thread, and the call returns.

The method does not return until the new thread has started running. There is no way to know at what point the new thread will start running, during the call to .|Running| +|Another thread calls the method on the new thread, and the call returns.

The method does not return until the new thread has started running. There is no way to know at what point the new thread will start running, during the call to .|Running| |The thread calls |WaitSleepJoin| |The thread calls on another object.|WaitSleepJoin| |The thread calls on another thread.|WaitSleepJoin| @@ -61,7 +61,7 @@ A thread can be in more than one state at a given time. For example, if a thread is blocked on a call to , and another thread calls on the blocked thread, the blocked thread will be in both the `WaitSleepJoin` and the `AbortRequested` states at the same time. In this case, as soon as the thread returns from the call to or is interrupted, it will receive the to begin aborting. - The property of a thread provides the current state of a thread. Applications must use a bitmask to determine whether a thread is running. Since the value for `Running` is zero (0), test whether a thread is running by using C# code such as `(myThread.ThreadState & (ThreadState.Stopped | ThreadState.Unstarted)) == 0` or Visual Basic code such as `(myThread.ThreadState And (ThreadState.Stopped Or ThreadState.Unstarted)) = 0`. + The property of a thread provides the current state of a thread. Applications must use a bitmask to determine whether a thread is running. Since the value for `Running` is zero (0), test whether a thread is running by using C# code such as `(myThread.ThreadState & (ThreadState.Stopped | ThreadState.Unstarted)) == 0` or Visual Basic code such as `(myThread.ThreadState And (ThreadState.Stopped Or ThreadState.Unstarted)) = 0`. ]]> diff --git a/xml/System.Threading/Timeout.xml b/xml/System.Threading/Timeout.xml index b7a0e24fea779..1feb3b705ccf3 100644 --- a/xml/System.Threading/Timeout.xml +++ b/xml/System.Threading/Timeout.xml @@ -34,7 +34,7 @@ is used by methods that accept an integer `millisecondsTimeout` parameter, such as , , and . is used by methods that accept a `timeout` parameter of type , such as , , and . + The members of this class are used to specify infinite time-out intervals in threading operations. is used by methods that accept an integer `millisecondsTimeout` parameter, such as , , and . is used by methods that accept a `timeout` parameter of type , such as , , and . @@ -82,7 +82,7 @@ and , this value is used to suspend the thread indefinitely. However, in most cases, we recommend that you use other classes such as , , , or instead to sychronize threads or manage resources. + For threading methods that accept a `millisecondsTimeout` parameter, such as and , this value is used to suspend the thread indefinitely. However, in most cases, we recommend that you use other classes such as , , , or instead to sychronize threads or manage resources. The value of this field is -1 (0xFFFFFFFF). @@ -126,7 +126,7 @@ , such as and , this value is used to suspend the thread indefinitely. However, in most cases, we recommend that you use other classes such as , , , or instead to sychronize threads or manage resources. + For threading methods that accept a `timeout` parameter of type , such as and , this value is used to suspend the thread indefinitely. However, in most cases, we recommend that you use other classes such as , , , or instead to sychronize threads or manage resources. The value of this field is -00:00:00.0010000, or -1 millisecond. diff --git a/xml/System.Threading/Timer.xml b/xml/System.Threading/Timer.xml index 2a24ba8cc5491..05ef91da29ee7 100644 --- a/xml/System.Threading/Timer.xml +++ b/xml/System.Threading/Timer.xml @@ -59,10 +59,10 @@ Sub TimerCallback(state As Object) > [!TIP] > The .NET Framework Class Library includes four classes named `Timer`, each of which offers different functionality: > -> - , which fires an event and executes the code in one or more event sinks at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. -> - , which executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. -> - , a Windows Forms component that fires an event and executes the code in one or more event sinks at regular intervals. The component has no user interface and is designed for use in a single-threaded environment; it executes on the UI thread. -> - , an ASP.NET component that performs asynchronous or synchronous web page postbacks at a regular interval. +> - , which fires an event and executes the code in one or more event sinks at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. +> - , which executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. +> - , a Windows Forms component that fires an event and executes the code in one or more event sinks at regular intervals. The component has no user interface and is designed for use in a single-threaded environment; it executes on the UI thread. +> - , an ASP.NET component that performs asynchronous or synchronous web page postbacks at a regular interval. When you create a timer, you can specify an amount of time to wait before the first execution of the method (due time), and an amount of time to wait between subsequent executions (period). The class has the same resolution as the system clock. This means that if the period is less than the resolution of the system clock, the delegate will execute at intervals defined by the resolution of the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems. You can change the due time and period, or disable the timer, by using the method. @@ -74,7 +74,7 @@ Sub TimerCallback(state As Object) The callback method executed by the timer should be reentrant, because it is called on threads. The callback can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the callback, or if all thread pool threads are in use and the callback is queued multiple times. > [!NOTE] -> is a simple, lightweight timer that uses callback methods and is served by thread pool threads. It is not recommended for use with Windows Forms, because its callbacks do not occur on the user interface thread. is a better choice for use with Windows Forms. For server-based timer functionality, you might consider using , which raises events and has additional features. +> is a simple, lightweight timer that uses callback methods and is served by thread pool threads. It is not recommended for use with Windows Forms, because its callbacks do not occur on the user interface thread. is a better choice for use with Windows Forms. For server-based timer functionality, you might consider using , which raises events and has additional features. @@ -181,9 +181,9 @@ Sub TimerCallback(state As Object) ## Remarks The delegate specified by the `callback` parameter is invoked once after `dueTime` elapses, and thereafter each time the `period` time interval elapses. - If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. @@ -238,9 +238,9 @@ Sub TimerCallback(state As Object) ## Remarks The delegate specified by the `callback` parameter is invoked once after `dueTime` elapses, and thereafter each time the `period` time interval elapses. - If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. @@ -349,9 +349,9 @@ Sub TimerCallback(state As Object) ## Remarks The delegate specified by the `callback` parameter is invoked once after `dueTime` elapses, and thereafter each time the `period` time interval elapses. - If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. + If `dueTime` is zero (0), `callback` is invoked immediately. If `dueTime` is , `callback` is not invoked; the timer is disabled, but can be re-enabled by calling the method. - Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. + Because the class has the same resolution as the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems, the `callback` delegate executes at intervals defined by the resolution of the system clock if `period` is less than the resolution of the system clock. If `period` is zero (0) or and `dueTime` is not , `callback` is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled using the method. The method specified for `callback` should be reentrant, because it is called on threads. The method can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the method, or if all thread pool threads are in use and the method is queued multiple times. @@ -399,9 +399,9 @@ Sub TimerCallback(state As Object) ## Remarks The callback method is invoked once after `dueTime` elapses, and thereafter each time the time interval specified by `period` elapses. - If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. The method can be called from the delegate. @@ -457,9 +457,9 @@ Sub TimerCallback(state As Object) ## Remarks The callback method is invoked once after `dueTime` elapses, and thereafter each time the time interval specified by `period` elapses. - If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. The method can be called from the delegate. @@ -572,9 +572,9 @@ Sub TimerCallback(state As Object) ## Remarks The callback method is invoked once after `dueTime` elapses, and thereafter each time the time interval specified by `period` elapses. - If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. + If `dueTime` is zero (0), the callback method is invoked immediately. If `dueTime` is , the callback method is never invoked; the timer is disabled, but can be re-enabled by calling and specifying a positive value for `dueTime`. - If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. + If `period` is zero (0) or , and `dueTime` is not , the callback method is invoked once; the periodic behavior of the timer is disabled, but can be re-enabled by calling and specifying a positive value for `period`. The method can be called from the delegate. diff --git a/xml/System.Threading/TimerCallback.xml b/xml/System.Threading/TimerCallback.xml index 55108a4ddcc2f..3cee61c2607e0 100644 --- a/xml/System.Threading/TimerCallback.xml +++ b/xml/System.Threading/TimerCallback.xml @@ -37,12 +37,12 @@ . This method does not execute in the thread that created the timer; it executes in a separate thread pool thread that is provided by the system. The `TimerCallback` delegate invokes the method once after the start time elapses, and continues to invoke it once per timer interval until the method is called, or until the method is called with the interval value . + Use a `TimerCallback` delegate to specify the method that is called by a . This method does not execute in the thread that created the timer; it executes in a separate thread pool thread that is provided by the system. The `TimerCallback` delegate invokes the method once after the start time elapses, and continues to invoke it once per timer interval until the method is called, or until the method is called with the interval value . > [!NOTE] > Callbacks can occur after the method overload has been called, because the timer queues callbacks for execution by thread pool threads. You can use the method overload to wait until all callbacks have completed. - The timer delegate is specified when the timer is constructed, and cannot be changed. The start time for a `Timer` is passed in the `dueTime` parameter of the `Timer` constructors, and the period is passed in the `period` parameter. For an example that demonstrates creating and using a `TimerCallback` delegate, see . + The timer delegate is specified when the timer is constructed, and cannot be changed. The start time for a `Timer` is passed in the `dueTime` parameter of the `Timer` constructors, and the period is passed in the `period` parameter. For an example that demonstrates creating and using a `TimerCallback` delegate, see . diff --git a/xml/System.Threading/Volatile.xml b/xml/System.Threading/Volatile.xml index 4aea79faa531b..91ebc5299f661 100644 --- a/xml/System.Threading/Volatile.xml +++ b/xml/System.Threading/Volatile.xml @@ -34,14 +34,14 @@ Volatile memory operations are for special cases of synchronization, where normal locking is not an acceptable alternative. Under normal circumstances, the C# `lock` statement, the Visual Basic `SyncLock` statement, and the class provide the easiest and least error-prone way of synchronizing access to data, and the class provides a simple way to write lazy initialization code without directly using double-checked locking. - The and methods enable functionality that is not supported in languages. For example: + The and methods enable functionality that is not supported in languages. For example: - Some languages, such as Visual Basic, do not recognize the concept of volatile memory operations. The class provides that functionality in such languages. > [!NOTE] - > Calling one of these methods affects only a single memory access. To provide effective synchronization for a field, all access to the field must use and . + > Calling one of these methods affects only a single memory access. To provide effective synchronization for a field, all access to the field must use and . -- In C#, using the `volatile` modifier on a field guarantees that every access to that field uses the and methods, but the `volatile` modifier cannot be applied to array elements. The and methods can be used on array elements. +- In C#, using the `volatile` modifier on a field guarantees that every access to that field uses the and methods, but the `volatile` modifier cannot be applied to array elements. The and methods can be used on array elements. ]]> diff --git a/xml/System.Threading/WaitCallback.xml b/xml/System.Threading/WaitCallback.xml index 9d128d13b9ec5..9de1084d632a4 100644 --- a/xml/System.Threading/WaitCallback.xml +++ b/xml/System.Threading/WaitCallback.xml @@ -39,7 +39,7 @@ ## Remarks represents a callback method that you want to execute on a thread. Create the delegate by passing your callback method to the constructor. Your method must have the signature shown here. - Queue your task for execution by passing the delegate to . Your callback method executes when a thread pool thread becomes available. + Queue your task for execution by passing the delegate to . Your callback method executes when a thread pool thread becomes available. > [!NOTE] > Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. @@ -57,7 +57,7 @@ **Example 1** - This example shows how to use the delegate to queue a task for execution by the thread pool. The code example uses the method overload to queue a task, which is represented by a that wraps the `ThreadProc` method, to execute when a thread becomes available. No task information is supplied with this overload. Therefore, the information that is available to the `ThreadProc` method is limited to the object the method belongs to. + This example shows how to use the delegate to queue a task for execution by the thread pool. The code example uses the method overload to queue a task, which is represented by a that wraps the `ThreadProc` method, to execute when a thread becomes available. No task information is supplied with this overload. Therefore, the information that is available to the `ThreadProc` method is limited to the object the method belongs to. [!code-cpp[System.Threading.ThreadPool QueueUserWorkItem0#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/CPP/source.cpp#1)] [!code-csharp[System.Threading.ThreadPool QueueUserWorkItem0#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.ThreadPool QueueUserWorkItem0/CS/source.cs#1)] diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index f6717f3549e44..f4a31cf55bcf3 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -140,7 +140,7 @@ method for the class and its derived classes. It provides a standard implementation that calls the `Dispose(Boolean)` overload with a `true` argument and then calls the method. Call this method to release all resources held by an instance of `WaitHandle` or a derived class. + This method is the public implementation of the method for the class and its derived classes. It provides a standard implementation that calls the `Dispose(Boolean)` overload with a `true` argument and then calls the method. Call this method to release all resources held by an instance of `WaitHandle` or a derived class. Once this method is called, references to the current instance cause undefined behavior. @@ -430,7 +430,7 @@ ## Examples The following code example uses the method overload to allow the main thread to signal a blocked thread and then wait until the thread finishes a task. - The example starts five threads, allows them to block on an created with the flag, and then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. + The example starts five threads, allows them to block on an created with the flag, and then releases one thread each time the user presses the ENTER key. The example then queues another five threads and releases them all using an created with the flag. [!code-cpp[System.Threading.WaitHandle.SignalAndWait#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CPP/source.cpp#1)] [!code-csharp[System.Threading.WaitHandle.SignalAndWait#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Threading.WaitHandle.SignalAndWait/CS/source.cs#1)] @@ -565,7 +565,7 @@ ## Remarks This operation is not guaranteed to be atomic. After the current thread signals `toSignal` but before it waits on `toWaitOn`, a thread that is running on another processor might signal `toWaitOn` or wait on it. - The maximum value for `timeout` is . + The maximum value for `timeout` is . If `timeout` is zero, the method does not block. It tests the state of the `toWaitOn` and returns immediately. @@ -641,7 +641,7 @@ > [!NOTE] > The method is not supported on threads that have . - Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. + Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. @@ -806,7 +806,7 @@ > [!NOTE] > The method is not supported on threads that have . - The maximum value for `timeout` is . + The maximum value for `timeout` is . Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. @@ -985,7 +985,7 @@ > [!NOTE] > The method is not supported on threads that have . - The maximum value for `timeout` is . + The maximum value for `timeout` is . ## Notes on Exiting the Context The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that is not derived from , like , you can be in a nondefault context if a is on your stack in the current application domain. @@ -1082,7 +1082,7 @@ This method returns when any handle is signaled. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. On some implementations, if more that 64 handles are passed, a is thrown. - Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. + Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. @@ -1225,7 +1225,7 @@ This method returns when the wait terminates, either when any of the handles are signaled or when a time-out occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. On some implementations, if more that 64 handles are passed, a is thrown. - The maximum value for `timeout` is . + The maximum value for `timeout` is . Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. @@ -1392,7 +1392,7 @@ This method returns when the wait terminates, either when any of the handles are signaled or when a time-out occurs. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. On some implementations, if more that 64 handles are passed, a is thrown. - The maximum value for `timeout` is . + The maximum value for `timeout` is . ## Notes on Exiting the Context The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that does not derive from , like , you can be in a nondefault context if a is on your stack in the current application domain. @@ -1470,7 +1470,7 @@ The caller of this method blocks indefinitely until the current instance receives a signal. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. - Calling this method overload is equivalent to calling the method overload and specifying -1 or for the first parameter and `false` for the second parameter. + Calling this method overload is equivalent to calling the method overload and specifying -1 or for the first parameter and `false` for the second parameter. Override this method to customize the behavior of derived classes. @@ -1596,7 +1596,7 @@ Override this method to customize the behavior of derived classes. - The maximum value for `timeout` is . + The maximum value for `timeout` is . Calling this method overload is the same as calling the overload and specifying `false` for `exitContext`. @@ -1726,7 +1726,7 @@ Override this method to customize the behavior of derived classes. - The maximum value for `timeout` is . + The maximum value for `timeout` is . ## Notes on Exiting the Context The `exitContext` parameter has no effect unless the method is called from inside a nondefault managed context. This can happen if your thread is inside a call to an instance of a class derived from . Even if you are currently executing a method on a class that does not derive from , like , you can be in a nondefault context if a is on your stack in the current application domain. diff --git a/xml/System.Threading/WaitHandleCannotBeOpenedException.xml b/xml/System.Threading/WaitHandleCannotBeOpenedException.xml index 6dd9f25e35ba4..bed5f59c625c9 100644 --- a/xml/System.Threading/WaitHandleCannotBeOpenedException.xml +++ b/xml/System.Threading/WaitHandleCannotBeOpenedException.xml @@ -33,7 +33,7 @@ , , and classes can represent named system synchronization objects. When you use the method, the method, or the method to open a named system object that does not exist, a exception is thrown. + Instances of the , , and classes can represent named system synchronization objects. When you use the method, the method, or the method to open a named system object that does not exist, a exception is thrown. ]]> diff --git a/xml/System.Threading/WaitHandleExtensions.xml b/xml/System.Threading/WaitHandleExtensions.xml index ee4dca7bca49d..4faa9b5850c86 100644 --- a/xml/System.Threading/WaitHandleExtensions.xml +++ b/xml/System.Threading/WaitHandleExtensions.xml @@ -76,7 +76,7 @@ is an extension method that is equivalent to retrieving the value of the property. + is an extension method that is equivalent to retrieving the value of the property. ]]> @@ -126,7 +126,7 @@ is an extension method that is equivalent to assigning a value to the property. + is an extension method that is equivalent to assigning a value to the property. ]]> diff --git a/xml/System.Threading/WaitOrTimerCallback.xml b/xml/System.Threading/WaitOrTimerCallback.xml index 047ea41c70c16..8033246cbe63b 100644 --- a/xml/System.Threading/WaitOrTimerCallback.xml +++ b/xml/System.Threading/WaitOrTimerCallback.xml @@ -42,7 +42,7 @@ ## Remarks represents a callback method that you want to execute when a registered wait handle times out or is signaled. Create the delegate by passing your callback method to the constructor. Your method must have the signature shown here. - Create the registered wait handle by passing the delegate and a to . Your callback method executes each time the times out or is signaled. + Create the registered wait handle by passing the delegate and a to . Your callback method executes each time the times out or is signaled. > [!NOTE] diff --git a/xml/System.Timers/ElapsedEventArgs.xml b/xml/System.Timers/ElapsedEventArgs.xml index 526e9cc5830a0..8be4002c1a314 100644 --- a/xml/System.Timers/ElapsedEventArgs.xml +++ b/xml/System.Timers/ElapsedEventArgs.xml @@ -25,7 +25,7 @@ object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. [!code-cpp[System.Timers.Timer#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.timers.timer/cpp/timer1.cpp#1)] [!code-csharp[System.Timers.Timer#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/timer1.cs#1)] @@ -63,12 +63,12 @@ event is raised on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. This race condition cannot be prevented simply by comparing the property with the time when the method is called, because the event-handling method might already be executing when the method is called, or might begin executing between the moment when the method is called and the moment when the stop time is saved. If it is critical to prevent the thread that calls the method from proceeding while the event-handling method is still executing, use a more robust synchronization mechanism such as the class or the method. Code that uses the method can be found in the example for the method. + The event is raised on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. This race condition cannot be prevented simply by comparing the property with the time when the method is called, because the event-handling method might already be executing when the method is called, or might begin executing between the moment when the method is called and the moment when the stop time is saved. If it is critical to prevent the thread that calls the method from proceeding while the event-handling method is still executing, use a more robust synchronization mechanism such as the class or the method. Code that uses the method can be found in the example for the method. ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. [!code-cpp[System.Timers.Timer#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.timers.timer/cpp/timer1.cpp#1)] [!code-csharp[System.Timers.Timer#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/timer1.cs#1)] diff --git a/xml/System.Timers/ElapsedEventHandler.xml b/xml/System.Timers/ElapsedEventHandler.xml index 78f730daaf3fb..aef660bdebe3c 100644 --- a/xml/System.Timers/ElapsedEventHandler.xml +++ b/xml/System.Timers/ElapsedEventHandler.xml @@ -33,12 +33,12 @@ delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Events](http://msdn.microsoft.com/library/b6f65241-e0ad-4590-a99f-200ce741bb1f). + When you create an delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Events](http://msdn.microsoft.com/library/b6f65241-e0ad-4590-a99f-200ce741bb1f). ## Examples - The following code example sets up an event handler for the event, creates a timer, and starts the timer. The event handler has the same signature as the delegate. The event handler displays the property each time it is raised. + The following code example sets up an event handler for the event, creates a timer, and starts the timer. The event handler has the same signature as the delegate. The event handler displays the property each time it is raised. [!code-cpp[Classic Timer Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_Classic/classic Timer Example/CPP/source.cpp#1)] [!code-csharp[Classic Timer Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic Timer Example/CS/source.cs#1)] diff --git a/xml/System.Timers/Timer.xml b/xml/System.Timers/Timer.xml index dfe191619ce0d..aa137b8d59da9 100644 --- a/xml/System.Timers/Timer.xml +++ b/xml/System.Timers/Timer.xml @@ -44,18 +44,18 @@ The component is a server-based timer that raises an event in your application after the number of milliseconds in the property has elapsed. You can configure the object to raise the event just once or repeatedly using the property. Typically, a object is declared at the class level so that it stays in scope as long as it is needed. You can then handle its event to provide regular processing. For example, suppose you have a critical server that must be kept running 24 hours a day, 7 days a week. You could create a service that uses a object to periodically check the server and ensure that the system is up and running. If the system is not responding, the service could attempt to restart the server or notify an administrator. > [!IMPORTANT] -> The class is available in the .NET Framework only. It is not included in the .NET Standard and is not available in other implementations, such as .NET Core or the Universal Windows Platform. On these implementations, as well as for portability across all .NET implementations, you should use the class instead. +> The class is available in the .NET Framework only. It is not included in the .NET Standard and is not available in other implementations, such as .NET Core or the Universal Windows Platform. On these implementations, as well as for portability across all .NET implementations, you should use the class instead. This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - The server-based class is designed for use with worker threads in a multithreaded environment. Server timers can move among threads to handle the raised event, resulting in more accuracy than Windows timers in raising the event on time. + The server-based class is designed for use with worker threads in a multithreaded environment. Server timers can move among threads to handle the raised event, resulting in more accuracy than Windows timers in raising the event on time. - The component raises the event, based on the value (in milliseconds) of the property. You can handle this event to perform the processing you need. For example, suppose that you have an online sales application that continuously posts sales orders to a database. The service that compiles the instructions for shipping operates on a batch of orders rather than processing each order individually. You could use a to start the batch processing every 30 minutes. + The component raises the event, based on the value (in milliseconds) of the property. You can handle this event to perform the processing you need. For example, suppose that you have an online sales application that continuously posts sales orders to a database. The service that compiles the instructions for shipping operates on a batch of orders rather than processing each order individually. You could use a to start the batch processing every 30 minutes. > [!IMPORTANT] > The System.Timers.Timer class has the same resolution as the system clock. This means that the event will fire at an interval defined by the resolution of the system clock if the property is less than the resolution of the system clock. For more information, see the property. - When is set to `false`, a object raises the event only once, after the first has elapsed. To keep raising the event regularly at the interval defined by the , set to `true`, which is the default value. + When is set to `false`, a object raises the event only once, after the first has elapsed. To keep raising the event regularly at the interval defined by the , set to `true`, which is the default value. The component catches and suppresses all exceptions thrown by event handlers for the event. This behavior is subject to change in future releases of the .NET Framework. Note, however, that this is not true of event handlers that execute asynchronously and include the `await` operator (in C#) or the `Await` operator (in Visual Basic). Exceptions thrown in these event handlers are propagated back to the calling thread, as the following example illustrates. For more information on exceptions thrown in asynchronous methods, see [Exception Handling](~/docs/standard/parallel-programming/exception-handling-task-parallel-library.md). @@ -69,22 +69,22 @@ Even if is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. - If you use the class with a user interface element, such as a form or control, without placing the timer on that user interface element, assign the form or control that contains the to the property, so that the event is marshaled to the user interface thread. + If you use the class with a user interface element, such as a form or control, without placing the timer on that user interface element, assign the form or control that contains the to the property, so that the event is marshaled to the user interface thread. For a list of default property values for an instance of , see the constructor. > [!TIP] > Be aware that the .NET Framework Class Library includes four classes named `Timer`, each of which offers different functionality: > -> - (this topic): fires an event at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. -> - : executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. -> - : a Windows Forms component that fires an event at regular intervals. The component has no user interface and is designed for use in a single-threaded environment. -> - : an ASP.NET component that performs asynchronous or synchronous web page postbacks at a regular interval. +> - (this topic): fires an event at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. +> - : executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. +> - : a Windows Forms component that fires an event at regular intervals. The component has no user interface and is designed for use in a single-threaded environment. +> - : an ASP.NET component that performs asynchronous or synchronous web page postbacks at a regular interval. ## Examples - The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. [!code-csharp[System.Timers.Timer#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/timer2a.cs#2)] [!code-vb[System.Timers.Timer#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.timers.timer/vb/timer2a.vb#2)] @@ -131,7 +131,7 @@ ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. [!code-cpp[System.Timers.Timer#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.timers.timer/cpp/timer1.cpp#1)] [!code-csharp[System.Timers.Timer#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/timer1.cs#1)] @@ -174,7 +174,7 @@ ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. [!code-csharp[System.Timers.Timer#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/AsyncHandlerEx1.cs#3)] [!code-vb[System.Timers.Timer#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.timers.timer/vb/AsyncHandlerEx1.vb#3)] @@ -391,7 +391,7 @@ ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. [!code-cpp[System.Timers.Timer#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.timers.timer/cpp/timer1.cpp#1)] [!code-csharp[System.Timers.Timer#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/timer1.cs#1)] @@ -456,7 +456,7 @@ ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. [!code-cpp[System.Timers.Timer#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.timers.timer/cpp/timer1.cpp#1)] [!code-csharp[System.Timers.Timer#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/timer1.cs#1)] @@ -566,7 +566,7 @@ ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. [!code-cpp[System.Timers.Timer#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.timers.timer/cpp/timer1.cpp#1)] [!code-csharp[System.Timers.Timer#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/timer1.cs#1)] @@ -693,16 +693,16 @@ ## Examples - The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. When the user presses the Enter key, the application calls the method before terminating the application. + The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. When the user presses the Enter key, the application calls the method before terminating the application. [!code-csharp[System.Timers.Timer#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.timers.timer/cs/timer2a.cs#2)] [!code-vb[System.Timers.Timer#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.timers.timer/vb/timer2a.vb#2)] The following code example shows one way to prevent the thread that calls the method from continuing until a currently executing event ends, and also to prevent two events from executing the event handler at the same time (often referred to as reentrancy). - The example executes 100 test runs. Each time the test is run, the timer is started with an interval of 150 milliseconds. The event handler uses the method to simulate a task that randomly varies in length from 50 to 200 milliseconds. The test method also starts a control thread that waits for a second and then stops the timer. If an event is being handled when the control thread stops the timer, the control thread must wait until the event is finished before proceeding. + The example executes 100 test runs. Each time the test is run, the timer is started with an interval of 150 milliseconds. The event handler uses the method to simulate a task that randomly varies in length from 50 to 200 milliseconds. The test method also starts a control thread that waits for a second and then stops the timer. If an event is being handled when the control thread stops the timer, the control thread must wait until the event is finished before proceeding. - The method overload is used to avoid reentrancy and to prevent the control thread from continuing until an executing event ends. The event handler uses the method to set a control variable to 1, but only if the value is currently zero. This is an atomic operation. If the return value is zero, the control variable has been set to 1 and the event handler proceeds. If the return value is non-zero, the event is simply discarded to avoid reentrancy. (If it were necessary to execute every event, the class would be a better way to synchronize the events.) When the event handler ends, it sets the control variable back to zero. The example records the total number of events that executed, that were discarded because of reentrancy, and that occurred after the method was called. + The method overload is used to avoid reentrancy and to prevent the control thread from continuing until an executing event ends. The event handler uses the method to set a control variable to 1, but only if the value is currently zero. This is an atomic operation. If the return value is zero, the control variable has been set to 1 and the event handler proceeds. If the return value is non-zero, the event is simply discarded to avoid reentrancy. (If it were necessary to execute every event, the class would be a better way to synchronize the events.) When the event handler ends, it sets the control variable back to zero. The example records the total number of events that executed, that were discarded because of reentrancy, and that occurred after the method was called. The control thread uses the method to set the control variable to -1 (minus one), but only if the value is currently zero. If the atomic operation returns non-zero, an event is currently executing. The control thread waits and tries again. The example records the number of times the control thread had to wait for an event to finish. diff --git a/xml/System.Transactions/IPromotableSinglePhaseNotification.xml b/xml/System.Transactions/IPromotableSinglePhaseNotification.xml index 8deeb3bb78aeb..be206572a5796 100644 --- a/xml/System.Transactions/IPromotableSinglePhaseNotification.xml +++ b/xml/System.Transactions/IPromotableSinglePhaseNotification.xml @@ -30,7 +30,7 @@ A resource manager that implements this interface delegates control of the commit of it's internal non-distributed transaction to an enlistment on a transaction through the method on the class. - If the method is called, your implementation of this interface must produce a distributed transaction in the form of a propagation token, and return it to . + If the method is called, your implementation of this interface must produce a distributed transaction in the form of a propagation token, and return it to . After you enlist an object that implements this interface as a participant of a transaction using the method, the transaction manager then notifies the participant when the transaction is promoted, committed, or rolled back by invoking the method, the method, or the method of the object. diff --git a/xml/System.Transactions/Transaction.xml b/xml/System.Transactions/Transaction.xml index 130eaa9b42b5e..2026fe5064deb 100644 --- a/xml/System.Transactions/Transaction.xml +++ b/xml/System.Transactions/Transaction.xml @@ -716,7 +716,7 @@ if and are equal; otherwise, . - .]]> + .]]> @@ -752,7 +752,7 @@ if and are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Transactions/TransactionOptions.xml b/xml/System.Transactions/TransactionOptions.xml index cffe88753c875..c3c16d69dd285 100644 --- a/xml/System.Transactions/TransactionOptions.xml +++ b/xml/System.Transactions/TransactionOptions.xml @@ -150,7 +150,7 @@ if and are equal; otherwise, . - .]]> + .]]> @@ -186,7 +186,7 @@ if and are not equal; otherwise, . - .]]> + .]]> diff --git a/xml/System.Web.Caching/AggregateCacheDependency.xml b/xml/System.Web.Caching/AggregateCacheDependency.xml index ec57429f1578a..7fa156f273fd1 100644 --- a/xml/System.Web.Caching/AggregateCacheDependency.xml +++ b/xml/System.Web.Caching/AggregateCacheDependency.xml @@ -18,7 +18,7 @@ ## Remarks The class monitors a collection of dependency objects so that when any of them change, the cached item is automatically removed. The objects in the array can be objects, objects, custom objects derived from , or any combination of these. - The class differs from the class in that it allows you to associate multiple dependencies of different types with a single cached item. For example, if you create a page that imports data from a SQL Server database table and an XML file, you can create a object to represent a dependency on the database table and a to represent the dependency on the XML file. Rather than making an method call for each dependency, you can create an instance of the class with each dependency added to it. You can then use a single call to make the page dependent on the instance. + The class differs from the class in that it allows you to associate multiple dependencies of different types with a single cached item. For example, if you create a page that imports data from a SQL Server database table and an XML file, you can create a object to represent a dependency on the database table and a to represent the dependency on the XML file. Rather than making an method call for each dependency, you can create an instance of the class with each dependency added to it. You can then use a single call to make the page dependent on the instance. diff --git a/xml/System.Web.Caching/Cache.xml b/xml/System.Web.Caching/Cache.xml index c740b09b904da..c7f17051c4503 100644 --- a/xml/System.Web.Caching/Cache.xml +++ b/xml/System.Web.Caching/Cache.xml @@ -28,7 +28,7 @@ ## Examples - The following example is a page that shows users the value assigned to an item in the cache, and then notifies them when the item is removed from the cache. It creates a `RemovedCallback` method, which has the signature of the `CacheItemRemovedCallback` delegate, to notify users when the cache item is removed, and it uses the enumeration to tell them why it was removed. In addition, it uses the property to add objects to the cache and retrieve the value of those objects. In the `AddItemToCache` method, it uses the method to add an item to the cache. To use the `CacheItemRemovedCallback` delegate, you must add an item to the cache with this method or the method, so that that ASP.NET can automatically make the proper method calls when the item is removed. The custom `RemoveItemFromCache` method uses the method to explicitly delete the item from the cache, causing the `RemovedCallback` method to be invoked. + The following example is a page that shows users the value assigned to an item in the cache, and then notifies them when the item is removed from the cache. It creates a `RemovedCallback` method, which has the signature of the `CacheItemRemovedCallback` delegate, to notify users when the cache item is removed, and it uses the enumeration to tell them why it was removed. In addition, it uses the property to add objects to the cache and retrieve the value of those objects. In the `AddItemToCache` method, it uses the method to add an item to the cache. To use the `CacheItemRemovedCallback` delegate, you must add an item to the cache with this method or the method, so that that ASP.NET can automatically make the proper method calls when the item is removed. The custom `RemoveItemFromCache` method uses the method to explicitly delete the item from the cache, causing the `RemovedCallback` method to be invoked. > [!NOTE] > The instance of Cache that is accessed by the snippet below is a member of the object that this sample inherits. @@ -544,12 +544,12 @@ property is equivalent to calling the method. + You can use this property to retrieve the value of a specified cache item, or to add an item and a key for it to the cache. Adding a cache item using the property is equivalent to calling the method. ## Examples - The following example uses the `Item` property to retrieve the value of a cached object associated with the `Key1` key. It then uses the method to write the value and introductory text and the B HTML element to a Web Forms page. + The following example uses the `Item` property to retrieve the value of a cached object associated with the `Key1` key. It then uses the method to write the value and introductory text and the B HTML element to a Web Forms page. [!code-csharp[System.Web.Caching Examples#5](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Web.Caching Examples/CS/cachecs.aspx#5)] [!code-vb[System.Web.Caching Examples#5](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.Caching Examples/VB/cachevb.aspx#5)] @@ -613,7 +613,7 @@ field, which has a constant value of zero. The cached item expires in accordance with the `absoluteExpiration` parameter associated with the `Insert` or `Add` method call. + When used, this field sets the `slidingExpiration` parameter to the field, which has a constant value of zero. The cached item expires in accordance with the `absoluteExpiration` parameter associated with the `Insert` or `Add` method call. diff --git a/xml/System.Web.Caching/CacheDependency.xml b/xml/System.Web.Caching/CacheDependency.xml index e31025111a445..dd06c8c8a0e9d 100644 --- a/xml/System.Web.Caching/CacheDependency.xml +++ b/xml/System.Web.Caching/CacheDependency.xml @@ -22,14 +22,14 @@ ## Remarks If you add an item to the cache that is dependent on another object, such as a file or array of files, the dependent item is automatically removed from the cache when the object changes. For example, suppose you create a object based on data in an XML file. You can add the to the cache with a object that makes the dependent on the XML file. If the XML file changes, the is removed from the cache. - You can add items with dependencies to your application's cache with the and methods. You cannot use the property to add items to the cache with dependencies. + You can add items with dependencies to your application's cache with the and methods. You cannot use the property to add items to the cache with dependencies. - To set up a dependency, you create an instance of the class, specifying the files, keys, or directories on which the item is dependent, and then pass the dependency to the or method. The instance can represent a single file or directory, an array of files or directories, or an array of files or directories along with an array of cache keys (these represent other items stored in the object). + To set up a dependency, you create an instance of the class, specifying the files, keys, or directories on which the item is dependent, and then pass the dependency to the or method. The instance can represent a single file or directory, an array of files or directories, or an array of files or directories along with an array of cache keys (these represent other items stored in the object). ## Examples - The following code example demonstrates using the property to determine whether a changed since the previous request for an item in the . The `dt` value passed in the `start` parameter is set to . + The following code example demonstrates using the property to determine whether a changed since the previous request for an item in the . The `dt` value passed in the `start` parameter is set to . [!code-csharp[System.Web.Caching.CacheDependency_HasChanged#1](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Web.Caching.CacheDependency_HasChanged/CS/t.cs.aspx#1)] [!code-vb[System.Web.Caching.CacheDependency_HasChanged#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.Caching.CacheDependency_HasChanged/VB/t.vb.aspx#1)] @@ -93,7 +93,7 @@ ## Examples - The following code example creates an instance of the class with a dependency on an XML file. The method then adds an item to the that is dependent upon that file. + The following code example creates an instance of the class with a dependency on an XML file. The method then adds an item to the that is dependent upon that file. [!code-csharp[Classic CacheDependency.CacheDependency Example#1](~/samples/snippets/csharp/VS_Snippets_WebNet/Classic CacheDependency.CacheDependency Example/CS/source.cs#1)] [!code-vb[Classic CacheDependency.CacheDependency Example#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/Classic CacheDependency.CacheDependency Example/VB/source.vb#1)] @@ -138,7 +138,7 @@ ## Examples - The following code example demonstrates how to use the method to add an item to the with dependencies on an array of files. You can also make the item dependent on an array of directories. + The following code example demonstrates how to use the method to add an item to the with dependencies on an array of files. You can also make the item dependent on an array of directories. [!code-csharp[Multiple file based dependency#1](~/samples/snippets/csharp/VS_Snippets_WebNet/Multiple file based dependency/CS/DependencyMultiFilecs.aspx#1)] [!code-vb[Multiple file based dependency#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/Multiple file based dependency/VB/DependencyMultiFilevb.aspx#1)] @@ -178,7 +178,7 @@ ## Examples - The following code example uses this constructor to instantiate a object, then inserts an item into the with that dependency. The `dt` value passed in the `start` parameter is set to . + The following code example uses this constructor to instantiate a object, then inserts an item into the with that dependency. The `dt` value passed in the `start` parameter is set to . [!code-csharp[System.Web.Caching.CacheDependency_HasChanged#1](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Web.Caching.CacheDependency_HasChanged/CS/t.cs.aspx#1)] [!code-vb[System.Web.Caching.CacheDependency_HasChanged#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.Caching.CacheDependency_HasChanged/VB/t.vb.aspx#1)] @@ -218,7 +218,7 @@ ## Examples - The following code example creates a object that passes two XML files and a value when the object is included as a parameter argument in an method call. + The following code example creates a object that passes two XML files and a value when the object is included as a parameter argument in an method call. [!code-csharp[CacheDependency Constructor4#1](~/samples/snippets/csharp/VS_Snippets_WebNet/CacheDependency Constructor4/CS/depmultifilestimecs.aspx#1)] [!code-vb[CacheDependency Constructor4#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/CacheDependency Constructor4/VB/depmultifilestimevb.aspx#1)] @@ -297,7 +297,7 @@ ## Examples - The following code example creates a `CreateDependency` method. When this method is called, it creates a object and the property is used to add an item to the cache with a `key` parameter of `key1` and a value of `Value 1`. An array of strings, `dependencyKey`, is then created with the value of `key1` as well. This constructor then instantiates a object that passes `dependencyKey` and the object as parameter arguments. The method is called next, using the object as a parameter. This makes the object added to the cache using the method dependent on the `key1` key. + The following code example creates a `CreateDependency` method. When this method is called, it creates a object and the property is used to add an item to the cache with a `key` parameter of `key1` and a value of `Value 1`. An array of strings, `dependencyKey`, is then created with the value of `key1` as well. This constructor then instantiates a object that passes `dependencyKey` and the object as parameter arguments. The method is called next, using the object as a parameter. This makes the object added to the cache using the method dependent on the `key1` key. [!code-csharp[CacheDependency Constructor6#1](~/samples/snippets/csharp/VS_Snippets_WebNet/CacheDependency Constructor6/CS/depkeytimecs.aspx#1)] [!code-vb[CacheDependency Constructor6#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/CacheDependency Constructor6/VB/depkeytimevb.aspx#1)] @@ -336,7 +336,7 @@ ## Examples - The following code example creates a `CreateDependency` method. When this method is called, it uses the property to add an item to the cache with a `key` parameter of `key1` and a value of `Value 1`. An array of strings, `dependencyKey`, is then created with the value of `key1` as well. The constructor is used to create a object, `dep1`, which passes `dependencyKey` as a parameter argument. A second object, `dep2`, is created using this constructor, with `dep1` passed as the third parameter argument. This second dependency is dependent on the first. The method is called next, using the second object as a parameter. If the first dependency changes in any way, the cached item will be invalidated. + The following code example creates a `CreateDependency` method. When this method is called, it uses the property to add an item to the cache with a `key` parameter of `key1` and a value of `Value 1`. An array of strings, `dependencyKey`, is then created with the value of `key1` as well. The constructor is used to create a object, `dep1`, which passes `dependencyKey` as a parameter argument. A second object, `dep2`, is created using this constructor, with `dep1` passed as the third parameter argument. This second dependency is dependent on the first. The method is called next, using the second object as a parameter. If the first dependency changes in any way, the cached item will be invalidated. [!code-csharp[CacheDependency Constructor7#1](~/samples/snippets/csharp/VS_Snippets_WebNet/CacheDependency Constructor7/CS/dependencycs.aspx#1)] [!code-vb[CacheDependency Constructor7#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/CacheDependency Constructor7/VB/dependencyvb.aspx#1)] @@ -380,7 +380,7 @@ ## Examples - The following code example shows a `CreateDependency` method. When this method is called, it creates a object and the property is used to add an item to the cache with a key parameter of `key1` and a value of `Value 1`. An array of strings, `dependencyKey`, is then created with the value at its first (and only) index set to the value of `key1` as well. The constructor is then used to create a object, `dep1`, which passes `dependencyKey` as a parameter argument. A second object, `dep2`, is then created using this constructor, with `dep1` and the object passed as parameter arguments. This second dependency is dependent on the first, and dependency monitoring will begin 10 seconds after the `CreateDependency` method is called. The method is called next, using the second object as a parameter. If the first dependency changes in any way, the cached item will be invalidated. + The following code example shows a `CreateDependency` method. When this method is called, it creates a object and the property is used to add an item to the cache with a key parameter of `key1` and a value of `Value 1`. An array of strings, `dependencyKey`, is then created with the value at its first (and only) index set to the value of `key1` as well. The constructor is then used to create a object, `dep1`, which passes `dependencyKey` as a parameter argument. A second object, `dep2`, is then created using this constructor, with `dep1` and the object passed as parameter arguments. This second dependency is dependent on the first, and dependency monitoring will begin 10 seconds after the `CreateDependency` method is called. The method is called next, using the second object as a parameter. If the first dependency changes in any way, the cached item will be invalidated. [!code-csharp[CacheDependency Constructor8#1](~/samples/snippets/csharp/VS_Snippets_WebNet/CacheDependency Constructor8/CS/dependencytimecs.aspx#1)] [!code-vb[CacheDependency Constructor8#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/CacheDependency Constructor8/VB/dependencytimevb.aspx#1)] @@ -546,7 +546,7 @@ ## Examples - The following code example demonstrates using the property to determine whether a changed since the previous request for an item in the . The `dt` value passed in the `start` parameter is set to . + The following code example demonstrates using the property to determine whether a changed since the previous request for an item in the . The `dt` value passed in the `start` parameter is set to . [!code-csharp[System.Web.Caching.CacheDependency_HasChanged#1](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Web.Caching.CacheDependency_HasChanged/CS/t.cs.aspx#1)] [!code-vb[System.Web.Caching.CacheDependency_HasChanged#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.Caching.CacheDependency_HasChanged/VB/t.vb.aspx#1)] diff --git a/xml/System.Web.Caching/CacheItemRemovedCallback.xml b/xml/System.Web.Caching/CacheItemRemovedCallback.xml index 040caf30d5fe0..e4c914b05391d 100644 --- a/xml/System.Web.Caching/CacheItemRemovedCallback.xml +++ b/xml/System.Web.Caching/CacheItemRemovedCallback.xml @@ -26,7 +26,7 @@ delegate, to notify users when the cache item is removed and uses the enumeration to tell them why it was removed. In addition, it uses the property to add objects to the cache and retrieve the value of those objects. In the `AddItemToCache` method, it uses the method to add an item to the cache. To use the delegate, you must add an item to the cache with this method or the method so that that ASP.NET can automatically make the proper method calls when the item is removed. The custom `RemoveItemFromCache` method uses the method to explicitly delete the item from the cache, causing the `RemovedCallback` method to be invoked. + The following code example demonstrates a page that shows users the value assigned to an item in the cache and then notifies them when the item is removed from the cache. It creates a `RemovedCallback` method, which uses the signature of the delegate, to notify users when the cache item is removed and uses the enumeration to tell them why it was removed. In addition, it uses the property to add objects to the cache and retrieve the value of those objects. In the `AddItemToCache` method, it uses the method to add an item to the cache. To use the delegate, you must add an item to the cache with this method or the method so that that ASP.NET can automatically make the proper method calls when the item is removed. The custom `RemoveItemFromCache` method uses the method to explicitly delete the item from the cache, causing the `RemovedCallback` method to be invoked. diff --git a/xml/System.Web.Caching/SqlCacheDependency.xml b/xml/System.Web.Caching/SqlCacheDependency.xml index 96ad2c0f0e051..98de05937d70f 100644 --- a/xml/System.Web.Caching/SqlCacheDependency.xml +++ b/xml/System.Web.Caching/SqlCacheDependency.xml @@ -18,7 +18,7 @@ ## Remarks On all supported versions of SQL Server (Microsoft SQL Server 7.0, Microsoft SQL Server 2000, and SQL Server 2005) the class monitors a specific SQL Server database table. When the table changes, items associated with the table are removed from the , and a new version of the item is added to the . - The class also supports integration with the class when using a [!INCLUDE[sqprsqlong](~/includes/sqprsqlong-md.md)] database. The query notification mechanism of [!INCLUDE[sqprsqlong](~/includes/sqprsqlong-md.md)] detects changes to data that invalidate the results of an SQL query and removes any cached items associated with the SQL query from the . + The class also supports integration with the class when using a [!INCLUDE[sqprsqlong](~/includes/sqprsqlong-md.md)] database. The query notification mechanism of [!INCLUDE[sqprsqlong](~/includes/sqprsqlong-md.md)] detects changes to data that invalidate the results of an SQL query and removes any cached items associated with the SQL query from the . You can use the class to add items to your application's that are dependent on either a SQL Server database table or on an SQL query when using [!INCLUDE[sqprsqlong](~/includes/sqprsqlong-md.md)]. You can also use this class with the directive to make an output-cached page or a user control dependent on a SQL Server database table. Finally, you can use the class with the page directive to make an output-cached page dependent on the results of an SQL query when using [!INCLUDE[sqprsqlong](~/includes/sqprsqlong-md.md)]. Query notification using [!INCLUDE[sqprsqlong](~/includes/sqprsqlong-md.md)] is not supported on the directive for user controls. @@ -141,7 +141,7 @@ ``` - Two exceptions are commonly thrown when this constructor is used: and . If a is thrown, you can call the method in exception-handling code, or use the command-line tool to set up the database for notifications. If a is thrown, you can call the method or use to set up the table for notifications. + Two exceptions are commonly thrown when this constructor is used: and . If a is thrown, you can call the method in exception-handling code, or use the command-line tool to set up the database for notifications. If a is thrown, you can call the method or use to set up the table for notifications. diff --git a/xml/System.Web.Caching/TableNotEnabledForNotificationException.xml b/xml/System.Web.Caching/TableNotEnabledForNotificationException.xml index b77a1f24e6fde..a2130e21b276d 100644 --- a/xml/System.Web.Caching/TableNotEnabledForNotificationException.xml +++ b/xml/System.Web.Caching/TableNotEnabledForNotificationException.xml @@ -16,7 +16,7 @@ object and add an item to the with a dependency on the object. If the SQL Server database table is not enabled for dependency notifications, the is thrown and handled by calling the method. + The following code example attempts to create a object and add an item to the with a dependency on the object. If the SQL Server database table is not enabled for dependency notifications, the is thrown and handled by calling the method. [!code-csharp[CachingSamples_SqlCacheDependency#2](~/samples/snippets/csharp/VS_Snippets_WebNet/CachingSamples_SqlCacheDependency/CS/sqlcachedepsamplecs.aspx#2)] [!code-vb[CachingSamples_SqlCacheDependency#2](~/samples/snippets/visualbasic/VS_Snippets_WebNet/CachingSamples_SqlCacheDependency/VB/sqlcachedepsamplevb.aspx#2)] diff --git a/xml/System.Web.ClientServices.Providers/ClientFormsAuthenticationCredentials.xml b/xml/System.Web.ClientServices.Providers/ClientFormsAuthenticationCredentials.xml index 2791d8ced079f..c4836432661be 100644 --- a/xml/System.Web.ClientServices.Providers/ClientFormsAuthenticationCredentials.xml +++ b/xml/System.Web.ClientServices.Providers/ClientFormsAuthenticationCredentials.xml @@ -21,7 +21,7 @@ ## Examples - The following example code demonstrates how to implement the method, which returns an instance of this class. In this example, the method is part of a login dialog box class. The method displays the dialog box, and then returns a instance initialized with the user-specified values. + The following example code demonstrates how to implement the method, which returns an instance of this class. In this example, the method is part of a login dialog box class. The method displays the dialog box, and then returns a instance initialized with the user-specified values. [!code-csharp[ClientApplicationServices#210](~/samples/snippets/csharp/VS_Snippets_Winforms/ClientApplicationServices/CS/Login.cs#210)] [!code-vb[ClientApplicationServices#210](~/samples/snippets/visualbasic/VS_Snippets_Winforms/ClientApplicationServices/VB/Login.vb#210)] @@ -58,7 +58,7 @@ ## Examples - The following example code demonstrates how to implement the method, which returns an instance of this class. In this example, the method is part of a login dialog box class. The method displays the dialog box, and then returns a instance initialized with the user-specified values. + The following example code demonstrates how to implement the method, which returns an instance of this class. In this example, the method is part of a login dialog box class. The method displays the dialog box, and then returns a instance initialized with the user-specified values. [!code-csharp[ClientApplicationServices#210](~/samples/snippets/csharp/VS_Snippets_Winforms/ClientApplicationServices/CS/Login.cs#210)] [!code-vb[ClientApplicationServices#210](~/samples/snippets/visualbasic/VS_Snippets_Winforms/ClientApplicationServices/VB/Login.vb#210)] diff --git a/xml/System.Web.ClientServices.Providers/ClientFormsAuthenticationMembershipProvider.xml b/xml/System.Web.ClientServices.Providers/ClientFormsAuthenticationMembershipProvider.xml index bfd492a6361a4..061b3a4569961 100644 --- a/xml/System.Web.ClientServices.Providers/ClientFormsAuthenticationMembershipProvider.xml +++ b/xml/System.Web.ClientServices.Providers/ClientFormsAuthenticationMembershipProvider.xml @@ -18,15 +18,15 @@ ## Remarks You can use client application services to validate users by using forms authentication. To enable forms authentication, you configure your application to use the class. For more information, see [How to: Configure Client Application Services](~/docs/framework/common-client-technologies/how-to-configure-client-application-services.md). - After configuration, you can validate users by calling the `static` method, which internally calls the method. + After configuration, you can validate users by calling the `static` method, which internally calls the method. - Forms authentication requires that the user specify their credentials through login controls provided by your application. You can retrieve the credentials and pass them to the method. You can also pass in empty strings or `null` to use a credentials provider. A credentials provider is an implementation specified in your application configuration file. You will typically implement the method to display a login dialog box and return a populated object. Using a credentials provider enables you to share a single login dialog box among multiple applications. + Forms authentication requires that the user specify their credentials through login controls provided by your application. You can retrieve the credentials and pass them to the method. You can also pass in empty strings or `null` to use a credentials provider. A credentials provider is an implementation specified in your application configuration file. You will typically implement the method to display a login dialog box and return a populated object. Using a credentials provider enables you to share a single login dialog box among multiple applications. - The method authenticates users through the login service indicated by the property. The value of the property is typically retrieved from the application configuration file along with other configuration values. For more information, see [How to: Configure Client Application Services](~/docs/framework/common-client-technologies/how-to-configure-client-application-services.md). + The method authenticates users through the login service indicated by the property. The value of the property is typically retrieved from the application configuration file along with other configuration values. For more information, see [How to: Configure Client Application Services](~/docs/framework/common-client-technologies/how-to-configure-client-application-services.md). - If the user is successfully authenticated, the service provider sets the `static` property to a new object that contains a new object that contains the user information. If a is configured for your application, you can use the object to retrieve user role information from the roles service. + If the user is successfully authenticated, the service provider sets the `static` property to a new object that contains a new object that contains the user information. If a is configured for your application, you can use the object to retrieve user role information from the roles service. - You can retrieve a reference to the current instance through the `static` property. You can use the membership provider reference to call the method directly. Additionally, you will need the membership provider reference to call the method, which is not available in the base class. + You can retrieve a reference to the current instance through the `static` property. You can use the membership provider reference to call the method directly. Additionally, you will need the membership provider reference to call the method, which is not available in the base class. You cannot use the class to create, delete, or modify membership information. To create, delete, or modify users, you must change the configuration of the login service on the server. @@ -557,11 +557,11 @@ method clears all authentication cookies from the cookie cache and resets the `static` property to a object that contains the current . + The method clears all authentication cookies from the cookie cache and resets the `static` property to a object that contains the current . - After you call this method, the current user is no longer authenticated for client application services. This means that you cannot retrieve roles through the class and settings through the class. However, because the user might have a valid Windows identity, you might still receive a `true` value from code such as the following: `Thread.CurrentPrincipal.Identity.IsAuthenticated`. To determine whether the user is authenticated for client application services, confirm that the property value of the retrieved through the `static` property is a reference. Then, check the property. + After you call this method, the current user is no longer authenticated for client application services. This means that you cannot retrieve roles through the class and settings through the class. However, because the user might have a valid Windows identity, you might still receive a `true` value from code such as the following: `Thread.CurrentPrincipal.Identity.IsAuthenticated`. To determine whether the user is authenticated for client application services, confirm that the property value of the retrieved through the `static` property is a reference. Then, check the property. - To reauthenticate the current user, call the method or the `static` method. + To reauthenticate the current user, call the method or the `static` method. @@ -921,9 +921,9 @@ property to display the user name in your application user interface (UI). + This event occurs only after the user is successfully validated. You can use this event to update your application to reflect the current user. For example, you can use the property to display the user name in your application user interface (UI). - You can silently revalidate users by calling the method. Therefore, you should avoid using the event to display intrusive UI. For example, you should not use the event to display a welcome dialog box. + You can silently revalidate users by calling the method. Therefore, you should avoid using the event to display intrusive UI. For example, you should not use the event to display a welcome dialog box. @@ -963,9 +963,9 @@ method, which internally calls the method. Alternatively, you can call this method directly, as shown in the Example section. + You can use client application services to validate users by using forms authentication. To validate users, you will typically call the `static` method, which internally calls the method. Alternatively, you can call this method directly, as shown in the Example section. - Forms authentication requires that the user specify their credentials through login controls provided by your application. You can retrieve the credentials and pass them to the method. You can also pass in empty strings or `null` to use a credentials provider. For more information, see [How to: Implement User Login with Client Application Services](~/docs/framework/common-client-technologies/how-to-implement-user-login-with-client-application-services.md). + Forms authentication requires that the user specify their credentials through login controls provided by your application. You can retrieve the credentials and pass them to the method. You can also pass in empty strings or `null` to use a credentials provider. For more information, see [How to: Implement User Login with Client Application Services](~/docs/framework/common-client-technologies/how-to-implement-user-login-with-client-application-services.md). @@ -1009,7 +1009,7 @@ method, which internally calls the method. Alternatively, you can call the method directly. You can call this overload to pass in a `rememberMe` value in addition to the `username` and `password` values. + You can use client application services to validate users by using forms authentication. To validate users, you will typically call the `static` method, which internally calls the method. Alternatively, you can call the method directly. You can call this overload to pass in a `rememberMe` value in addition to the `username` and `password` values. @@ -1052,7 +1052,7 @@ method, which internally calls the method. Alternatively, you can call the method directly. You can call this overload to access an authentication service at the location specified by the `serviceUri` parameter. Using this overload is an alternative to setting the property and calling the overload. + You can use client application services to validate users by using forms authentication. To validate users, you will typically call the `static` method, which internally calls the method. Alternatively, you can call the method directly. You can call this overload to access an authentication service at the location specified by the `serviceUri` parameter. Using this overload is an alternative to setting the property and calling the overload. diff --git a/xml/System.Web.ClientServices.Providers/ClientRoleProvider.xml b/xml/System.Web.ClientServices.Providers/ClientRoleProvider.xml index 4dbf5db12f765..9711335ca97b5 100644 --- a/xml/System.Web.ClientServices.Providers/ClientRoleProvider.xml +++ b/xml/System.Web.ClientServices.Providers/ClientRoleProvider.xml @@ -16,11 +16,11 @@ class. After configuration, you can determine whether an authenticated user is in a particular role by calling the method of the returned by the `static` property. For applications configured to use client application services, this property returns a . Because this class implements the interface, you do not need to reference it explicitly. The method internally calls the method. + You can use client application services to retrieve role information from an existing roles service by configuring your application to use the class. After configuration, you can determine whether an authenticated user is in a particular role by calling the method of the returned by the `static` property. For applications configured to use client application services, this property returns a . Because this class implements the interface, you do not need to reference it explicitly. The method internally calls the method. The class is a read-only role membership provider that retrieves role information for authenticated users from the roles service indicated by the property. The value of the property is typically retrieved from the application configuration file along with other configuration values. For more information, see [How to: Configure Client Application Services](~/docs/framework/common-client-technologies/how-to-configure-client-application-services.md). - You can retrieve the current instance through the `static` property. + You can retrieve the current instance through the `static` property. The class supports only the and methods of the abstract class. When you call one of these methods for a particular user, the service provider first checks the local data cache for role information. If the cache does not contain any role information or the cache has expired, the service provider retrieves the role information from the roles service and adds it to the cache. @@ -219,7 +219,7 @@ method retrieves role information for the current, authenticated user, which you must specify in the `username` parameter. You can get the user name through the `static` property as follows: `Thread.CurrentPrincipal.Identity.Name`. + The method retrieves role information for the current, authenticated user, which you must specify in the `username` parameter. You can get the user name through the `static` property as follows: `Thread.CurrentPrincipal.Identity.Name`. The service provider caches role information about the local file system to avoid unnecessary service calls. For more information, see the class overview. @@ -351,7 +351,7 @@ method of the returned by the `static` property. For applications configured to use client application services, this property returns a . Because this class implements the interface, you do not need to reference it explicitly. The method internally calls the method. The method uses the method to determine whether the user indicated by `username` is in the role indicated by `roleName`. + You can determine whether an authenticated user is in a particular role by calling the method of the returned by the `static` property. For applications configured to use client application services, this property returns a . Because this class implements the interface, you do not need to reference it explicitly. The method internally calls the method. The method uses the method to determine whether the user indicated by `username` is in the role indicated by `roleName`. The service provider caches role information about the local file system to avoid unnecessary service calls. For more information, see the class overview. diff --git a/xml/System.Web.ClientServices.Providers/ClientSettingsProvider.xml b/xml/System.Web.ClientServices.Providers/ClientSettingsProvider.xml index 1c4a9c8852d98..8a4c18f232bf4 100644 --- a/xml/System.Web.ClientServices.Providers/ClientSettingsProvider.xml +++ b/xml/System.Web.ClientServices.Providers/ClientSettingsProvider.xml @@ -27,7 +27,7 @@ ## Remarks You can use client application services to retrieve user settings from an existing Web settings service by configuring your application to use the class. For more information, see [How to: Configure Client Application Services](~/docs/framework/common-client-technologies/how-to-configure-client-application-services.md). After configuration, you can get and set user settings through an application settings class derived from and configured to use the class. You can use [!INCLUDE[vsprvs](~/includes/vsprvs-md.md)] to generate a `Settings` class for your project (accessed as `Properties.Settings.Default` in C# and `My.Settings` in [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)]). For more information about application settings, see [Application Settings Overview](~/docs/framework/winforms/advanced/application-settings-overview.md). - You can retrieve the current through the property using the fully-qualified class name as a key. You can also retrieve the provider through the property when you handle the event. + You can retrieve the current through the property using the fully-qualified class name as a key. You can also retrieve the provider through the property when you handle the event. > [!NOTE] > This class contains a at the class level that applies to all members of the class. A run-time exception is thrown if the immediate caller is security-transparent or partially trusted. For more information about security-critical types and members, see [Security-Transparent Code, Level 2](~/docs/framework/misc/security-transparent-code-level-2.md). @@ -280,7 +280,7 @@ method of your project's `Settings` class (typically accessed as `Properties.Settings.Default` in C# and `My.Settings` in [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)]). You can also revert Web settings to the previously cached values by calling the method. + This method is used internally by the application settings system and it not meant to be used by your application code. To reset Web settings to their default values, you will typically use the method of your project's `Settings` class (typically accessed as `Properties.Settings.Default` in C# and `My.Settings` in [!INCLUDE[vbprvb](~/includes/vbprvb-md.md)]). You can also revert Web settings to the previously cached values by calling the method. ]]> @@ -371,7 +371,7 @@ property to determine whether any settings were not successfully saved. + This event occurs after the settings provider accesses the settings service, even if the settings were not successfully saved. One reason that the provider might fail to save the settings is if the current user has been logged out. You can use the property to determine whether any settings were not successfully saved. This event does not occur if the settings provider cannot access the settings service, which instead causes the provider to throw a . diff --git a/xml/System.Web.ClientServices.Providers/ClientWindowsAuthenticationMembershipProvider.xml b/xml/System.Web.ClientServices.Providers/ClientWindowsAuthenticationMembershipProvider.xml index e281dfe620579..03e3691ca53e9 100644 --- a/xml/System.Web.ClientServices.Providers/ClientWindowsAuthenticationMembershipProvider.xml +++ b/xml/System.Web.ClientServices.Providers/ClientWindowsAuthenticationMembershipProvider.xml @@ -18,16 +18,16 @@ ## Remarks You can use client application services to validate users by using Windows authentication. To enable Windows authentication, you configure your application to use the class. For more information, see [How to: Configure Client Application Services](~/docs/framework/common-client-technologies/how-to-configure-client-application-services.md). - After configuration, you can validate users by calling the `static` method. The method internally calls the method. + After configuration, you can validate users by calling the `static` method. The method internally calls the method. - The method automatically authenticates the current user and sets the `static` property to a object that contains the current . If a is configured for your application, you can use the object to retrieve user role information from the roles service. + The method automatically authenticates the current user and sets the `static` property to a object that contains the current . If a is configured for your application, you can use the object to retrieve user role information from the roles service. - You can retrieve a reference to the current instance through the `static` property. You can use the membership provider reference to call the method directly. Additionally, you will need the membership provider reference to call the method, which is not available in the base class. + You can retrieve a reference to the current instance through the `static` property. You can use the membership provider reference to call the method directly. Additionally, you will need the membership provider reference to call the method, which is not available in the base class. ## Examples - The following example code demonstrates how to use this method to authenticate a user by using Windows authentication. In this example, the value of the `static` property is cast to a instance. This makes sure that a will be thrown if you accidentally test this code by using another membership provider. + The following example code demonstrates how to use this method to authenticate a user by using Windows authentication. In this example, the value of the `static` property is cast to a instance. This makes sure that a will be thrown if you accidentally test this code by using another membership provider. [!code-csharp[ClientApplicationServices#309](~/samples/snippets/csharp/VS_Snippets_Winforms/ClientApplicationServices/CS/Class1.cs#309)] [!code-vb[ClientApplicationServices#309](~/samples/snippets/visualbasic/VS_Snippets_Winforms/ClientApplicationServices/VB/Class1.vb#309)] @@ -466,7 +466,7 @@ property is set to a object that enables access to the configured role service. The method resets the property to a object that contains the current . After you call this method, you can no longer retrieve roles for the user through the class. To reauthenticate the current user, call the method. + For users authenticated through client application services, the `static` property is set to a object that enables access to the configured role service. The method resets the property to a object that contains the current . After you call this method, you can no longer retrieve roles for the user through the class. To reauthenticate the current user, call the method. @@ -775,7 +775,7 @@ class, the `static` method will use this method for its implementation. The method automatically authenticates the current user and sets the `static` property to a object that contains the current . If a is configured for your application, you can use the object to retrieve user role information from the roles service. + When you configure your application to use the class, the `static` method will use this method for its implementation. The method automatically authenticates the current user and sets the `static` property to a object that contains the current . If a is configured for your application, you can use the object to retrieve user role information from the roles service. diff --git a/xml/System.Web.ClientServices.Providers/SettingsSavedEventArgs.xml b/xml/System.Web.ClientServices.Providers/SettingsSavedEventArgs.xml index 3da3984f5983d..967ac106fd400 100644 --- a/xml/System.Web.ClientServices.Providers/SettingsSavedEventArgs.xml +++ b/xml/System.Web.ClientServices.Providers/SettingsSavedEventArgs.xml @@ -16,7 +16,7 @@ event occurs after the settings provider accesses the settings service, even if the settings were not successfully saved. One reason that the provider might fail to save the settings is if the current user has been logged out. You can use the property to determine whether any settings were not successfully saved. + The event occurs after the settings provider accesses the settings service, even if the settings were not successfully saved. One reason that the provider might fail to save the settings is if the current user has been logged out. You can use the property to determine whether any settings were not successfully saved. This event does not occur if the settings provider cannot access the settings service, which instead causes the provider to throw a . diff --git a/xml/System.Web.ClientServices/ClientFormsIdentity.xml b/xml/System.Web.ClientServices/ClientFormsIdentity.xml index f9a62026b585d..877530de869f9 100644 --- a/xml/System.Web.ClientServices/ClientFormsIdentity.xml +++ b/xml/System.Web.ClientServices/ClientFormsIdentity.xml @@ -23,9 +23,9 @@ method. After authentication, you can retrieve a reference to the current instance through the property of the retrieved through the `static` property. For more information, see [Client Application Services](~/docs/framework/common-client-technologies/client-application-services.md). + The client application services feature uses this class to represent an authenticated user. When you configure your application to use client application services and forms authentication, you can authenticate a user by calling the `static` method. After authentication, you can retrieve a reference to the current instance through the property of the retrieved through the `static` property. For more information, see [Client Application Services](~/docs/framework/common-client-technologies/client-application-services.md). - You will typically access a object as an reference to avoid a direct dependency on this class. You can determine whether a user is authenticated by checking the property of the identity. However, the user may be authenticated for Windows, but not for client application services. To determine whether the user is authenticated for client application services, you should also confirm that the property value is "ClientForms". + You will typically access a object as an reference to avoid a direct dependency on this class. You can determine whether a user is authenticated by checking the property of the identity. However, the user may be authenticated for Windows, but not for client application services. To determine whether the user is authenticated for client application services, you should also confirm that the property value is "ClientForms". You must use an explicit reference to call the method, which is not defined by the interface. @@ -117,7 +117,7 @@ object as an reference to avoid a direct dependency on this class. You can determine whether a user is authenticated by checking the property of the identity. However, the user may be authenticated for Windows, but not for client application services. To determine whether the user is authenticated for client application services, you should also confirm that the property value is "ClientForms". For more information, see the class overview. + You will typically access a object as an reference to avoid a direct dependency on this class. You can determine whether a user is authenticated by checking the property of the identity. However, the user may be authenticated for Windows, but not for client application services. To determine whether the user is authenticated for client application services, you should also confirm that the property value is "ClientForms". For more information, see the class overview. @@ -216,7 +216,7 @@ object as an reference to avoid a direct dependency on this class. You can determine whether a user is authenticated by checking the property of the identity. However, the user may be authenticated for Windows, but not for client application services. To determine whether the user is authenticated for client application services, you should also confirm that the property value is "ClientForms". For more information, see the class overview. + You will typically access a object as an reference to avoid a direct dependency on this class. You can determine whether a user is authenticated by checking the property of the identity. However, the user may be authenticated for Windows, but not for client application services. To determine whether the user is authenticated for client application services, you should also confirm that the property value is "ClientForms". For more information, see the class overview. diff --git a/xml/System.Web.ClientServices/ClientRolePrincipal.xml b/xml/System.Web.ClientServices/ClientRolePrincipal.xml index 2bbf602fdb4c8..44f6b139c3e69 100644 --- a/xml/System.Web.ClientServices/ClientRolePrincipal.xml +++ b/xml/System.Web.ClientServices/ClientRolePrincipal.xml @@ -20,7 +20,7 @@ or the sets the `static` property to an instance of this class. The initializes the property to a new instance of the class. The initializes the property to the object returned by the `static` method. + When you validate a user in client application services, the or the sets the `static` property to an instance of this class. The initializes the property to a new instance of the class. The initializes the property to the object returned by the `static` method. You will not typically access this class directly. Normally, you will call the method of the returned by the `static` property. However, you can cast the property value to a reference to call the method explicitly, as demonstrated in the Example section. @@ -57,7 +57,7 @@ ## Remarks The property is initialized with the value of the `identity` parameter. - When you validate a user in client application services, the or the sets the `static` property to an instance of this class. The initializes the property to a new instance of the class. The initializes the property to the object returned by the `static` method. + When you validate a user in client application services, the or the sets the `static` property to an instance of this class. The initializes the property to a new instance of the class. The initializes the property to the object returned by the `static` method. ]]> @@ -82,7 +82,7 @@ or the sets the `static` property to an instance of this class. The initializes the property to a new instance of the class. The initializes the property to the object returned by the `static` method. + When you validate a user in client application services, the or the sets the `static` property to an instance of this class. The initializes the property to a new instance of the class. The initializes the property to the object returned by the `static` method. ]]> @@ -112,9 +112,9 @@ method of the returned by the `static` property. However, you can cast the property value to a reference to call this method explicitly, as demonstrated in the Example section. + Normally, you will call the method of the returned by the `static` property. However, you can cast the property value to a reference to call this method explicitly, as demonstrated in the Example section. - The method will always return `false` if the user login has expired. This will not occur if your application calls the method one time shortly after authentication. If your application must retrieve user roles at other times, you might want to add code to revalidate users whose login has expired. If all valid users are assigned to roles, you can determine whether the login has expired by calling the method. If no roles are returned, the login has expired. For an example of this functionality, see the method. This functionality is only necessary if you have selected **Require users to log on again whenever the server cookie expires** in your application configuration. For more information, see [How to: Configure Client Application Services](~/docs/framework/common-client-technologies/how-to-configure-client-application-services.md). + The method will always return `false` if the user login has expired. This will not occur if your application calls the method one time shortly after authentication. If your application must retrieve user roles at other times, you might want to add code to revalidate users whose login has expired. If all valid users are assigned to roles, you can determine whether the login has expired by calling the method. If no roles are returned, the login has expired. For an example of this functionality, see the method. This functionality is only necessary if you have selected **Require users to log on again whenever the server cookie expires** in your application configuration. For more information, see [How to: Configure Client Application Services](~/docs/framework/common-client-technologies/how-to-configure-client-application-services.md). diff --git a/xml/System.Web.Compilation/AppSettingsExpressionBuilder.xml b/xml/System.Web.Compilation/AppSettingsExpressionBuilder.xml index ffae56321d5e6..f98b7ae37167a 100644 --- a/xml/System.Web.Compilation/AppSettingsExpressionBuilder.xml +++ b/xml/System.Web.Compilation/AppSettingsExpressionBuilder.xml @@ -110,7 +110,7 @@ ` is encountered in a no-compile page. It retrieves the appropriate value from the key/value pairs in the `` section of the Web.config file. This method overrides by calling the method with the property as the `key` parameter, the property on the property as the `propertyName` parameter, and the of the `target` parameter as the `targetType` parameter. + This method is called when an expression of the form `<%$ AppSettings: someApplicationSetting %>` is encountered in a no-compile page. It retrieves the appropriate value from the key/value pairs in the `` section of the Web.config file. This method overrides by calling the method with the property as the `key` parameter, the property on the property as the `propertyName` parameter, and the of the `target` parameter as the `targetType` parameter. ]]> diff --git a/xml/System.Web.Compilation/AssemblyBuilder.xml b/xml/System.Web.Compilation/AssemblyBuilder.xml index 25f7e299ba838..de5e7593d2bcf 100644 --- a/xml/System.Web.Compilation/AssemblyBuilder.xml +++ b/xml/System.Web.Compilation/AssemblyBuilder.xml @@ -20,7 +20,7 @@ The class defines build functionality for individual files, and the class combines the source code contributed by each instance into a single assembly. The ASP.NET build environment passes an object to the methods when building an assembly from one or more files, so that each instance can contribute source code for its file to the overall assembly. - The ASP.NET build environment determines the language and compiler required by files within the project, based on the property. The build environment groups files based on their compiler settings and builds an assembly from files that require the same compiler. + The ASP.NET build environment determines the language and compiler required by files within the project, based on the property. The build environment groups files based on their compiler settings and builds an assembly from files that require the same compiler. The property indicates the implementation that the ASP.NET build environment uses to compile an assembly from the source code contributed by each implementation. @@ -66,9 +66,9 @@ ## Remarks A implementation uses the method when generating source code that references types within the input assembly. - The ASP.NET build environment initializes the default collection of assemblies available for reference through the build provider in the property. If the build provider generates source code that references additional assemblies, the build provider adds the additional assemblies using the method. The ASP.NET build environment resolves external types during assembly compilation using both the referenced assemblies added by build providers and the default collection of assemblies available for reference. + The ASP.NET build environment initializes the default collection of assemblies available for reference through the build provider in the property. If the build provider generates source code that references additional assemblies, the build provider adds the additional assemblies using the method. The ASP.NET build environment resolves external types during assembly compilation using both the referenced assemblies added by build providers and the default collection of assemblies available for reference. - Typically, a object adds source code to the object in the method. If a build provider generates source code that uses an external type, the build provider adds the type's assembly using the method. + Typically, a object adds source code to the object in the method. If a build provider generates source code that uses an external type, the build provider adds the type's assembly using the method. Use the method to add a referenced assembly required in source code generated by a instance for a specific file type. Use the [assemblies Element for compilation (ASP.NET Settings Schema)](http://msdn.microsoft.com/en-us/3811c448-af1c-498d-be2b-6ed2634c51e9) configuration element to configure an assembly for reference across multiple file types in a project. @@ -127,9 +127,9 @@ property indicates the implementation that the ASP.NET build environment uses to compile an assembly from the source code contributed by each implementation. + The property indicates the implementation that the ASP.NET build environment uses to compile an assembly from the source code contributed by each implementation. - The ASP.NET build environment determines the language and compiler required by files within the project, based on the property. The build environment groups files based on their compiler settings and builds an assembly from files that require the same compiler. + The ASP.NET build environment determines the language and compiler required by files within the project, based on the property. The build environment groups files based on their compiler settings and builds an assembly from files that require the same compiler. ]]> diff --git a/xml/System.Web.Compilation/BuildManager.xml b/xml/System.Web.Compilation/BuildManager.xml index bbf06cfd188e6..ddfccb4abf54c 100644 --- a/xml/System.Web.Compilation/BuildManager.xml +++ b/xml/System.Web.Compilation/BuildManager.xml @@ -251,9 +251,9 @@ method overload behaves like the method overload. Both overloads return a current build dependency set if one exists, otherwise they return `null`. + If the `ensureIsUpToDate` parameter value is set to `true`, the method overload behaves like the method overload. Both overloads return a current build dependency set if one exists, otherwise they return `null`. - However, the method overload includes the option to return any build dependency set that is available, even an outdated one. If the `ensureIsUpToDate` parameter value is set to `false`, the method will return any available build dependency set. + However, the method overload includes the option to return any build dependency set that is available, even an outdated one. If the `ensureIsUpToDate` parameter value is set to `false`, the method will return any available build dependency set. ]]> diff --git a/xml/System.Web.Compilation/BuildProvider.xml b/xml/System.Web.Compilation/BuildProvider.xml index a034efb977c58..0172880dede56 100644 --- a/xml/System.Web.Compilation/BuildProvider.xml +++ b/xml/System.Web.Compilation/BuildProvider.xml @@ -265,7 +265,7 @@ ## Remarks Use the method to examine the compiler type configured in the build provider for a specific language name. Use the method to examine the default compiler type for a build provider. - The base class determines the default compiler type using the elements in the property of the object for the configuration file. This is equivalent to examining the elements in the and the elements in the sections of the configuration file. For example, for the `language` value VB, the base class method returns a object that corresponds to the configured settings for an instance of . + The base class determines the default compiler type using the elements in the property of the object for the configuration file. This is equivalent to examining the elements in the and the elements in the sections of the configuration file. For example, for the `language` value VB, the base class method returns a object that corresponds to the configured settings for an instance of . When you derive from the class, you can use to set the property value for the language supported by your implementation. diff --git a/xml/System.Web.Compilation/BuildProviderResultFlags.xml b/xml/System.Web.Compilation/BuildProviderResultFlags.xml index 38ab770e534e3..28b28674f0d92 100644 --- a/xml/System.Web.Compilation/BuildProviderResultFlags.xml +++ b/xml/System.Web.Compilation/BuildProviderResultFlags.xml @@ -20,7 +20,7 @@ values are used to indicate the results from the method. The enumeration values indicate actions that are required after a virtual path is built within the ASP.NET build environment. The values are used by the ASP.NET build environment when using instances of the class to build files and load the compiled assemblies. + The values are used to indicate the results from the method. The enumeration values indicate actions that are required after a virtual path is built within the ASP.NET build environment. The values are used by the ASP.NET build environment when using instances of the class to build files and load the compiled assemblies. ]]> diff --git a/xml/System.Web.Compilation/CompilerType.xml b/xml/System.Web.Compilation/CompilerType.xml index bbdae0de44bf1..fd6b03d3f90c6 100644 --- a/xml/System.Web.Compilation/CompilerType.xml +++ b/xml/System.Web.Compilation/CompilerType.xml @@ -112,9 +112,9 @@ method overrides the method. + The method overrides the method. - compares two instances based on their , , , and properties. + compares two instances based on their , , , and properties. ]]> @@ -140,7 +140,7 @@ method overrides the method. + The method overrides the method. generates the same hash code for two objects that are equal according to the method. diff --git a/xml/System.Web.Compilation/ConnectionStringsExpressionBuilder.xml b/xml/System.Web.Compilation/ConnectionStringsExpressionBuilder.xml index d2517110efd8b..d8e7b6a3a9763 100644 --- a/xml/System.Web.Compilation/ConnectionStringsExpressionBuilder.xml +++ b/xml/System.Web.Compilation/ConnectionStringsExpressionBuilder.xml @@ -211,7 +211,7 @@ property returns a collection of connection string values. The method returns the provider for the value from this collection that is associated with the connection string name. + The property returns a collection of connection string values. The method returns the provider for the value from this collection that is associated with the connection string name. ]]> diff --git a/xml/System.Web.Configuration/ClientTarget.xml b/xml/System.Web.Configuration/ClientTarget.xml index 9a05f599e906e..257345b5a6390 100644 --- a/xml/System.Web.Configuration/ClientTarget.xml +++ b/xml/System.Web.Configuration/ClientTarget.xml @@ -22,9 +22,9 @@ The class contains two properties identifying a client browser, also named user agent. One property is the alias associated with the client browser identified by the second property. ASP.NET uses this information to render server controls in a page. - For information about how the user agent or its alias is used programmatically, see the property. For information about how the user agent or its alias is used declaratively, see [@ Page](http://msdn.microsoft.com/en-us/f06cf9e5-22bb-461d-8b8f-549e53ff40a4). + For information about how the user agent or its alias is used programmatically, see the property. For information about how the user agent or its alias is used declaratively, see [@ Page](http://msdn.microsoft.com/en-us/f06cf9e5-22bb-461d-8b8f-549e53ff40a4). - If the property is not set, the object that is associated with the property reflects the capabilities of the client browser. (It reflects the capabilities of the browser type, but not necessarily the settings in a specific instance of that browser.) If the property is set, the client browser detection is disabled and the page uses browser capabilities that are associated with the user agent string that you define. You can set this property to any valid user agent string. + If the property is not set, the object that is associated with the property reflects the capabilities of the client browser. (It reflects the capabilities of the browser type, but not necessarily the settings in a specific instance of that browser.) If the property is set, the client browser detection is disabled and the page uses browser capabilities that are associated with the user agent string that you define. You can set this property to any valid user agent string. diff --git a/xml/System.Web.Configuration/ClientTargetCollection.xml b/xml/System.Web.Configuration/ClientTargetCollection.xml index 442828cdf7590..35109e7e41310 100644 --- a/xml/System.Web.Configuration/ClientTargetCollection.xml +++ b/xml/System.Web.Configuration/ClientTargetCollection.xml @@ -145,12 +145,12 @@ method is dependent upon the value chosen. To update the configuration file you use one of these two methods: or . + The result of updating the configuration file after calling the method is dependent upon the value chosen. To update the configuration file you use one of these two methods: or . > [!NOTE] -> Calling is equivalent to calling when the value is modified. +> Calling is equivalent to calling when the value is modified. - If you use the method, the following conditions apply: + If you use the method, the following conditions apply: - If you pass the or parameter value, then a `clear` element is inserted into the `clientTarget` section of the configuration file at the current hierarchy level. diff --git a/xml/System.Web.Configuration/FormsAuthenticationConfiguration.xml b/xml/System.Web.Configuration/FormsAuthenticationConfiguration.xml index 2186c5c198f5c..b0ba74d418da6 100644 --- a/xml/System.Web.Configuration/FormsAuthenticationConfiguration.xml +++ b/xml/System.Web.Configuration/FormsAuthenticationConfiguration.xml @@ -225,7 +225,7 @@ ## Remarks The is used for the authentication cookies. - This property corresponds to the value of . + This property corresponds to the value of . This setting will take precedence over the `domain` attribute of the section for forms authentication cookies. diff --git a/xml/System.Web.Configuration/HttpCapabilitiesBase.xml b/xml/System.Web.Configuration/HttpCapabilitiesBase.xml index 49b4da7f490e6..5cfc3f20ae4c8 100644 --- a/xml/System.Web.Configuration/HttpCapabilitiesBase.xml +++ b/xml/System.Web.Configuration/HttpCapabilitiesBase.xml @@ -20,7 +20,7 @@ is the base class from which the class is derived. offers a large number of read-only properties that provide type-safe access to a browser's capabilities dictionary. You can access the class through the property that is exposed by the ASP.NET property. + is the base class from which the class is derived. offers a large number of read-only properties that provide type-safe access to a browser's capabilities dictionary. You can access the class through the property that is exposed by the ASP.NET property. diff --git a/xml/System.Web.Configuration/HttpRuntimeSection.xml b/xml/System.Web.Configuration/HttpRuntimeSection.xml index 9e8c09c03439a..99cba6d737339 100644 --- a/xml/System.Web.Configuration/HttpRuntimeSection.xml +++ b/xml/System.Web.Configuration/HttpRuntimeSection.xml @@ -1062,7 +1062,7 @@ class checks both the property and the property to determine whether to send the `cache-control:private` header in the HTTP response. If either property is set to `false`, the header will not be sent. When the cache-control header is set to `private`, then the client will not cache the response in a shared cache. + The class checks both the property and the property to determine whether to send the `cache-control:private` header in the HTTP response. If either property is set to `false`, the header will not be sent. When the cache-control header is set to `private`, then the client will not cache the response in a shared cache. Support for the property in the class is provided for compatibility with legacy applications; this property is obsolete in the .NET Framework version 2.0. For more information, see the class. diff --git a/xml/System.Web.Configuration/MachineKeySection.xml b/xml/System.Web.Configuration/MachineKeySection.xml index 19671e4075042..c28f410aaf0d0 100644 --- a/xml/System.Web.Configuration/MachineKeySection.xml +++ b/xml/System.Web.Configuration/MachineKeySection.xml @@ -94,7 +94,7 @@ property. The property value is passed to the factory method. + This property must be set if you set the property. The property value is passed to the factory method. ]]> @@ -177,7 +177,7 @@ property to and set this property to a string that represents a class that derives from the class. This string corresponds to the `providerClass` parameter that is passed to the static factory method. The class you specify is used by the and methods even if you do not specify the option. + To specify custom data protection algorithms for ASP.NET, set the property to and set this property to a string that represents a class that derives from the class. This string corresponds to the `providerClass` parameter that is passed to the static factory method. The class you specify is used by the and methods even if you do not specify the option. If you set this property, you must also set the property. @@ -268,7 +268,7 @@ If you add the "IsolateApps" modifier to the "AutoGenerate" value, ASP.NET generates a unique encrypted key for each application by using each application's . This is the default setting. - If you add the "IsolateByAppId" modifier to the "AutoGenerate" value, ASP.NET generates a unique encrypted key for each application by using each application's . If two distinct applications share a virtual path (perhaps because those applications are running on different ports), this flag can be used to further distinguish them from one another. The "IsolateByAppId" flag is understood only by ASP.NET 4.5, but it can be used regardless of the setting. + If you add the "IsolateByAppId" modifier to the "AutoGenerate" value, ASP.NET generates a unique encrypted key for each application by using each application's . If two distinct applications share a virtual path (perhaps because those applications are running on different ports), this flag can be used to further distinguish them from one another. The "IsolateByAppId" flag is understood only by ASP.NET 4.5, but it can be used regardless of the setting. If you need to support configuration across a network of Web servers (a Web farm), set the property manually to ensure consistent configuration. For information about how to manually generate values for the `DecryptionKey` attribute, see [How To: Configure MachineKey in ASP.NET 2.0](http://go.microsoft.com/fwlink/?linkid=155113). @@ -454,7 +454,7 @@ If you add the "IsolateApps" modifier to the "AutoGenerate" value, ASP.NET generates a unique encrypted key for each application by using each application's . This is the default setting. - If you add the "IsolateByAppId" modifier to the "AutoGenerate" value, ASP.NET generates a unique encrypted key for each application by using each application's . If two distinct applications share a virtual path (perhaps because those applications are running on different ports), this flag can be used to further distinguish them from one another. The "IsolateByAppId" flag is understood only by ASP.NET 4.5, but it can be used regardless of the setting. + If you add the "IsolateByAppId" modifier to the "AutoGenerate" value, ASP.NET generates a unique encrypted key for each application by using each application's . If two distinct applications share a virtual path (perhaps because those applications are running on different ports), this flag can be used to further distinguish them from one another. The "IsolateByAppId" flag is understood only by ASP.NET 4.5, but it can be used regardless of the setting. If you need to support configuration across a network of Web servers (a Web farm), set the property manually to ensure consistent configuration. For information about how to manually generate values for the `DecryptionKey` attribute, see [How To: Configure MachineKey in ASP.NET 2.0](http://go.microsoft.com/fwlink/?linkid=155113). diff --git a/xml/System.Web.Configuration/MachineKeyValidation.xml b/xml/System.Web.Configuration/MachineKeyValidation.xml index 6cc3e8ce4b713..daf7558c17d19 100644 --- a/xml/System.Web.Configuration/MachineKeyValidation.xml +++ b/xml/System.Web.Configuration/MachineKeyValidation.xml @@ -75,7 +75,7 @@ ## Remarks The custom hashing algorithm can be implemented in any class that derives from . - The custom algorithm is typically specified declaratively in the validation attribute of the element, in the format `alg:`*algorithm_name*. For information about how to specify a custom algorithm in code, see the property. + The custom algorithm is typically specified declaratively in the validation attribute of the element, in the format `alg:`*algorithm_name*. For information about how to specify a custom algorithm in code, see the property. ]]> diff --git a/xml/System.Web.Configuration/OutputCacheProfile.xml b/xml/System.Web.Configuration/OutputCacheProfile.xml index 84ce029dfaed2..1f37069997a45 100644 --- a/xml/System.Web.Configuration/OutputCacheProfile.xml +++ b/xml/System.Web.Configuration/OutputCacheProfile.xml @@ -244,9 +244,9 @@ property set to `true` issues a response specifying in its header to prevent secondary storage of sensitive information. + The page that has the property set to `true` issues a response specifying in its header to prevent secondary storage of sensitive information. - Setting this attribute to `true` is equivalent to invoking the method during a Web request. + Setting this attribute to `true` is equivalent to invoking the method during a Web request. @@ -505,7 +505,7 @@ The setting must be defined in either the profile or the directive of the page using the profile. > [!NOTE] -> The settings are the same ones used by the `VaryByParam` attribute of the . Varying by all parameters by setting the value of "*" is not recommended. It can result in cache overflow or a denial of service attack on the Web server. +> The settings are the same ones used by the `VaryByParam` attribute of the . Varying by all parameters by setting the value of "*" is not recommended. It can result in cache overflow or a denial of service attack on the Web server. diff --git a/xml/System.Web.Configuration/PagesSection.xml b/xml/System.Web.Configuration/PagesSection.xml index 357905feff124..a13527bb2d4dc 100644 --- a/xml/System.Web.Configuration/PagesSection.xml +++ b/xml/System.Web.Configuration/PagesSection.xml @@ -370,7 +370,7 @@ public partial class AutoEventWireupExample : System.Web.UI.Page property. For information about how it is used, see the property. + This value is set by the `controlRenderingCompatibilityVersion` attribute of the `pages` element in the Web.config file. The value of this property is the default value for the property. For information about how it is used, see the property. ]]> diff --git a/xml/System.Web.Configuration/ProfileGroupSettings.xml b/xml/System.Web.Configuration/ProfileGroupSettings.xml index 77bac409eb217..e9d98ea739958 100644 --- a/xml/System.Web.Configuration/ProfileGroupSettings.xml +++ b/xml/System.Web.Configuration/ProfileGroupSettings.xml @@ -18,7 +18,7 @@ ## Remarks The class provides a way to programmatically create, access, and modify groups of properties added to the `group` subsection of the `profile` section of a configuration file. - The `profile` section of the configuration file specifies a schema for user profiles. At run time, the ASP.NET compilation system uses the information specified in the `profile` section to generate a class called `ProfileCommon`, which is derived from . The `ProfileCommon` class definition is based on the properties defined in the `properties` subsection of the `profile` section of the configuration file. An instance of this class is created for each user profile, and you can access the individual profile values in your code through the property. For more information about the profile features added to [!INCLUDE[vstecasplong](~/includes/vstecasplong-md.md)], see [ASP.NET Profile Properties Overview](http://msdn.microsoft.com/library/89439440-92ea-48c3-a4bd-dea40307899d). + The `profile` section of the configuration file specifies a schema for user profiles. At run time, the ASP.NET compilation system uses the information specified in the `profile` section to generate a class called `ProfileCommon`, which is derived from . The `ProfileCommon` class definition is based on the properties defined in the `properties` subsection of the `profile` section of the configuration file. An instance of this class is created for each user profile, and you can access the individual profile values in your code through the property. For more information about the profile features added to [!INCLUDE[vstecasplong](~/includes/vstecasplong-md.md)], see [ASP.NET Profile Properties Overview](http://msdn.microsoft.com/library/89439440-92ea-48c3-a4bd-dea40307899d). diff --git a/xml/System.Web.Configuration/ProfilePropertySettings.xml b/xml/System.Web.Configuration/ProfilePropertySettings.xml index c3b0539ca2327..05bf512c8ce02 100644 --- a/xml/System.Web.Configuration/ProfilePropertySettings.xml +++ b/xml/System.Web.Configuration/ProfilePropertySettings.xml @@ -18,7 +18,7 @@ ## Remarks The class provides a way to programmatically create, access, and modify the definition of an individual property added to the `properties` subsection of the `profile` section of a configuration file. - The `profile` section of the configuration file specifies a schema for user profiles. At run time, the ASP.NET compilation system uses the information specified in the `profile` section to generate a class called `ProfileCommon`, which is derived from . The `ProfileCommon` class definition is based on the properties defined in the `properties` subsection of the `profile` section of the configuration file. An instance of this class is created for each user profile, and you can access the individual profile values in your code through the property. For more information about profile properties, see [ASP.NET Profile Properties Overview](http://msdn.microsoft.com/library/89439440-92ea-48c3-a4bd-dea40307899d). For more information about the profile features added to [!INCLUDE[vstecasplong](~/includes/vstecasplong-md.md)], see [ASP.NET Profile Properties Overview](http://msdn.microsoft.com/library/89439440-92ea-48c3-a4bd-dea40307899d). + The `profile` section of the configuration file specifies a schema for user profiles. At run time, the ASP.NET compilation system uses the information specified in the `profile` section to generate a class called `ProfileCommon`, which is derived from . The `ProfileCommon` class definition is based on the properties defined in the `properties` subsection of the `profile` section of the configuration file. An instance of this class is created for each user profile, and you can access the individual profile values in your code through the property. For more information about profile properties, see [ASP.NET Profile Properties Overview](http://msdn.microsoft.com/library/89439440-92ea-48c3-a4bd-dea40307899d). For more information about the profile features added to [!INCLUDE[vstecasplong](~/includes/vstecasplong-md.md)], see [ASP.NET Profile Properties Overview](http://msdn.microsoft.com/library/89439440-92ea-48c3-a4bd-dea40307899d). @@ -302,7 +302,7 @@ ## Remarks Profile providers are data sources in which user-profile values are stored. You can specify profile providers in the `providers` subsection of the `profile` section of a configuration file. - If the value of this property is an empty string, the default provider specified in the property is used. + If the value of this property is an empty string, the default provider specified in the property is used. diff --git a/xml/System.Web.Configuration/ProfilePropertySettingsCollection.xml b/xml/System.Web.Configuration/ProfilePropertySettingsCollection.xml index 5e07aaade52dd..186560b39a092 100644 --- a/xml/System.Web.Configuration/ProfilePropertySettingsCollection.xml +++ b/xml/System.Web.Configuration/ProfilePropertySettingsCollection.xml @@ -363,7 +363,7 @@ throws specialized errors if the element name is either "clear" or "group". After checking for these conditions, the method then explicitly calls its base implementation, the method. + This implementation of throws specialized errors if the element name is either "clear" or "group". After checking for these conditions, the method then explicitly calls its base implementation, the method. ]]> diff --git a/xml/System.Web.Configuration/ProfileSection.xml b/xml/System.Web.Configuration/ProfileSection.xml index b8d9d53660eba..d01298c07dc70 100644 --- a/xml/System.Web.Configuration/ProfileSection.xml +++ b/xml/System.Web.Configuration/ProfileSection.xml @@ -16,7 +16,7 @@ class provides a way to programmatically access and modify the content of the configuration file `profile` section. The `profile` section of the configuration file specifies a schema for user profiles. At run time, the ASP.NET compilation system uses the information specified in the `profile` section to generate a class called `ProfileCommon`, which is derived from . The `ProfileCommon` class definition is based on the properties defined in the `profile` section of the configuration file. The class allows you to access and modify the values for individual profiles. An instance of this class is created for each user profile, and you can access the individual profile values in your code through the property. For more information about the profile features added to [!INCLUDE[vstecasplong](~/includes/vstecasplong-md.md)], see [ASP.NET Profile Properties Overview](http://msdn.microsoft.com/library/89439440-92ea-48c3-a4bd-dea40307899d). + The class provides a way to programmatically access and modify the content of the configuration file `profile` section. The `profile` section of the configuration file specifies a schema for user profiles. At run time, the ASP.NET compilation system uses the information specified in the `profile` section to generate a class called `ProfileCommon`, which is derived from . The `ProfileCommon` class definition is based on the properties defined in the `profile` section of the configuration file. The class allows you to access and modify the values for individual profiles. An instance of this class is created for each user profile, and you can access the individual profile values in your code through the property. For more information about the profile features added to [!INCLUDE[vstecasplong](~/includes/vstecasplong-md.md)], see [ASP.NET Profile Properties Overview](http://msdn.microsoft.com/library/89439440-92ea-48c3-a4bd-dea40307899d). diff --git a/xml/System.Web.Configuration/UrlMappingCollection.xml b/xml/System.Web.Configuration/UrlMappingCollection.xml index dac68124d7ede..f5ae1db25b569 100644 --- a/xml/System.Web.Configuration/UrlMappingCollection.xml +++ b/xml/System.Web.Configuration/UrlMappingCollection.xml @@ -140,7 +140,7 @@ The following list describes the conditions that apply if you use the method to save the file: -- If you pass or as the parameter value, a `clear` element is inserted into the `urlMappings` section of the configuration file at the current hierarchy level. +- If you pass or as the parameter value, a `clear` element is inserted into the `urlMappings` section of the configuration file at the current hierarchy level. - If you pass as the parameter value, a series of `remove` elements are added to the `urlMappings` of the configuration file at the current hierarchy level. These `remove` elements remove all references to the `add` elements defined in the parent configuration files at higher levels in the hierarchy. With the enumeration value, there is one additional property on the collection that affects what gets serialized to the configuration file. The property is and is `false` by default. One of the following conditions applies: diff --git a/xml/System.Web.DynamicData.Design/DataControlReferenceIDConverter.xml b/xml/System.Web.DynamicData.Design/DataControlReferenceIDConverter.xml index 8835d432ade79..f729678c43f8d 100644 --- a/xml/System.Web.DynamicData.Design/DataControlReferenceIDConverter.xml +++ b/xml/System.Web.DynamicData.Design/DataControlReferenceIDConverter.xml @@ -67,7 +67,7 @@ method gets the set of controls that can be converted. It creates a instance that contains objects that are valid data types in `context`. + The method gets the set of controls that can be converted. It creates a instance that contains objects that are valid data types in `context`. ]]> diff --git a/xml/System.Web.DynamicData.ModelProviders/ColumnProvider.xml b/xml/System.Web.DynamicData.ModelProviders/ColumnProvider.xml index 5b31426065e0a..c12a027920434 100644 --- a/xml/System.Web.DynamicData.ModelProviders/ColumnProvider.xml +++ b/xml/System.Web.DynamicData.ModelProviders/ColumnProvider.xml @@ -163,7 +163,7 @@ property can be used to determine whether column operations such as sorting are supported. For example, the implementation of the interface of the data model will not support sorting on properties that return `true` for the property, because the column does not exist in the database. + Columns that are not in the data context typically come from a view or calculated property. The value of the property can be used to determine whether column operations such as sorting are supported. For example, the implementation of the interface of the data model will not support sorting on properties that return `true` for the property, because the column does not exist in the database. ]]> diff --git a/xml/System.Web.DynamicData/DynamicControl.xml b/xml/System.Web.DynamicData/DynamicControl.xml index bb17b5f6cf441..8bd31e41f0fe7 100644 --- a/xml/System.Web.DynamicData/DynamicControl.xml +++ b/xml/System.Web.DynamicData/DynamicControl.xml @@ -235,7 +235,7 @@ object of the data source control also has a property named . This property performs the same function. Make sure that both properties are set appropriately. + The object of the data source control also has a property named . This property performs the same function. Make sure that both properties are set appropriately. ]]> @@ -346,7 +346,7 @@ By default, the formatting string is applied to the field value only when the property is set to . To apply the formatting string to the field value while in edit mode, set the property to `true`. - The display format that you specify using the property is specific to this instance of the control. You can also change the display format for a data field across the entire application by applying the to your data model and setting the named parameter in the constructor. For more information, see [ASP.NET Dynamic Data](http://msdn.microsoft.com/library/78c7fcd7-5f38-46a0-a4bc-48eff3c8a512). + The display format that you specify using the property is specific to this instance of the control. You can also change the display format for a data field across the entire application by applying the to your data model and setting the named parameter in the constructor. For more information, see [ASP.NET Dynamic Data](http://msdn.microsoft.com/library/78c7fcd7-5f38-46a0-a4bc-48eff3c8a512). ]]> diff --git a/xml/System.Web.DynamicData/DynamicDataExtensions.xml b/xml/System.Web.DynamicData/DynamicDataExtensions.xml index 6a5defedd0152..96646f5bcf510 100644 --- a/xml/System.Web.DynamicData/DynamicDataExtensions.xml +++ b/xml/System.Web.DynamicData/DynamicDataExtensions.xml @@ -491,7 +491,7 @@ class overview. + For more information, see the class overview. ]]> diff --git a/xml/System.Web.DynamicData/DynamicDataManager.xml b/xml/System.Web.DynamicData/DynamicDataManager.xml index 1b24cedc82a37..5a3512ac29540 100644 --- a/xml/System.Web.DynamicData/DynamicDataManager.xml +++ b/xml/System.Web.DynamicData/DynamicDataManager.xml @@ -81,7 +81,7 @@ ## Examples - The following example shows how to use a control to enable dynamic behavior for an instance of the control. + The following example shows how to use a control to enable dynamic behavior for an instance of the control. @@ -330,7 +330,7 @@ ## Examples - The following example shows how to register a control in the `Page_Init` method of an ASP.NET Web page. + The following example shows how to register a control in the `Page_Init` method of an ASP.NET Web page. diff --git a/xml/System.Web.DynamicData/DynamicDataRoute.xml b/xml/System.Web.DynamicData/DynamicDataRoute.xml index e5492f8dbcdc8..33cdcbff64c5c 100644 --- a/xml/System.Web.DynamicData/DynamicDataRoute.xml +++ b/xml/System.Web.DynamicData/DynamicDataRoute.xml @@ -74,7 +74,7 @@ . If you do not set this property when you create an instance of , the route will apply to all actions. + For a list of possible action names, see . If you do not set this property when you create an instance of , the route will apply to all actions. ]]> @@ -223,7 +223,7 @@ property is identical to the property. It is provided as a strongly typed version of the property for coding convenience. + The property is identical to the property. It is provided as a strongly typed version of the property for coding convenience. ]]> diff --git a/xml/System.Web.DynamicData/DynamicField.xml b/xml/System.Web.DynamicData/DynamicField.xml index ce3042aeeafb2..f9ebf2a4ead3c 100644 --- a/xml/System.Web.DynamicData/DynamicField.xml +++ b/xml/System.Web.DynamicData/DynamicField.xml @@ -299,7 +299,7 @@ By default, a object displays null values as empty strings. To display a different value, set the property. > [!NOTE] -> The object of the data source control that the parent control of object is bound to also has a property named . This property performs the same function. Make sure that both properties are set appropriately. +> The object of the data source control that the parent control of object is bound to also has a property named . This property performs the same function. Make sure that both properties are set appropriately. ]]> @@ -456,7 +456,7 @@ By default, the formatting string is applied to the field value only when the data-bound control that contains the object is in read-only mode. To apply the formatting string to the field value while in edit mode, set the property to `true`. - The display format that you specify using the property is specific to this instance of the class. You can also change the display format for a data field across the entire application by applying the to your data model and setting the named parameter in the constructor. For more information, see [ASP.NET Dynamic Data](http://msdn.microsoft.com/library/78c7fcd7-5f38-46a0-a4bc-48eff3c8a512). + The display format that you specify using the property is specific to this instance of the class. You can also change the display format for a data field across the entire application by applying the to your data model and setting the named parameter in the constructor. For more information, see [ASP.NET Dynamic Data](http://msdn.microsoft.com/library/78c7fcd7-5f38-46a0-a4bc-48eff3c8a512). ]]> @@ -712,7 +712,7 @@ property tries to use the value of the property of the column object that is associated with the object by setting the property. + The property tries to use the value of the property of the column object that is associated with the object by setting the property. The method is called to raise a state change event when the property is set. diff --git a/xml/System.Web.DynamicData/DynamicQueryStringParameter.xml b/xml/System.Web.DynamicData/DynamicQueryStringParameter.xml index 55d8adae28784..c23c49aa80c2c 100644 --- a/xml/System.Web.DynamicData/DynamicQueryStringParameter.xml +++ b/xml/System.Web.DynamicData/DynamicQueryStringParameter.xml @@ -24,7 +24,7 @@ For primary keys, you can simply add a object without supplying any other parameters. Dynamic Data will generate the parameters for the primary key or keys. For foreign keys or Boolean columns, you must set the property to the name of the column you want to filter. - In order to use the class, you must add a control to the page and you must register the data-bound control with the control by using the method. + In order to use the class, you must add a control to the page and you must register the data-bound control with the control by using the method. See a run-time code example of this feature: [Run](http://go.microsoft.com/fwlink/?LinkId=120736&sref=System.Web.DynamicData.DynamicQueryStringParameter). diff --git a/xml/System.Web.DynamicData/MetaColumn.xml b/xml/System.Web.DynamicData/MetaColumn.xml index 984e3ff56c48b..6df837dee8170 100644 --- a/xml/System.Web.DynamicData/MetaColumn.xml +++ b/xml/System.Web.DynamicData/MetaColumn.xml @@ -94,7 +94,7 @@ property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not found, this property verifies if a attribute is applied to retrieve formatting information. + The property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not found, this property verifies if a attribute is applied to retrieve formatting information. ]]> @@ -189,7 +189,7 @@ property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not found, this property verifies if a attribute is applied to retrieve formatting information. + The property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not found, this property verifies if a attribute is applied to retrieve formatting information. ]]> @@ -214,7 +214,7 @@ property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not found, this property verifies if a attribute is applied to retrieve formatting information. + The property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not found, this property verifies if a attribute is applied to retrieve formatting information. ]]> @@ -282,7 +282,7 @@ property verifies if a attribute is applied to the data field and retrieves the value of the property. + The property verifies if a attribute is applied to the data field and retrieves the value of the property. ]]> @@ -717,7 +717,7 @@ property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not found, this property verifies if a attribute is applied to retrieve formatting information. + The property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not found, this property verifies if a attribute is applied to retrieve formatting information. ]]> @@ -834,7 +834,7 @@ property indicates whether a data field should be displayed when it is automatically generated by ASP.NET Dynamic Data. This property verifies if a attribute is applied to the data field and returns the value of the property. If a attribute is not applied to the data field, Dynamic Data uses the following rules to determine whether to display the column: + The property indicates whether a data field should be displayed when it is automatically generated by ASP.NET Dynamic Data. This property verifies if a attribute is applied to the data field and returns the value of the property. If a attribute is not applied to the data field, Dynamic Data uses the following rules to determine whether to display the column: - If a attribute is applied to the data field, the data field is displayed. This rule overrides all the other rules. @@ -972,7 +972,7 @@ property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not applied to the data field, the property returns an empty string. + The property verifies if a attribute is applied to the data field and retrieves the value of the property. If a attribute is not applied to the data field, the property returns an empty string. ]]> diff --git a/xml/System.Web.DynamicData/MetaModel.xml b/xml/System.Web.DynamicData/MetaModel.xml index 1afb04f315e34..73983ec64261c 100644 --- a/xml/System.Web.DynamicData/MetaModel.xml +++ b/xml/System.Web.DynamicData/MetaModel.xml @@ -166,7 +166,7 @@ method. + This property provides a simple way to reference the default data-model instance. If the application uses multiple models, you must provide your own way to store references to the additional data models. To find a specific data model, call the method. diff --git a/xml/System.Web.DynamicData/MetaTable.xml b/xml/System.Web.DynamicData/MetaTable.xml index dea4408b75ed5..aedc15eff452b 100644 --- a/xml/System.Web.DynamicData/MetaTable.xml +++ b/xml/System.Web.DynamicData/MetaTable.xml @@ -337,7 +337,7 @@ End Class method. For more information, see the class overview. + The data context is retrieved from a new context that is instantiated by calling the method. For more information, see the class overview. ]]> @@ -460,7 +460,7 @@ End Class class overview. + For more information, see the class overview. ]]> @@ -520,7 +520,7 @@ End Class property. You can customize the value of this property by using the attribute. + The value of this property defaults to the value of the property. You can customize the value of this property by using the attribute. ]]> @@ -573,7 +573,7 @@ End Class class overview. + The action path is a URL for an action for a specific entity. For more information, see the class overview. ]]> @@ -602,7 +602,7 @@ End Class class overview. + The action path is a URL for an action for a specific entity. For more information, see the class overview. ]]> @@ -633,7 +633,7 @@ End Class class overview. + The action path is a URL for an action for a specific entity. For more information, see the class overview. ]]> @@ -666,7 +666,7 @@ End Class ## Remarks The action path is a URL for an action for a specific entity. The action path contains the primary-key column names, which can be used for query-string filters. - For more information, see the class overview. + For more information, see the class overview. ]]> @@ -697,7 +697,7 @@ End Class class overview. + The action path is a URL for an action for a specific entity. For more information, see the class overview. ]]> @@ -730,7 +730,7 @@ End Class class overview. + The action path is a URL for an action for a specific entity. For more information, see the class overview. ]]> @@ -763,7 +763,7 @@ End Class class overview. + The action path is a URL for an action for a specific entity. For more information, see the class overview. ]]> @@ -1052,7 +1052,7 @@ End Function method. + If the `context` parameter is `null`, this method creates a new context by calling the method. ]]> @@ -1224,7 +1224,7 @@ End Sub class overview. + The action path is a URL for an action for a specific entity. For more information, see the class overview. ]]> @@ -1249,7 +1249,7 @@ End Sub class overview. + For more information, see the class overview. ]]> @@ -1416,7 +1416,7 @@ End Sub attribute. + You can specify sort order by using the attribute. ]]> diff --git a/xml/System.Web.Hosting/ApplicationManager.xml b/xml/System.Web.Hosting/ApplicationManager.xml index a10240d0519e5..bc7afd7306863 100644 --- a/xml/System.Web.Hosting/ApplicationManager.xml +++ b/xml/System.Web.Hosting/ApplicationManager.xml @@ -451,7 +451,7 @@ method is equivalent to calling the method in all application domains managed by this instance; however, the method can be called from outside the managed application domains. + Calling the method is equivalent to calling the method in all application domains managed by this instance; however, the method can be called from outside the managed application domains. ]]> @@ -479,7 +479,7 @@ method is equivalent to calling the method for a specific application domain; however, the method can be called from outside managed application domains. + Calling the method is equivalent to calling the method for a specific application domain; however, the method can be called from outside managed application domains. ]]> diff --git a/xml/System.Web.Hosting/HostingEnvironment.xml b/xml/System.Web.Hosting/HostingEnvironment.xml index 16cb4250a38fc..7e40b16ff917e 100644 --- a/xml/System.Web.Hosting/HostingEnvironment.xml +++ b/xml/System.Web.Hosting/HostingEnvironment.xml @@ -614,15 +614,15 @@ To use a registered object, follow these steps: -1. Create a new instance of your registered object by calling the method. +1. Create a new instance of your registered object by calling the method. 2. Call a type-specific method to initialize your new object. In the initialization method, call the method to add the object to the list of registered objects. -3. Call the method to return the registered object when required. +3. Call the method to return the registered object when required. -4. When you wish to stop your object, call the method. The method in turn calls the method. +4. When you wish to stop your object, call the method. The method in turn calls the method. -5. In the method, have your object call the method. +5. In the method, have your object call the method. diff --git a/xml/System.Web.Hosting/IRegisteredObject.xml b/xml/System.Web.Hosting/IRegisteredObject.xml index 147b5c8d55e5f..8e36b59743ac2 100644 --- a/xml/System.Web.Hosting/IRegisteredObject.xml +++ b/xml/System.Web.Hosting/IRegisteredObject.xml @@ -15,7 +15,7 @@ ## Remarks Objects must implement the interface in order to register with the hosting environment and have their lifetime managed by the hosting environment. - You can create an instance of a registered object by calling the method on the application manager. The application manager returns the newly created object to the caller, which can then call a type-specific method on the object. During startup, the registered object should call the method to complete registration of the object. + You can create an instance of a registered object by calling the method on the application manager. The application manager returns the newly created object to the caller, which can then call a type-specific method on the object. During startup, the registered object should call the method to complete registration of the object. When the application manager needs to stop a registered object, it will call the method. @@ -48,7 +48,7 @@ method to ask a registered object to unregister. During processing of the method, the registered object must call the method. + The application manager will call the method to ask a registered object to unregister. During processing of the method, the registered object must call the method. The method is first called with the `immediate` parameter set to `false`. The object can either complete processing, call the method, and then return or it can return immediately and complete processing asynchronously before calling the method. diff --git a/xml/System.Web.Hosting/VirtualPathProvider.xml b/xml/System.Web.Hosting/VirtualPathProvider.xml index 7b44779dd7312..361d88a22e46c 100644 --- a/xml/System.Web.Hosting/VirtualPathProvider.xml +++ b/xml/System.Web.Hosting/VirtualPathProvider.xml @@ -44,7 +44,7 @@ > If a Web site is precompiled for deployment, content provided by a instance is not compiled, and no instances are used by the precompiled site. ## Registering a VirtualPathProvider - A custom instance should be registered with the ASP.NET compilation system by using the method before any page parsing or compilation is performed by the Web application. + A custom instance should be registered with the ASP.NET compilation system by using the method before any page parsing or compilation is performed by the Web application. Typically, a instance is registered in an `AppInitialize` method defined in the `App_Code` directory, or during the `Application_Start` event in the `Global.asax` file. For an example of registering a instance in an `AppInitialize` method, see the Example section. diff --git a/xml/System.Web.Management/SqlWebEventProvider.xml b/xml/System.Web.Management/SqlWebEventProvider.xml index 6e35a104f0e05..c731c054dc8bd 100644 --- a/xml/System.Web.Management/SqlWebEventProvider.xml +++ b/xml/System.Web.Management/SqlWebEventProvider.xml @@ -16,7 +16,7 @@ namespace contains the health event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. + ASP.NET health monitoring allows production and operations staff to manage deployed Web applications. The namespace contains the health event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. This provider has a comprehensive set of configuration attributes that you can use to customize its behavior. diff --git a/xml/System.Web.Management/TemplatedMailWebEventProvider.xml b/xml/System.Web.Management/TemplatedMailWebEventProvider.xml index 8ba07f0544f1e..e945ce88cca84 100644 --- a/xml/System.Web.Management/TemplatedMailWebEventProvider.xml +++ b/xml/System.Web.Management/TemplatedMailWebEventProvider.xml @@ -16,9 +16,9 @@ namespace contains the health event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. + ASP.NET health monitoring allows production and operations staff to manage deployed Web applications. The namespace contains the health event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. - This class is not intended to be used from your code. It is created, configured, and used by the ASP.NET health-monitoring system to send event notifications by e-mail. You can define an e-mail Web event provider in a configuration file, as demonstrated in the Example section of this topic. In addition, you can configure the providers section programmatically by accessing the property. + This class is not intended to be used from your code. It is created, configured, and used by the ASP.NET health-monitoring system to send event notifications by e-mail. You can define an e-mail Web event provider in a configuration file, as demonstrated in the Example section of this topic. In addition, you can configure the providers section programmatically by accessing the property. The e-mail this class produces is defined and formatted using a template. This template consists of markup code defined in a standard .aspx file that outputs the text for the message body. The event information used by the template is provided by a object that is available from the static property of this class. diff --git a/xml/System.Web.Management/TraceWebEventProvider.xml b/xml/System.Web.Management/TraceWebEventProvider.xml index 325f6a9226c74..129707782afd6 100644 --- a/xml/System.Web.Management/TraceWebEventProvider.xml +++ b/xml/System.Web.Management/TraceWebEventProvider.xml @@ -16,7 +16,7 @@ namespace contains the health event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. + ASP.NET health monitoring allows production and operations staff to manage deployed Web applications. The namespace contains the health event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. This provider passes events to the object. It passes events that derive from the class as trace errors and passes all other events as trace information. diff --git a/xml/System.Web.Management/WebApplicationInformation.xml b/xml/System.Web.Management/WebApplicationInformation.xml index e1e0195598f07..a51562cb14bc1 100644 --- a/xml/System.Web.Management/WebApplicationInformation.xml +++ b/xml/System.Web.Management/WebApplicationInformation.xml @@ -16,7 +16,7 @@ namespace contains the health-event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. + ASP.NET health monitoring allows production and operations staff to manage deployed Web applications. The namespace contains the health-event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. Instances of the class contain information that is obtained using any of the types derived from the type. diff --git a/xml/System.Web.Management/WebFailureAuditEvent.xml b/xml/System.Web.Management/WebFailureAuditEvent.xml index d28c01888ad19..a3c88a25b143f 100644 --- a/xml/System.Web.Management/WebFailureAuditEvent.xml +++ b/xml/System.Web.Management/WebFailureAuditEvent.xml @@ -16,7 +16,7 @@ namespace contains the health event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. + ASP.NET health monitoring allows production and operations staff to manage deployed Web applications. The namespace contains the health event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. The class is used when a security operation fails. An example of this is a failed URL authorization for a Web request. diff --git a/xml/System.Web.Management/WebManagementEvent.xml b/xml/System.Web.Management/WebManagementEvent.xml index ccd1e1b1e1048..388faf396cf6a 100644 --- a/xml/System.Web.Management/WebManagementEvent.xml +++ b/xml/System.Web.Management/WebManagementEvent.xml @@ -16,7 +16,7 @@ namespace contains the health-event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. + ASP.NET health monitoring allows production and operations staff to manage deployed Web applications. The namespace contains the health-event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. The is the base class for all the ASP.NET health-monitoring event types. It uses the class to obtain process information that is available to its derived classes. diff --git a/xml/System.Web.Management/WebViewStateFailureAuditEvent.xml b/xml/System.Web.Management/WebViewStateFailureAuditEvent.xml index 11d0701598490..c4f0ff80a5381 100644 --- a/xml/System.Web.Management/WebViewStateFailureAuditEvent.xml +++ b/xml/System.Web.Management/WebViewStateFailureAuditEvent.xml @@ -16,7 +16,7 @@ namespace contains the health-event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. + ASP.NET health monitoring allows production and operations staff to manage deployed Web applications. The namespace contains the health-event types responsible for packaging application health-status data and the provider types responsible for processing this data. It also contains supporting types that help during the management of health events. ASP.NET raises events of type when a view-state failure occurs. This failure indicates either an attempt to tamper with view state or its reuse from another machine with a different key. The related audit event code is . diff --git a/xml/System.Web.Mobile/DeviceFilterElementCollection.xml b/xml/System.Web.Mobile/DeviceFilterElementCollection.xml index ac8c439ec7677..0cb1746c81dd1 100644 --- a/xml/System.Web.Mobile/DeviceFilterElementCollection.xml +++ b/xml/System.Web.Mobile/DeviceFilterElementCollection.xml @@ -241,7 +241,7 @@ property can only get an item. To set an item, use the property, which can both set and get an item. + The property can only get an item. To set an item, use the property, which can both set and get an item. ]]> @@ -308,7 +308,7 @@ method with the key as the argument. + This overload gets the key from the object referenced by the `deviceFilter` parameter and then calls the method with the key as the argument. ]]> diff --git a/xml/System.Web.ModelBinding/MutableObjectModelBinder.xml b/xml/System.Web.ModelBinding/MutableObjectModelBinder.xml index fd328bf23c283..7bd4a7fb56de1 100644 --- a/xml/System.Web.ModelBinding/MutableObjectModelBinder.xml +++ b/xml/System.Web.ModelBinding/MutableObjectModelBinder.xml @@ -84,7 +84,7 @@ property value is `false`. If a property's property value is `true`, the property can be updated if it is not a value type, a string, or an array. + A property can be updated if its property value is `false`. If a property's property value is `true`, the property can be updated if it is not a value type, a string, or an array. ]]> diff --git a/xml/System.Web.Profile/ProfileAutoSaveEventArgs.xml b/xml/System.Web.Profile/ProfileAutoSaveEventArgs.xml index 81ec7dd0bd6cf..ed4f0e0fa8f1e 100644 --- a/xml/System.Web.Profile/ProfileAutoSaveEventArgs.xml +++ b/xml/System.Web.Profile/ProfileAutoSaveEventArgs.xml @@ -16,7 +16,7 @@ delegate is defined for the event of the class. You can access the event of the class in the Global.asax file for your ASP.NET application, as shown in the example for this topic. The event is raised at the end of page execution if the property is `true`. + The delegate is defined for the event of the class. You can access the event of the class in the Global.asax file for your ASP.NET application, as shown in the example for this topic. The event is raised at the end of page execution if the property is `true`. The method automatically determines whether properties that are made up of primitive types, strings, or objects have been changed, by checking the property value for each in the user profile. The method cannot explicitly determine whether a custom class has changed. You can use the event to determine whether a custom object has been modified and then either continue with the automatic save if the object has been modified or cancel the automatic save if the object has not been modified. diff --git a/xml/System.Web.Profile/ProfileEventArgs.xml b/xml/System.Web.Profile/ProfileEventArgs.xml index 3a1f8265d3930..2dd812c49b012 100644 --- a/xml/System.Web.Profile/ProfileEventArgs.xml +++ b/xml/System.Web.Profile/ProfileEventArgs.xml @@ -102,7 +102,7 @@ You can use the property during the event to specify a custom user profile. If, when the event completes, the parameter of the has its property set to a value that’s not `null`, then the uses the value of the property in the current . > [!NOTE] -> The does not set the property for the event. The only gets the value of the property when the code in the event completes. If the property is not explicitly set by application code during the event, the property value will be `null`. +> The does not set the property for the event. The only gets the value of the property when the code in the event completes. If the property is not explicitly set by application code during the event, the property value will be `null`. diff --git a/xml/System.Web.Profile/ProfileGroupBase.xml b/xml/System.Web.Profile/ProfileGroupBase.xml index 41957f65d65b9..0fcef7ae63f0c 100644 --- a/xml/System.Web.Profile/ProfileGroupBase.xml +++ b/xml/System.Web.Profile/ProfileGroupBase.xml @@ -284,7 +284,7 @@ and must be cast as the specific object type when retrieved. For strongly typed access to profile property values, you can access the property by name as a member of a group of the property, for example, `Profile.Address.City`. + You can use this property to retrieve or set grouped property values of the user profile for your application. Returned values are typed as and must be cast as the specific object type when retrieved. For strongly typed access to profile property values, you can access the property by name as a member of a group of the property, for example, `Profile.Address.City`. diff --git a/xml/System.Web.Profile/ProfileInfo.xml b/xml/System.Web.Profile/ProfileInfo.xml index 272b037ab6266..5f8a571fc6f3a 100644 --- a/xml/System.Web.Profile/ProfileInfo.xml +++ b/xml/System.Web.Profile/ProfileInfo.xml @@ -45,7 +45,7 @@ constructor is not intended to be used from your code. Instead, use the . + This constructor is not intended to be used from your code. Instead, use the . objects are constructed and returned as part of a by the , , , and methods of a . diff --git a/xml/System.Web.Profile/ProfileInfoCollection.xml b/xml/System.Web.Profile/ProfileInfoCollection.xml index 7222c5bd4d5fc..baff2516f56d6 100644 --- a/xml/System.Web.Profile/ProfileInfoCollection.xml +++ b/xml/System.Web.Profile/ProfileInfoCollection.xml @@ -147,7 +147,7 @@ to copy objects to the specified . + This method uses to copy objects to the specified . ]]> @@ -177,7 +177,7 @@ to copy objects to the specified array. + This method uses to copy objects to the specified array. ]]> diff --git a/xml/System.Web.Profile/ProfileManager.xml b/xml/System.Web.Profile/ProfileManager.xml index 051285d1d309c..0698845c1899e 100644 --- a/xml/System.Web.Profile/ProfileManager.xml +++ b/xml/System.Web.Profile/ProfileManager.xml @@ -120,7 +120,7 @@ If a value is not specified for the `applicationName` attribute in the configuration file for the Web application, then the profile providers included with the .NET Framework use the property value for ASP.NET applications. For non-ASP.NET applications, the default value is the property value, without the file extension. - The property exposes the property of the default profile provider. The default profile provider is specified using the `defaultProvider` attribute of the configuration element. If the user profile contains properties that are managed by a profile provider other than the default provider, they may be configured with a different application name. To access the application name of a profile provider other than the default provider, obtain a reference to the profile provider using the property and access the property of the provider directly. + The property exposes the property of the default profile provider. The default profile provider is specified using the `defaultProvider` attribute of the configuration element. If the user profile contains properties that are managed by a profile provider other than the default provider, they may be configured with a different application name. To access the application name of a profile provider other than the default provider, obtain a reference to the profile provider using the property and access the property of the provider directly. > [!CAUTION] > Because a single default profile provider instance is used for all of the requests served by an object, you can have multiple requests executing concurrently and attempting to set the property value. The property is not thread safe for multiple writes, and changing the property value can result in unexpected behavior for multiple users of an application. It is recommended that you avoid writing code that allows users to set the property unless you require it. An example of an application where setting the property may be required is an administrative application that manages profile data for multiple applications. Such an application should be a single-user application and not a Web application. @@ -369,7 +369,7 @@ Note that the return value may differ from the value for the supplied . This indicates that some of the profiles in the specified were already deleted from the data store. - The method calls the method of the default profile provider. The default profile provider is specified using the `defaultProvider` attribute of the configuration element. If the user profile contains properties that are managed by a profile provider other than the default provider, they are not deleted. To delete profile properties that are managed by a profile provider other than the default provider, obtain a reference to the profile provider using the property and call the method of the provider directly. + The method calls the method of the default profile provider. The default profile provider is specified using the `defaultProvider` attribute of the configuration element. If the user profile contains properties that are managed by a profile provider other than the default provider, they are not deleted. To delete profile properties that are managed by a profile provider other than the default provider, obtain a reference to the profile provider using the property and call the method of the provider directly. @@ -474,7 +474,7 @@ > [!NOTE] > Your profile provider may support wildcard characters in the `usernameToMatch` parameter. For example, the method of the class supports wildcard characters in the `usernameToMatch` parameter. - The method calls the method of the default profile provider. The default profile provider is specified using the `defaultProvider` attribute of the configuration element. If the user profile contains properties that are managed by a profile provider other than the default provider, the data source for the other profile provider is not searched. To find inactive profiles that are managed by a profile provider other than the default provider, obtain a reference to the profile provider using the property and call the method of the provider directly. + The method calls the method of the default profile provider. The default profile provider is specified using the `defaultProvider` attribute of the configuration element. If the user profile contains properties that are managed by a profile provider other than the default provider, the data source for the other profile provider is not searched. To find inactive profiles that are managed by a profile provider other than the default provider, obtain a reference to the profile provider using the property and call the method of the provider directly. diff --git a/xml/System.Web.Profile/ProfileModule.xml b/xml/System.Web.Profile/ProfileModule.xml index fd835aeb24025..acb2474023c26 100644 --- a/xml/System.Web.Profile/ProfileModule.xml +++ b/xml/System.Web.Profile/ProfileModule.xml @@ -223,9 +223,9 @@ event is raised during the event. You can access the event of the class in the Global.asax file for your ASP.NET application using the `Profile_Personalize` global event as shown in the example for this topic. + The event is raised during the event. You can access the event of the class in the Global.asax file for your ASP.NET application using the `Profile_Personalize` global event as shown in the example for this topic. - You can use the event to specify a custom user profile. If the property value specified for the event handler for the event is set to a value that is not `null` when the event ends, then the will use the specified value of the property as the value of the property of the current . + You can use the event to specify a custom user profile. If the property value specified for the event handler for the event is set to a value that is not `null` when the event ends, then the will use the specified value of the property as the value of the property of the current . @@ -257,9 +257,9 @@ event is raised at the end of page execution if the property is `true`. You can access the event of the class in the Global.asax file for your ASP.NET application using the `Profile_ProfileAutoSaving` global event, as shown in the example for this topic. + The event is raised at the end of page execution if the property is `true`. You can access the event of the class in the Global.asax file for your ASP.NET application using the `Profile_ProfileAutoSaving` global event, as shown in the example for this topic. - The method checks the property value for each in the user profile to determine whether properties that are made up of primitive types, strings, or objects have been changed. The method cannot explicitly determine whether a custom class has changed. You can use the event to determine whether a custom object has been changed and then either to continue with the automatic save for modified objects or to cancel the automatic save if no objects have been modified. + The method checks the property value for each in the user profile to determine whether properties that are made up of primitive types, strings, or objects have been changed. The method cannot explicitly determine whether a custom class has changed. You can use the event to determine whether a custom object has been changed and then either to continue with the automatic save for modified objects or to cancel the automatic save if no objects have been modified. To cancel the automatic profile save operation, set the property to `false` in the event; otherwise, set the property to `true`. diff --git a/xml/System.Web.RegularExpressions/TagRegex.xml b/xml/System.Web.RegularExpressions/TagRegex.xml index 4bacfb73197be..1f2bab4863938 100644 --- a/xml/System.Web.RegularExpressions/TagRegex.xml +++ b/xml/System.Web.RegularExpressions/TagRegex.xml @@ -16,7 +16,7 @@ class provides a regular expression that ASP.NET uses internally to parse the opening tag of an HTML element, an XML element, or an ASP.NET Web server control tag, for applications that target the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)] or later versions. ASP.NET uses the class for applications that target the [!INCLUDE[net_v35_short](~/includes/net-v35-short-md.md)] and earlier versions. + The class provides a regular expression that ASP.NET uses internally to parse the opening tag of an HTML element, an XML element, or an ASP.NET Web server control tag, for applications that target the [!INCLUDE[net_v40_long](~/includes/net-v40-long-md.md)] or later versions. ASP.NET uses the class for applications that target the [!INCLUDE[net_v35_short](~/includes/net-v35-short-md.md)] and earlier versions. > [!NOTE] > The classes are used internally by the .NET Framework to parse ASP.NET pages. diff --git a/xml/System.Web.RegularExpressions/TagRegex35.xml b/xml/System.Web.RegularExpressions/TagRegex35.xml index 2d67a2814d5ac..2b241152ca26a 100644 --- a/xml/System.Web.RegularExpressions/TagRegex35.xml +++ b/xml/System.Web.RegularExpressions/TagRegex35.xml @@ -16,7 +16,7 @@ class provides a regular expression that ASP.NET uses internally to parse the opening tag of an HTML element, an XML element, or an ASP.NET Web server control tag, for applications that target the [!INCLUDE[net_v35SP1_short](~/includes/net-v35sp1-short-md.md)] and earlier versions. ASP.NET uses the class for applications that target the [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)] and later versions. + The class provides a regular expression that ASP.NET uses internally to parse the opening tag of an HTML element, an XML element, or an ASP.NET Web server control tag, for applications that target the [!INCLUDE[net_v35SP1_short](~/includes/net-v35sp1-short-md.md)] and earlier versions. ASP.NET uses the class for applications that target the [!INCLUDE[net_v40_short](~/includes/net-v40-short-md.md)] and later versions. > [!NOTE] > The classes are used internally by the .NET Framework to parse ASP.NET pages. diff --git a/xml/System.Web.Routing/PageRouteHandler.xml b/xml/System.Web.Routing/PageRouteHandler.xml index 82259aca0d0e5..434f329708d17 100644 --- a/xml/System.Web.Routing/PageRouteHandler.xml +++ b/xml/System.Web.Routing/PageRouteHandler.xml @@ -210,7 +210,7 @@ property in the constructor or in the constructor. + You set the property in the constructor or in the constructor. ]]> diff --git a/xml/System.Web.Routing/RequestContext.xml b/xml/System.Web.Routing/RequestContext.xml index c1d2e9d8161e1..71d06b1e126d1 100644 --- a/xml/System.Web.Routing/RequestContext.xml +++ b/xml/System.Web.Routing/RequestContext.xml @@ -23,7 +23,7 @@ ## Remarks The class contains information about the HTTP request in the property. It contains information about the route that matched the current request in the property. - When you construct a URL from a route, you pass an instance of the class to the method. + When you construct a URL from a route, you pass an instance of the class to the method. ]]> diff --git a/xml/System.Web.Script.Serialization/JavaScriptSerializer.xml b/xml/System.Web.Script.Serialization/JavaScriptSerializer.xml index a3d3f30c96d18..5d2a8bca69ae5 100644 --- a/xml/System.Web.Script.Serialization/JavaScriptSerializer.xml +++ b/xml/System.Web.Script.Serialization/JavaScriptSerializer.xml @@ -37,8 +37,8 @@ |Primitive numeric (or numeric-compatible) types: , , , , , , , , , and . The culture-invariant string representation is used.|Number| ||Date object, represented in JSON as "\\/Date(number of ticks)\\/". The number of ticks is a positive or negative long value that indicates the number of ticks (milliseconds) that have elapsed since midnight 01 January, 1970 UTC.

The maximum supported date value is (12/31/9999 11:59:59 PM) and the minimum supported date value is (1/1/0001 12:00:00 AM).| |Enumerations of integer type|Integer equivalent of the enumeration value| -|Types that implement or that are not also implementations of or . This includes types such as , , and .|Array that uses JSON array syntax| -|Types that implement or . This includes types such as and .|JavaScript object that uses JSON dictionary syntax| +|Types that implement or that are not also implementations of or . This includes types such as , , and .|Array that uses JSON array syntax| +|Types that implement or . This includes types such as and .|JavaScript object that uses JSON dictionary syntax| |Custom concrete (non-abstract) types that have public instance properties that have get accessors or public instance fields.

Note that public write-only properties, public property or public field attributes marked with , and public indexed properties in these types are ignored.|JavaScript object that uses JSON dictionary syntax. A special metadata property named "__type" is included to ensure correct deserialization. Make sure that public instance properties have get and set accessors to ensure correct deserialization.| ||String representation of a GUID| ||String representation of the return value of | diff --git a/xml/System.Web.Script.Serialization/SimpleTypeResolver.xml b/xml/System.Web.Script.Serialization/SimpleTypeResolver.xml index 7bbaa5fed95eb..3f9c3d9d5723d 100644 --- a/xml/System.Web.Script.Serialization/SimpleTypeResolver.xml +++ b/xml/System.Web.Script.Serialization/SimpleTypeResolver.xml @@ -72,7 +72,7 @@ method calls the method to resolve the type. + The method calls the method to resolve the type. ]]> diff --git a/xml/System.Web.Script.Services/ScriptMethodAttribute.xml b/xml/System.Web.Script.Services/ScriptMethodAttribute.xml index 2418697d28855..bc00b0078cd46 100644 --- a/xml/System.Web.Script.Services/ScriptMethodAttribute.xml +++ b/xml/System.Web.Script.Services/ScriptMethodAttribute.xml @@ -23,7 +23,7 @@ ## Remarks This attribute is used to specify information for methods that can be called from client script. The attribute lets you specify which HTTP verb (GET or POST) can be used to invoke a method. It also lets you specify whether the response is formatted by using either JavaScript Object Notation (JSON) or XML. - The attribute is optional. (However, methods that can be called from client script must have the attribute applied.). If a method is not marked with , the method will be called by using the HTTP POST command and the response will be serialized as JSON. You cannot override this setting from script. + The attribute is optional. (However, methods that can be called from client script must have the attribute applied.). If a method is not marked with , the method will be called by using the HTTP POST command and the response will be serialized as JSON. You cannot override this setting from script. takes only named parameters. The following are the properties of the class that can be used as named parameters: diff --git a/xml/System.Web.Security/ActiveDirectoryMembershipProvider.xml b/xml/System.Web.Security/ActiveDirectoryMembershipProvider.xml index e15c8ca75dacb..c0bc2a1b37a6d 100644 --- a/xml/System.Web.Security/ActiveDirectoryMembershipProvider.xml +++ b/xml/System.Web.Security/ActiveDirectoryMembershipProvider.xml @@ -1939,7 +1939,7 @@ Leading and trailing spaces are trimmed from all parameter values. - You can call the method directly by first obtaining a reference to the instance from the property. + You can call the method directly by first obtaining a reference to the instance from the property. The provider uses a subtree search starting at the search point specified in the connection string. See the class topic for more information about connection strings. diff --git a/xml/System.Web.Security/AuthorizationStoreRoleProvider.xml b/xml/System.Web.Security/AuthorizationStoreRoleProvider.xml index a556a448f4264..cb6b7d6d8f0b0 100644 --- a/xml/System.Web.Security/AuthorizationStoreRoleProvider.xml +++ b/xml/System.Web.Security/AuthorizationStoreRoleProvider.xml @@ -139,7 +139,7 @@ msxml:// method is called by the class to associate one or more users with one or more roles in the authorization-manager data store specified in the ASP.NET application's configuration file (Web.config). This method is called by the , , , and methods of the class. + The method is called by the class to associate one or more users with one or more roles in the authorization-manager data store specified in the ASP.NET application's configuration file (Web.config). This method is called by the , , , and methods of the class. @@ -211,10 +211,10 @@ msxml:// ## Remarks The is used by the to associate users and roles with different authorization-manager applications, which enables multiple ASP.NET applications to use the same authorization-manager policy store to store role information without running into conflicts between duplicate role names. Alternatively, multiple ASP.NET applications can use the same policy store by specifying the same value in the property. The property can be set programmatically, or it can be set declaratively in the application's Web.config file by using the `applicationName` attribute. - If a value is not specified for the `applicationName` attribute in the Web.config file, then the property value for the current object is used. + If a value is not specified for the `applicationName` attribute in the Web.config file, then the property value for the current object is used. > [!NOTE] -> Authorization-manager application names cannot contain the "/" character that is included in the property. As a result, the default value for the property cannot be used as an authorization-manager application name, and in the application's Web.config file, you must always specify an `applicationName` attribute in the `provider` element to configure your instance. +> Authorization-manager application names cannot contain the "/" character that is included in the property. As a result, the default value for the property cannot be used as an authorization-manager application name, and in the application's Web.config file, you must always specify an `applicationName` attribute in the `provider` element to configure your instance. > [!CAUTION] > Because a single default role provider instance is used for all of the requests served by an object, you can have multiple requests executing concurrently and attempting to set the property value. The property is not thread safe for multiple writes, and changing the property value can result in unexpected behavior when there are multiple users of an application. We recommend that you avoid writing code that allows users to set the property unless you must. An example of an application where setting the property may be required is an administrative application that manages role data for multiple applications. Such an application should be a single-user application and not a Web application. @@ -441,7 +441,7 @@ msxml:// ## Examples - The following code example uses the method to get the list of roles for an application and bind the results to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to get the list of roles for an application and bind the results to a control. For an example of a Web.config file that enables role management, see . @@ -489,7 +489,7 @@ msxml:// ## Examples - The following code example uses the method to retrieve a list of roles for a specified user and binds them to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to retrieve a list of roles for a specified user and binds them to a control. For an example of a Web.config file that enables role management, see . @@ -543,7 +543,7 @@ msxml:// ## Examples - The following code example uses the method to get a list of the users in a particular role and bind the results to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to get a list of the users in a particular role and bind the results to a control. For an example of a Web.config file that enables role management, see . @@ -639,7 +639,7 @@ msxml:// method is called by the class and the method of the property to determine whether a user is associated with a role in the authorization-manager data store specified in the ASP.NET application's configuration file (Web.config). + The method is called by the class and the method of the property to determine whether a user is associated with a role in the authorization-manager data store specified in the ASP.NET application's configuration file (Web.config). diff --git a/xml/System.Web.Security/FormsAuthentication.xml b/xml/System.Web.Security/FormsAuthentication.xml index b28f1f55accbd..406a7e086ceb1 100644 --- a/xml/System.Web.Security/FormsAuthentication.xml +++ b/xml/System.Web.Security/FormsAuthentication.xml @@ -916,7 +916,7 @@ The method does not clear the forms-authentication cookie. You can use the method in conjunction with the method to log one user out and allow a different user to log in. - Unlike the method, this method does not end the request by calling . This means that code that follows the method call will run. + Unlike the method, this method does not end the request by calling . This means that code that follows the method call will run. diff --git a/xml/System.Web.Security/FormsAuthenticationModule.xml b/xml/System.Web.Security/FormsAuthenticationModule.xml index d1649af60baad..c7d515a12bd54 100644 --- a/xml/System.Web.Security/FormsAuthenticationModule.xml +++ b/xml/System.Web.Security/FormsAuthenticationModule.xml @@ -20,7 +20,7 @@ sets the current property to an object that represents the user identity for the current request when the authentication is set to in the [authentication Element (ASP.NET Settings Schema)](http://msdn.microsoft.com/en-us/27bc0ba9-f23a-45f3-ae42-dbe7916e3ee2) element of the application's configuration file. + The sets the current property to an object that represents the user identity for the current request when the authentication is set to in the [authentication Element (ASP.NET Settings Schema)](http://msdn.microsoft.com/en-us/27bc0ba9-f23a-45f3-ae42-dbe7916e3ee2) element of the application's configuration file. The exposes an event that enables you to provide a custom object for the property of the current . The event is accessed by specifying a subroutine named **FormsAuthentication_OnAuthenticate** in the Global.asax file for your ASP.NET application. diff --git a/xml/System.Web.Security/MachineKey.xml b/xml/System.Web.Security/MachineKey.xml index 48ee8e2e6cfe6..fb37773f90513 100644 --- a/xml/System.Web.Security/MachineKey.xml +++ b/xml/System.Web.Security/MachineKey.xml @@ -169,7 +169,7 @@ MachineKey.Unprotect(..., "Private message", "Recipient: " + username) When the method is called, the value that is provided for the `purposes` parameter must be the same value that was provided to the method. Otherwise the operation will fail with a exception. - The configuration settings that are required for the option are required for this method even if the property is not set to the option. + The configuration settings that are required for the option are required for this method even if the property is not set to the option. ]]> diff --git a/xml/System.Web.Security/Membership.xml b/xml/System.Web.Security/Membership.xml index b4ab516222efe..bf6db8684ae64 100644 --- a/xml/System.Web.Security/Membership.xml +++ b/xml/System.Web.Security/Membership.xml @@ -1056,7 +1056,7 @@ ## Remarks The method retrieves the user information from the data source and creates a object populated with the returned data. If you use one of the overloads that does not take a `username` parameter, returns the information for the current logged-on membership user. The current logged-on membership user is identified by the of the user in the current . - You can also specify whether you want to update the last-activity date/time stamp for the user being retrieved with the `userIsOnline` parameter. Of the overloads that do not take a `userIsOnline` parameter, implicitly updates the last-activity date/time stamp for the user. and do not. + You can also specify whether you want to update the last-activity date/time stamp for the user being retrieved with the `userIsOnline` parameter. Of the overloads that do not take a `userIsOnline` parameter, implicitly updates the last-activity date/time stamp for the user. and do not. @@ -1136,7 +1136,7 @@ If you use one of the overloads that does not take a `username` parameter, returns the information for the current logged-on membership user. The current logged-on membership user is identified by the of the user in the current . - You can also specify whether you want to update the last-activity date/time stamp for the user being retrieved with the `userIsOnline` parameter. Of the overloads that do not take a `userIsOnline` parameter, implicitly updates the last-activity date/time stamp for the user. and do not. + You can also specify whether you want to update the last-activity date/time stamp for the user being retrieved with the `userIsOnline` parameter. Of the overloads that do not take a `userIsOnline` parameter, implicitly updates the last-activity date/time stamp for the user. and do not. diff --git a/xml/System.Web.Security/MembershipCreateUserException.xml b/xml/System.Web.Security/MembershipCreateUserException.xml index f1f2e60a7bce4..24e5978fad904 100644 --- a/xml/System.Web.Security/MembershipCreateUserException.xml +++ b/xml/System.Web.Security/MembershipCreateUserException.xml @@ -59,12 +59,12 @@ class is thrown by the method when the user is not created. + An instance of the class is thrown by the method when the user is not created. ## Examples - The following code example calls the method to create a new membership user. If the user creation fails, a is thrown. + The following code example calls the method to create a new membership user. If the user creation fails, a is thrown. [!code-csharp[System.Web.Security.MembershipCreateUserException#3](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Web.Security.MembershipCreateUserException/CS/createuser3cs.aspx#3)] [!code-vb[System.Web.Security.MembershipCreateUserException#3](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.Security.MembershipCreateUserException/VB/createuser3vb.aspx#3)] @@ -92,14 +92,14 @@ class is thrown by the method when the user is not created. + The class is thrown by the method when the user is not created. You can use the `message` parameter to set the property of the exception to a meaningful description of the reason for the exception. ## Examples - The following code example calls the method to create a new membership user. If the user creation fails, a is thrown with a message based on the returned by the method. + The following code example calls the method to create a new membership user. If the user creation fails, a is thrown with a message based on the returned by the method. [!code-csharp[System.Web.Security.MembershipCreateUserException#2](~/samples/snippets/csharp/VS_Snippets_WebNet/System.Web.Security.MembershipCreateUserException/CS/createuser2cs.aspx#2)] [!code-vb[System.Web.Security.MembershipCreateUserException#2](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.Security.MembershipCreateUserException/VB/createuser2vb.aspx#2)] @@ -127,7 +127,7 @@ class is thrown by the method when the user is not created. + The class is thrown by the method when the user is not created. The `statusCode` parameter enables you to indicate why the was thrown. The `statusCode` parameter value is exposed by the property. @@ -199,7 +199,7 @@ class is thrown by the method when the user is not created. + An instance of the class is thrown by the method when the user is not created. You can use this overload of the constructor to supply information regarding a caught exception that occurred while the user was being created. diff --git a/xml/System.Web.Security/MembershipProviderCollection.xml b/xml/System.Web.Security/MembershipProviderCollection.xml index 7df4de525facf..5f2073df2b1e7 100644 --- a/xml/System.Web.Security/MembershipProviderCollection.xml +++ b/xml/System.Web.Security/MembershipProviderCollection.xml @@ -116,7 +116,7 @@ to copy role provider objects to the specified array. + This method uses to copy role provider objects to the specified array. diff --git a/xml/System.Web.Security/MembershipUser.xml b/xml/System.Web.Security/MembershipUser.xml index 6e88129f6d366..29b51b90cde7c 100644 --- a/xml/System.Web.Security/MembershipUser.xml +++ b/xml/System.Web.Security/MembershipUser.xml @@ -362,7 +362,7 @@ calls the method of the membership provider referenced by the property to retrieve the password for the membership from the membership data store. + calls the method of the membership provider referenced by the property to retrieve the password for the membership from the membership data store. If is `false`, the membership provider will return an exception. If the provider supports passwords with a of , you will be unable to retrieve the password for the membership user and should consider making use of the method when a user has forgotten his or her password. @@ -413,7 +413,7 @@ calls the method of the membership provider referenced by the property to retrieve the password for the membership user from the membership data store. If a password answer is required and an incorrect password answer is supplied, a is thrown by the membership provider. + calls the method of the membership provider referenced by the property to retrieve the password for the membership user from the membership data store. If a password answer is required and an incorrect password answer is supplied, a is thrown by the membership provider. If is `false`, the membership provider will return an exception. If the provider supports passwords with a of , you will be unable to retrieve the password for the membership user and should consider making use of the method when a user has forgotten his or her password. @@ -489,7 +489,7 @@ ## Remarks Users are most commonly locked out and cannot be validated by the method when the is reached within the . - Users can also be locked out if you use the or overload that accepts a password answer and the number of bad answers entered by the user reaches the within the . + Users can also be locked out if you use the or overload that accepts a password answer and the number of bad answers entered by the user reaches the within the . To set this property to `false` and let the user try to log in again, you can use the method. @@ -598,7 +598,7 @@ ## Remarks Users are most commonly locked out when the is reached within the . - Users can also be locked out if you use the or overload that accepts a password answer and the number of bad answers entered by the user reaches the within the . + Users can also be locked out if you use the or overload that accepts a password answer and the number of bad answers entered by the user reaches the within the . The default value for the property is determined by the membership provider. For example, when a membership user is created using the provider, the property for the user is initially set to 01/01/1754. @@ -785,7 +785,7 @@ calls the method of the membership provider referenced by the property to reset the password for the membership user to a new, automatically generated password. The new password is then returned to the caller. + calls the method of the membership provider referenced by the property to reset the password for the membership user to a new, automatically generated password. The new password is then returned to the caller. If is `false`, the membership provider will return an exception. @@ -830,7 +830,7 @@ calls the method of the membership provider referenced by the property to reset the password for the membership user to a new, automatically generated password. The new password is then returned to the caller. + calls the method of the membership provider referenced by the property to reset the password for the membership user to a new, automatically generated password. The new password is then returned to the caller. If is `false`, the membership provider will return an exception. @@ -896,7 +896,7 @@ ## Remarks Users are most commonly locked out and cannot be validated by the method when the is reached within the . - Users can also be locked out if you use the or overload that accepts a password answer and the number of bad answers entered by the user reaches the value of within the . + Users can also be locked out if you use the or overload that accepts a password answer and the number of bad answers entered by the user reaches the value of within the . Your implementation of this method should set the property to `false`, set the property to the current date, and reset any counters that you use to track the number of failed log in attempts and so forth. diff --git a/xml/System.Web.Security/MembershipUserCollection.xml b/xml/System.Web.Security/MembershipUserCollection.xml index 0b33477230df3..33d1cd750563d 100644 --- a/xml/System.Web.Security/MembershipUserCollection.xml +++ b/xml/System.Web.Security/MembershipUserCollection.xml @@ -25,7 +25,7 @@ is returned from the , , and methods of the class. The objects returned by the , , and methods contain a snapshot of user information in the membership data store. That is, changes to the membership user information in a are not reflected in the membership data store. To modify membership user information in the membership data store, use the , and methods of the class. + A is returned from the , , and methods of the class. The objects returned by the , , and methods contain a snapshot of user information in the membership data store. That is, changes to the membership user information in a are not reflected in the membership data store. To modify membership user information in the membership data store, use the , and methods of the class. > [!NOTE] > If you are not familiar with the membership features of ASP.NET, see [Introduction to Membership](http://msdn.microsoft.com/library/79184d17-f4c7-4c9f-a073-cec4f5543980) before continuing. For a list of other topics related to membership, see [Managing Users by Using Membership](http://msdn.microsoft.com/library/824c3a24-f0af-427c-a652-0d2d1e9397cd). diff --git a/xml/System.Web.Security/RoleProviderCollection.xml b/xml/System.Web.Security/RoleProviderCollection.xml index 924dd3f8d504a..deda78811e946 100644 --- a/xml/System.Web.Security/RoleProviderCollection.xml +++ b/xml/System.Web.Security/RoleProviderCollection.xml @@ -108,7 +108,7 @@ to copy role provider objects to the specified array. + This method uses to copy role provider objects to the specified array. diff --git a/xml/System.Web.Security/Roles.xml b/xml/System.Web.Security/Roles.xml index 2078b8d15df58..1ba48ba2c3fb5 100644 --- a/xml/System.Web.Security/Roles.xml +++ b/xml/System.Web.Security/Roles.xml @@ -67,7 +67,7 @@ If you use the `authorization` section in your application's Web.config file to specify authorization based on roles, users of your application must supply an authenticated user identity. You can authenticate users by using either Windows or Forms authentication. Anonymous users cannot be assigned to a role. Roles can be used independently of, or in conjunction with, the ASP.NET classes. - To verify role membership programmatically, you can use the class or the property with the method, or you can use the property with the method. For sample code that programmatically checks role membership, see the Example section in this topic. + To verify role membership programmatically, you can use the class or the property with the method, or you can use the property with the method. For sample code that programmatically checks role membership, see the Example section in this topic. The class also enables you to create and delete roles and to add users to or remove users from roles. @@ -403,7 +403,7 @@ ## Remarks The property is used by the class to associate users and roles with different applications. This enables multiple applications to use the same data source to store user and role information without running into conflicts between duplicate user names or duplicate role names. Multiple ASP.NET applications can use the same data source by specifying the same value in the property. You can set the property programmatically, or you can set it declaratively in the configuration file for the Web application by using the `applicationName` attribute. - If your Web application is using the class and a value is not specified for the `applicationName` attribute in the configuration file, the property value for the current property is used. + If your Web application is using the class and a value is not specified for the `applicationName` attribute in the configuration file, the property value for the current property is used. > [!CAUTION] > Because a single default role provider instance is used for all of the requests served by an object, you can have multiple requests executing concurrently and attempting to set the property value. The property is not thread safe for multiple writes, and changing the property value can result in unexpected behavior for multiple users of an application. You should avoid writing code to allow users to set the property, unless required. An example of an application where setting the property may be required is an administrative application that manages role data for multiple applications. Such an application should be a single-user application and not a Web application. @@ -1165,12 +1165,12 @@ method calls the method of the default role provider to get a list of all the roles from the data source for an application. Only the roles for the application that is specified in the property are retrieved. + The method calls the method of the default role provider to get a list of all the roles from the data source for an application. Only the roles for the application that is specified in the property are retrieved. ## Examples - The following code example uses the method to get the list of roles for an application and bind the results to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to get the list of roles for an application and bind the results to a control. For an example of a Web.config file that enables role management, see . > [!IMPORTANT] > This example contains a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see [Script Exploits Overview](http://msdn.microsoft.com/library/772c7312-211a-4eb3-8d6e-eec0aa1dcc07). @@ -1203,14 +1203,14 @@ method calls the method of the default role provider to retrieve from the data source the roles that the currently logged-on user is in. The currently logged-on user is identified by the property of the current , or by for non-HTTP hosting environments. If no user is logged on, an exception will be thrown. Only the roles for the application that is specified in the property are retrieved. + The method calls the method of the default role provider to retrieve from the data source the roles that the currently logged-on user is in. The currently logged-on user is identified by the property of the current , or by for non-HTTP hosting environments. If no user is logged on, an exception will be thrown. Only the roles for the application that is specified in the property are retrieved. If is `true`, then the results of the method may be returned from the role cache rather than the specified role provider. ## Examples - The following code example uses the method to retrieve a list of roles for a specified user and bind the returned roles to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to retrieve a list of roles for a specified user and bind the returned roles to a control. For an example of a Web.config file that enables role management, see . @@ -1244,14 +1244,14 @@ method calls the method of the default role provider to retrieve from the data source the roles that the user is in. Only the roles for the application that is specified in the property are retrieved. + The method calls the method of the default role provider to retrieve from the data source the roles that the user is in. Only the roles for the application that is specified in the property are retrieved. If `username` is equal to the current logged-on user and is `true`, the results of the method may be returned from the role cache rather than the specified . ## Examples - The following code example uses the method to retrieve a list of roles for a specified user and bind the returned roles to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to retrieve a list of roles for a specified user and bind the returned roles to a control. For an example of a Web.config file that enables role management, see . @@ -1331,7 +1331,7 @@ method calls the method of the default role provider to determine whether the currently logged-on user is associated with a role from the data source for the application that is specified in the property. The currently logged-on user is identified by the property of the current , or by for non-HTTP hosting environments. If no user is logged on, an exception will be thrown. Only the roles for the application that is specified in the property are retrieved. + The method calls the method of the default role provider to determine whether the currently logged-on user is associated with a role from the data source for the application that is specified in the property. The currently logged-on user is identified by the property of the current , or by for non-HTTP hosting environments. If no user is logged on, an exception will be thrown. Only the roles for the application that is specified in the property are retrieved. If is `true`, then `roleName` may be checked against the roles cache rather than the specified role provider. diff --git a/xml/System.Web.Security/SqlMembershipProvider.xml b/xml/System.Web.Security/SqlMembershipProvider.xml index 01c11d4a599a8..d0a7ba5027a25 100644 --- a/xml/System.Web.Security/SqlMembershipProvider.xml +++ b/xml/System.Web.Security/SqlMembershipProvider.xml @@ -401,7 +401,7 @@ - The `passwordQuestion` parameter is longer than 256 characters. -- The `providerUserKey` parameter set to an object of a type other than . +- The `providerUserKey` parameter set to an object of a type other than . - The `providerUserKey` parameter is a duplicate of an existing user key. diff --git a/xml/System.Web.Security/SqlRoleProvider.xml b/xml/System.Web.Security/SqlRoleProvider.xml index 99c94501c987b..86e69e73480d5 100644 --- a/xml/System.Web.Security/SqlRoleProvider.xml +++ b/xml/System.Web.Security/SqlRoleProvider.xml @@ -210,7 +210,7 @@ ## Remarks The is used by the to associate users and roles with different applications. This enables multiple applications to use the same database to store user and role information without running into conflicts between duplicate user names or role names. Multiple ASP.NET applications can use the same database by specifying the same value in the property. The property can be set programmatically, or it can be set declaratively in the configuration file for the Web application using the `applicationName` attribute. - If a value is not specified for the `applicationName` attribute in the configuration file for the Web application, then the property value for the current object is used. + If a value is not specified for the `applicationName` attribute in the configuration file for the Web application, then the property value for the current object is used. > [!CAUTION] > Because a single default role provider instance is used for all of the requests served by an object, you can have multiple requests executing concurrently and attempting to set the property value. The property is not thread safe for multiple writes, and changing the property value can result in unexpected behavior for multiple users of an application. It is recommended that you avoid writing code that allows users to set the property unless you must. An example of an application where setting the property may be required is an administrative application that manages role data for multiple applications. Such an application should be a single-user application and not a Web application. @@ -450,7 +450,7 @@ ## Examples - The following code example uses the method to get the list of roles for an application and bind the results to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to get the list of roles for an application and bind the results to a control. For an example of a Web.config file that enables role management, see . > [!IMPORTANT] > This example contains a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see [Script Exploits Overview](http://msdn.microsoft.com/library/772c7312-211a-4eb3-8d6e-eec0aa1dcc07). @@ -491,7 +491,7 @@ ## Examples - The following code example uses the method to retrieve a list of roles for a specified user and binds them to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to retrieve a list of roles for a specified user and binds them to a control. For an example of a Web.config file that enables role management, see . @@ -537,7 +537,7 @@ ## Examples - The following code example uses the method to get a list of the users in a particular role and bind the results to a control. For an example of a Web.config file that enables role management, see . + The following code example uses the method to get a list of the users in a particular role and bind the results to a control. For an example of a Web.config file that enables role management, see . @@ -628,7 +628,7 @@ method is called by the class and the method of the property to determine whether a user is associated with a role in the SQL Server database specified in the ASP.NET application's configuration file (Web.config). + The method is called by the class and the method of the property to determine whether a user is associated with a role in the SQL Server database specified in the ASP.NET application's configuration file (Web.config). diff --git a/xml/System.Web.Security/WindowsTokenRoleProvider.xml b/xml/System.Web.Security/WindowsTokenRoleProvider.xml index 4a996a5194143..ffec3c13f66fd 100644 --- a/xml/System.Web.Security/WindowsTokenRoleProvider.xml +++ b/xml/System.Web.Security/WindowsTokenRoleProvider.xml @@ -273,7 +273,7 @@ class to retrieve from the Windows operating system a list of the Windows groups that the specified user is in. The method can be called only for the currently logged-on user, as identified by the LOGON_USER server variable. If the value supplied in the `username` parameter is not the name of the currently logged-on user, a is thrown. + This method is called by the class to retrieve from the Windows operating system a list of the Windows groups that the specified user is in. The method can be called only for the currently logged-on user, as identified by the LOGON_USER server variable. If the value supplied in the `username` parameter is not the name of the currently logged-on user, a is thrown. For more information an ASP.NET and Windows authentication, see [ASP.NET Authentication](http://msdn.microsoft.com/library/fc10b0ef-4ce4-4a7f-9174-886325221ee1). diff --git a/xml/System.Web.Services.Description/ServiceDescriptionImporter.xml b/xml/System.Web.Services.Description/ServiceDescriptionImporter.xml index 2944440c6df6e..09c2ca0374f43 100644 --- a/xml/System.Web.Services.Description/ServiceDescriptionImporter.xml +++ b/xml/System.Web.Services.Description/ServiceDescriptionImporter.xml @@ -19,7 +19,7 @@ ## Remarks The interface to an XML Web service is typically described by a Web Services Description Language (WSDL) file. For example, to obtain a WSDL description of a Web service using ASP.NET exposed at `http://localhost/service.asmx`, simply navigate to `http://localhost/service.asmx?WSDL`. - The class allows you to easily import the information contained in a WSDL description into a object. By adjusting the value of the parameter, you can instruct a instance either to generate a client proxy class that provides the functionality of the Web service by transparently calling it or to generate an abstract class that encapsulates the functionality of the Web service without implementing it. + The class allows you to easily import the information contained in a WSDL description into a object. By adjusting the value of the parameter, you can instruct a instance either to generate a client proxy class that provides the functionality of the Web service by transparently calling it or to generate an abstract class that encapsulates the functionality of the Web service without implementing it. The code in the resulting object can then either be called directly or exported in the language of your choice. diff --git a/xml/System.Web.Services.Discovery/DiscoveryClientProtocol+DiscoveryClientResultsFile.xml b/xml/System.Web.Services.Discovery/DiscoveryClientProtocol+DiscoveryClientResultsFile.xml index 3b85dab07bf19..a061fe2da6b64 100644 --- a/xml/System.Web.Services.Discovery/DiscoveryClientProtocol+DiscoveryClientResultsFile.xml +++ b/xml/System.Web.Services.Discovery/DiscoveryClientProtocol+DiscoveryClientResultsFile.xml @@ -17,7 +17,7 @@ method, all resolved discovery documents and a file containing a map of all those files are saved to a directory. The map file is described in XML with the root element being ; this class is passed to the class to serialize the results. + When you invoke the method, all resolved discovery documents and a file containing a map of all those files are saved to a directory. The map file is described in XML with the root element being ; this class is passed to the class to serialize the results. diff --git a/xml/System.Web.Services.Discovery/DiscoveryReference.xml b/xml/System.Web.Services.Discovery/DiscoveryReference.xml index ff2c775468cb9..fd73973848236 100644 --- a/xml/System.Web.Services.Discovery/DiscoveryReference.xml +++ b/xml/System.Web.Services.Discovery/DiscoveryReference.xml @@ -160,7 +160,7 @@ . However, the underlying type varies, depending on the type of document referenced. For instance, a passed into returns an instance of . + The return value is always an . However, the underlying type varies, depending on the type of document referenced. For instance, a passed into returns an instance of . diff --git a/xml/System.Web.Services.Discovery/DiscoverySearchPattern.xml b/xml/System.Web.Services.Discovery/DiscoverySearchPattern.xml index c9ebaa9387dc0..22f2a66a89df7 100644 --- a/xml/System.Web.Services.Discovery/DiscoverySearchPattern.xml +++ b/xml/System.Web.Services.Discovery/DiscoverySearchPattern.xml @@ -17,7 +17,7 @@ property to add a discoverable file type to a Web services document. While a discovery document is usually serialized as a file using a .disco extension, you can add multiple files to the property, and those files can have other extensions, represented by implementations of . + You can use the property to add a discoverable file type to a Web services document. While a discovery document is usually serialized as a file using a .disco extension, you can add multiple files to the property, and those files can have other extensions, represented by implementations of . The class and its concrete derived classes are employed by the class's method, which handles an HTTP request for a discovery document. Normally, none of these classes need to be used directly by a developer. diff --git a/xml/System.Web.Services.Protocols/Soap12FaultCodes.xml b/xml/System.Web.Services.Protocols/Soap12FaultCodes.xml index 086a88de63f5d..7814e15a010b6 100644 --- a/xml/System.Web.Services.Protocols/Soap12FaultCodes.xml +++ b/xml/System.Web.Services.Protocols/Soap12FaultCodes.xml @@ -19,9 +19,9 @@ ## Remarks A SOAP fault in version 1.2 of the SOAP specification contains a `Code` element and among other things an optional `Subcode` element. -The `Code` element is one of a pre-defined set of codes that informs a recipient that the cause of the error fell into one of five large error categories. Those five fault codes are represented by the , , , , and fields. +The `Code` element is one of a pre-defined set of codes that informs a recipient that the cause of the error fell into one of five large error categories. Those five fault codes are represented by the , , , , and fields. -The `Subcode` element allows the sender of the SOAP fault to provide an application-specific error code. ASP.NET defines four such codes that are represented by the , , , and fields. +The `Subcode` element allows the sender of the SOAP fault to provide an application-specific error code. ASP.NET defines four such codes that are represented by the , , , and fields. An XML Web service throwing an exception sets the property, which represents the `Code` element, when a new instance of the or class is created. That error is transmitted over the wire as a SOAP fault, which a .NET Framework client can catch as a or . @@ -91,9 +91,9 @@ The `Subcode` element allows the sender of the SOAP fault to provide an applicat with the property set to . + ASP.NET does not automatically throw a with the property set to . - The class has a property of type that represents the SOAP fault subcode. The property represents the URI for the actual SOAP fault subcode. When setting the property to , set the property to . + The class has a property of type that represents the SOAP fault subcode. The property represents the URI for the actual SOAP fault subcode. When setting the property to , set the property to . ]]> @@ -118,9 +118,9 @@ The `Subcode` element allows the sender of the SOAP fault to provide an applicat with the property set to . If the SOAP request resided within a SOAP 1.1 request, the property is set to . + Not all SOAP headers require processing by the recipient. However, if a SOAP header is marked with the `MustUnderstand` attribute equal to "true", processing is required. Failure to process the header when it resides within a SOAP 1.2 request generates a with the property set to . If the SOAP request resided within a SOAP 1.1 request, the property is set to . - Both SOAP 1.1 and 1.2 define `MustUnderstand` SOAP fault codes differing only by the version of the SOAP protocol used to send the SOAP message. This field represents the SOAP 1.2 version, and the SOAP 1.1 version is represented by . The two fields map to different qualified names, but you can check whether the property is either one of the fault codes by calling the method. + Both SOAP 1.1 and 1.2 define `MustUnderstand` SOAP fault codes differing only by the version of the SOAP protocol used to send the SOAP message. This field represents the SOAP 1.2 version, and the SOAP 1.1 version is represented by . The two fields map to different qualified names, but you can check whether the property is either one of the fault codes by calling the method. ]]> @@ -172,9 +172,9 @@ The `Subcode` element allows the sender of the SOAP fault to provide an applicat with the property set to . + ASP.NET does not automatically throw a with the property set to . - The class has a property of type that represents the SOAP fault subcode. The property represents the URI for the actual SOAP fault subcode. When setting the property to , set the property to . + The class has a property of type that represents the SOAP fault subcode. The property represents the URI for the actual SOAP fault subcode. When setting the property to , set the property to . ]]> @@ -199,9 +199,9 @@ The `Subcode` element allows the sender of the SOAP fault to provide an applicat with the property set to . + ASP.NET does not automatically throw a with the property set to . - The class has a property of type that represents the SOAP fault subcode. The property represents the URI for the actual SOAP fault subcode. When setting the property to , set the property to . + The class has a property of type that represents the SOAP fault subcode. The property represents the URI for the actual SOAP fault subcode. When setting the property to , set the property to . ]]> @@ -253,7 +253,7 @@ The `Subcode` element allows the sender of the SOAP fault to provide an applicat is thrown with the property set to when an XML Web service is configured to only accept SOAP 1.2 requests and it receives a SOAP 1.1 message. Likewise, if an XML Web service is configured to accept only SOAP 1.1 messages and it receives a SOAP 1.2 message, a is thrown with the property set to . For details on configuring XML Web services, see [[\]](http://msdn.microsoft.com/en-us/1f0d71bc-8faa-4730-b500-2a6c7b5d4f6b). + A is thrown with the property set to when an XML Web service is configured to only accept SOAP 1.2 requests and it receives a SOAP 1.1 message. Likewise, if an XML Web service is configured to accept only SOAP 1.1 messages and it receives a SOAP 1.2 message, a is thrown with the property set to . For details on configuring XML Web services, see [[\]](http://msdn.microsoft.com/en-us/1f0d71bc-8faa-4730-b500-2a6c7b5d4f6b). Both SOAP 1.1 and 1.2 define `VersionMismatch` SOAP fault codes that differ on the version of the SOAP protocol expected. This field represents the SOAP 1.2 version, whereas the SOAP 1.1 version is represented by . The two fields map to different qualified names, but you can check whether the property is either one of the fault codes by calling the method. diff --git a/xml/System.Web.Services.Protocols/SoapClientMessage.xml b/xml/System.Web.Services.Protocols/SoapClientMessage.xml index 10e1d9a2a81b3..aaa92fa3ef4c9 100644 --- a/xml/System.Web.Services.Protocols/SoapClientMessage.xml +++ b/xml/System.Web.Services.Protocols/SoapClientMessage.xml @@ -17,7 +17,7 @@ passed into the method of the SOAP extension by writing properties of the to the log file. + The following code fragment is part of a SOAP extension that logs the SOAP messages sent and received by an XML Web service client. This specific fragment processes the passed into the method of the SOAP extension by writing properties of the to the log file. [!code-cpp[SoapClientMessage#1](~/samples/snippets/cpp/VS_Snippets_Remoting/SoapClientMessage/CPP/SoapClientMessage.cpp#1)] [!code-csharp[SoapClientMessage#1](~/samples/snippets/csharp/VS_Snippets_Remoting/SoapClientMessage/CS/soapclientmessage.cs#1)] @@ -233,7 +233,7 @@ property. + When an XML Web service supports SOAP version 1.1,.NET Framework clients communicate with an XML Web service in that version by default. For details on how to change the version of the SOAP protocol, see the property. ]]> diff --git a/xml/System.Web.Services.Protocols/SoapException.xml b/xml/System.Web.Services.Protocols/SoapException.xml index 95b7f5fd47b51..e0e2df9204ac9 100644 --- a/xml/System.Web.Services.Protocols/SoapException.xml +++ b/xml/System.Web.Services.Protocols/SoapException.xml @@ -543,7 +543,7 @@ can use this method to determine whether the property is functionally equivalent to the `Client` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `Client` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code `Sender`, which is represented by the field. + Recipients of a can use this method to determine whether the property is functionally equivalent to the `Client` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `Client` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code `Sender`, which is represented by the field. ]]> @@ -574,7 +574,7 @@ can use this method to determine whether the property is functionally equivalent to the `MustUnderstand` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `MustUnderstand` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code the same; however it is scoped by a different XML namespace and is represented by the field. + Recipients of a can use this method to determine whether the property is functionally equivalent to the `MustUnderstand` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `MustUnderstand` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code the same; however it is scoped by a different XML namespace and is represented by the field. ]]> @@ -605,7 +605,7 @@ can use this method to determine whether the property is functionally equivalent to the `Server` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `Server` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code `Receiver`, which is represented by the field. + Recipients of a can use this method to determine whether the property is functionally equivalent to the `Server` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `Server` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code `Receiver`, which is represented by the field. ]]> @@ -636,7 +636,7 @@ can use this method to determine whether the property is functionally equivalent to the `VersionMismatch` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `VersionMismatch` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code the same; however, it is scoped by a different XML namespace and is represented by the field. + Recipients of a can use this method to determine whether the property is functionally equivalent to the `VersionMismatch` SOAP fault code defined in SOAP 1.1 regardless of the version of the SOAP protocol used. Versions of the SOAP protocol later than 1.1 might use different names or namespaces for the `VersionMismatch` SOAP fault code defined in SOAP version 1.1, which is represented by the field. SOAP 1.2 names the fault code the same; however, it is scoped by a different XML namespace and is represented by the field. ]]> diff --git a/xml/System.Web.Services.Protocols/SoapFaultSubCode.xml b/xml/System.Web.Services.Protocols/SoapFaultSubCode.xml index 0d648a7fee99d..fcc2bc32dc43e 100644 --- a/xml/System.Web.Services.Protocols/SoapFaultSubCode.xml +++ b/xml/System.Web.Services.Protocols/SoapFaultSubCode.xml @@ -87,7 +87,7 @@ ## Remarks Use a constructor to set the property. - The value of the property can be any user defined XML qualified name, including the codes represented by the , , , and fields. + The value of the property can be any user defined XML qualified name, including the codes represented by the , , , and fields. ]]> diff --git a/xml/System.Web.Services.Protocols/SoapMessage.xml b/xml/System.Web.Services.Protocols/SoapMessage.xml index b5574b0734708..3edb0d394677c 100644 --- a/xml/System.Web.Services.Protocols/SoapMessage.xml +++ b/xml/System.Web.Services.Protocols/SoapMessage.xml @@ -459,7 +459,7 @@ property of or for details about one-way XML Web service methods. + See the property of or for details about one-way XML Web service methods. The property is accessible in all stages of . @@ -533,7 +533,7 @@ ## Examples - The following code example demonstrates how to determine the within the method. + The following code example demonstrates how to determine the within the method. [!code-cpp[Classic SoapExtension.ProcessMessage Example#1](~/samples/snippets/cpp/VS_Snippets_Remoting/Classic SoapExtension.ProcessMessage Example/CPP/source.cpp#1)] [!code-csharp[Classic SoapExtension.ProcessMessage Example#1](~/samples/snippets/csharp/VS_Snippets_Remoting/Classic SoapExtension.ProcessMessage Example/CS/source.cs#1)] diff --git a/xml/System.Web.Services.Protocols/SoapServerMessage.xml b/xml/System.Web.Services.Protocols/SoapServerMessage.xml index e4bcc0d31755f..8850922e89b27 100644 --- a/xml/System.Web.Services.Protocols/SoapServerMessage.xml +++ b/xml/System.Web.Services.Protocols/SoapServerMessage.xml @@ -16,7 +16,7 @@ passed into the method of the SOAP extension by writing properties of the to the log file. + The following code fragment is part of a SOAP extension that logs the SOAP messages sent and received by an XML Web service method. This specific fragment processes the passed into the method of the SOAP extension by writing properties of the to the log file. diff --git a/xml/System.Web.Services.Protocols/WebClientAsyncResult.xml b/xml/System.Web.Services.Protocols/WebClientAsyncResult.xml index a6703dcab68c6..23dc99b74a9dc 100644 --- a/xml/System.Web.Services.Protocols/WebClientAsyncResult.xml +++ b/xml/System.Web.Services.Protocols/WebClientAsyncResult.xml @@ -49,7 +49,7 @@ method. If the corresponding `End` method is subsequently called after the method, a is thrown, setting the property to . + The XML Web service request is canceled if the underlying transport supports the method. If the corresponding `End` method is subsequently called after the method, a is thrown, setting the property to . ]]> diff --git a/xml/System.Web.Services.Protocols/WebClientProtocol.xml b/xml/System.Web.Services.Protocols/WebClientProtocol.xml index d4a50e88beb86..a6d196734df36 100644 --- a/xml/System.Web.Services.Protocols/WebClientProtocol.xml +++ b/xml/System.Web.Services.Protocols/WebClientProtocol.xml @@ -163,7 +163,7 @@ ## Remarks When using the `Credentials` property, a XML Web service client must instantiate a class implementing , such as , and then set the client credentials specific to the authentication mechanism. The class can be used to set authentication credentials using the basic, digest, NTLM and Kerberos authentication mechanisms. - When the property is set to then the client negotiates with the server to do Kerberos and/or NTLM authentication depending on how the server is configured. + When the property is set to then the client negotiates with the server to do Kerberos and/or NTLM authentication depending on how the server is configured. @@ -393,7 +393,7 @@ property to indicates that the request does not time out. Even though an XML Web service client can set the property to not time out, the Web server can still cause the request to time out on the server side. + Setting the property to indicates that the request does not time out. Even though an XML Web service client can set the property to not time out, the Web server can still cause the request to time out on the server side. diff --git a/xml/System.Web.Services/WebService.xml b/xml/System.Web.Services/WebService.xml index f5045d2e4f11d..ec47816be68cf 100644 --- a/xml/System.Web.Services/WebService.xml +++ b/xml/System.Web.Services/WebService.xml @@ -240,7 +240,7 @@ ## Remarks If the SOAP protocol was not used to communicate with the XML Web service, such as HTTP-GET or HTTP-POST, the value of the property is . - For XML Web services that do not derive from the class, the version of the SOAP protocol used to make the SOAP request to the XML Web service can be also be accessed using the "WebServiceSoapVersion" entry of the property. That entry is of type . + For XML Web services that do not derive from the class, the version of the SOAP protocol used to make the SOAP request to the XML Web service can be also be accessed using the "WebServiceSoapVersion" entry of the property. That entry is of type . ]]> diff --git a/xml/System.Web.SessionState/HttpSessionState.xml b/xml/System.Web.SessionState/HttpSessionState.xml index 1652f421c80f1..519867e7982a6 100644 --- a/xml/System.Web.SessionState/HttpSessionState.xml +++ b/xml/System.Web.SessionState/HttpSessionState.xml @@ -32,7 +32,7 @@ Session values are stored in memory on the Web server, by default. You can also store session values in a SQL Server database, an ASP.NET state server, or a custom server. This enables you to preserve session values in cases where the ASP.NET or IIS process or the ASP.NET application restarts and to make session values available across all the servers in a Web farm. This behavior is configured by setting the `mode` attribute to a valid value in the element of your application configuration. For more information, see [Session-State Modes](http://msdn.microsoft.com/library/0bb0a3a3-650f-4c47-a0c5-b08b9b591bb4). - Alternatives to session state include application state (see the property) and the ASP.NET cache (see the namespace), which store variables that can be accessed by all users of an ASP.NET application; the ASP.NET profile (see the namespace), which persists user values in a data store without expiring them using a time-out; ASP.NET , which persist control values in the ; ; the property; and fields on an HTML form that are available from an HTTP `POST` using the collection. For more details on the differences between session state and other state-management alternatives, see [ASP.NET State Management Recommendations](http://msdn.microsoft.com/library/af79fa0d-4bc8-47a6-9915-d8e355bfb732). + Alternatives to session state include application state (see the property) and the ASP.NET cache (see the namespace), which store variables that can be accessed by all users of an ASP.NET application; the ASP.NET profile (see the namespace), which persists user values in a data store without expiring them using a time-out; ASP.NET , which persist control values in the ; ; the property; and fields on an HTML form that are available from an HTTP `POST` using the collection. For more details on the differences between session state and other state-management alternatives, see [ASP.NET State Management Recommendations](http://msdn.microsoft.com/library/af79fa0d-4bc8-47a6-9915-d8e355bfb732). diff --git a/xml/System.Web.SessionState/ISessionIDManager.xml b/xml/System.Web.SessionState/ISessionIDManager.xml index 1cf8ee29499e5..cf95a963d3ae5 100644 --- a/xml/System.Web.SessionState/ISessionIDManager.xml +++ b/xml/System.Web.SessionState/ISessionIDManager.xml @@ -91,7 +91,7 @@ method is called by the during the and events. If you cannot retrieve a valid session identifier from the HTTP request, return `null`. If the receives `null` from the method, it will call the method to get a new session identifier for a new session. + The method is called by the during the and events. If you cannot retrieve a valid session identifier from the HTTP request, return `null`. If the receives `null` from the method, it will call the method to get a new session identifier for a new session. If it is possible that the value returned by your implementation contains characters that are not valid in an HTTP response or request, you should use the method to encode the session-identifier value in your method implementation and the method to decode the session-identifier value in your method implementation. @@ -197,7 +197,7 @@ calls the method during the event to remove the session identifier from the collection if a new session was created but was not used. + The calls the method during the event to remove the session identifier from the collection if a new session was created but was not used. @@ -239,7 +239,7 @@ method is called by the object during the event. The method stores the session identifier either in the URL (when cookieless session state is used) or in a non-expiring session cookie. + The method is called by the object during the event. The method stores the session identifier either in the URL (when cookieless session state is used) or in a non-expiring session cookie. If it is possible that the value returned from your implementation contains characters that are not valid in an HTTP response or request, you should use the method to encode the session-identifier value in your method implementation and the method to decode the session-identifier value in your method implementation. diff --git a/xml/System.Web.SessionState/ISessionStateItemCollection.xml b/xml/System.Web.SessionState/ISessionStateItemCollection.xml index faa5f6eeed71a..785145db4ea6d 100644 --- a/xml/System.Web.SessionState/ISessionStateItemCollection.xml +++ b/xml/System.Web.SessionState/ISessionStateItemCollection.xml @@ -262,7 +262,7 @@ ## Remarks In implementing the method, you should set the property to `true` to indicatevalues in the implementation have been modified. - Your implementation of the method should throw an exception if `index` is less than zero or is equal to or greater than . + Your implementation of the method should throw an exception if `index` is less than zero or is equal to or greater than . diff --git a/xml/System.Web.SessionState/SessionStateModule.xml b/xml/System.Web.SessionState/SessionStateModule.xml index 2ad7ab11705e8..880f3b54ca5be 100644 --- a/xml/System.Web.SessionState/SessionStateModule.xml +++ b/xml/System.Web.SessionState/SessionStateModule.xml @@ -104,7 +104,7 @@ You can specify a handler for the event by adding a public subroutine named **Session_OnEnd** to the Global.asax file. > [!NOTE] -> The **Session_OnEnd** event is only supported when the session-state property value is , which is the default. If the session-state is set to or , then the **Session_OnEnd** event in the Global.asax file is ignored. If the session state property value is , then support for the **Session_OnEnd** event is determined by the custom session-state store provider. +> The **Session_OnEnd** event is only supported when the session-state property value is , which is the default. If the session-state is set to or , then the **Session_OnEnd** event in the Global.asax file is ignored. If the session state property value is , then support for the **Session_OnEnd** event is determined by the custom session-state store provider. Though the event is public, you can only handle it by adding an event handler in the Global.asax file. This restriction is implemented because instances are reused for performance. When a session expires, only the **Session_OnEnd** event specified in the Global.asax file is executed, to prevent code from calling an event handler associated with an instance that is currently in use. diff --git a/xml/System.Web.SessionState/SessionStateStoreProviderBase.xml b/xml/System.Web.SessionState/SessionStateStoreProviderBase.xml index 822932839c5f9..8e492a9c58b5f 100644 --- a/xml/System.Web.SessionState/SessionStateStoreProviderBase.xml +++ b/xml/System.Web.SessionState/SessionStateStoreProviderBase.xml @@ -198,7 +198,7 @@ method is called when the method executes at the closing of the application domain. Classes that inherit the class can use this method to free any resources no longer in use. + The method is called when the method executes at the closing of the application domain. Classes that inherit the class can use this method to free any resources no longer in use. diff --git a/xml/System.Web.UI.Adapters/ControlAdapter.xml b/xml/System.Web.UI.Adapters/ControlAdapter.xml index 0c60df2b70d81..041f692bc8fe4 100644 --- a/xml/System.Web.UI.Adapters/ControlAdapter.xml +++ b/xml/System.Web.UI.Adapters/ControlAdapter.xml @@ -26,15 +26,15 @@ Controls themselves do not necessarily require an adapter. If controls are extended through composition, generally the child control adapters are sufficient. - Each control has explicit mappings to adapters through the .browser definition files. Thus, any access to the property uses the object extracted from the browser definition files to perform the lookup for the mapping of the adapter to control. + Each control has explicit mappings to adapters through the .browser definition files. Thus, any access to the property uses the object extracted from the browser definition files to perform the lookup for the mapping of the adapter to control. During processing, the .NET Framework intercepts calls to the overridable methods of a control that could be target-specific. If a control adapter is attached, the .NET Framework calls the associated adapter methods. - The adapter performs rendering for the control through the method. If overridden, potentially should not call the base class implementation because that performs a call back on the method. This might cause the rendering to occur twice, once by the adapter and once by the control. + The adapter performs rendering for the control through the method. If overridden, potentially should not call the base class implementation because that performs a call back on the method. This might cause the rendering to occur twice, once by the adapter and once by the control. - The base method calls back on the method of the control. Thus, if you override , you should not call the base class implementation unless the rendering you implement is in addition to that provided by of the control. + The base method calls back on the method of the control. Thus, if you override , you should not call the base class implementation unless the rendering you implement is in addition to that provided by of the control. - You must ensure that the .NET Framework performs interception for adapters of the child controls. You can do this by calling the base method, which calls the method of the control, from your override. + You must ensure that the .NET Framework performs interception for adapters of the child controls. You can do this by calling the base method, which calls the method of the control, from your override. The and methods are called by the control immediately before and after (respectively) the control calls the method. If pre- and post-rendering are the only browser-specific processing tasks required, using and might make it unnecessary to override . The default behavior of the and methods is to call the corresponding methods of the . @@ -214,7 +214,7 @@ object and the method is overridden, the override is called instead of the method. Thus, can be used to create a target-specific child control set. + If there is a derived control adapter attached to a object and the method is overridden, the override is called instead of the method. Thus, can be used to create a target-specific child control set. For more information about combining controls to create a new control, see [Composite Controls](http://msdn.microsoft.com/en-us/fb174677-d845-467c-8bf3-cc096b2490b0). @@ -284,7 +284,7 @@ An adapter might need to maintain control state information when there are features that need to have state maintained across requests, independent from the state of the associated control. For example, a composite control consisting of a large textual display and a group of controls might render as a single view on desktop computer browsers. On other browsers, it might split its rendering—one view for the textual display and the other for the radio button group. The adapter would need to maintain its own target-specific information about the currently active view. - The method is called immediately after the method, in the `LoadState` lifecycle stage. The adapter control state is separate and in addition to the control state of the control. + The method is called immediately after the method, in the `LoadState` lifecycle stage. The adapter control state is separate and in addition to the control state of the control. ]]> @@ -316,7 +316,7 @@ An adapter needs to maintain view state information when there is data that must be maintained across requests, independent from the view state of the associated control. For example, a grid control on desktop computer browsers might render as a single view of rows and columns of values. On other browsers, it might split its rendering into multiple separate views, such as a list of rows and details of a single row. The adapter would need to maintain the data for the views that are not currently active in view state. - The method is called immediately before the method in the `LoadState` lifecycle stage. The adapter view state is separate and in addition to the view state of the control. + The method is called immediately before the method in the `LoadState` lifecycle stage. The adapter view state is separate and in addition to the view state of the control. ]]> @@ -344,7 +344,7 @@ object and the method is overridden, the override method is called instead of the method. + If there is an adapter attached to a object and the method is overridden, the override method is called instead of the method. Override to perform target-specific processing in the `Initialize` stage of the control lifecycle. Typically, these are functions that are performed when a control is created. @@ -386,7 +386,7 @@ object and the method is overridden, the override method is called instead of the method. + If there is an adapter attached to a object and the method is overridden, the override method is called instead of the method. Override the method to perform target-specific processing in the `Load` stage of the control lifecycle. Typically, these are functions that should be performed for each client request. @@ -419,7 +419,7 @@ object and the method is overridden, the override method is called instead of the method. + If there is an adapter attached to a object and the method is overridden, the override method is called instead of the method. Override the method to perform target-specific processing in the `PreRender` stage of the control lifecycle. Typically, these are functions that immediately precede rendering of the control output. @@ -452,7 +452,7 @@ object and the method is overridden, the override method is called instead of the method. + If there is an adapter attached to a object and the method is overridden, the override method is called instead of the method. Override the method to do target-specific processing in the `Unload` stage of the control lifecycle. Typically, these are cleanup functions that precede disposition of the control. @@ -490,7 +490,7 @@ property provides access to the object where the control is situated. + The property provides access to the object where the control is situated. ]]> @@ -523,7 +523,7 @@ property provides access to the object for the object where the object associated with the current object is situated. + The property provides access to the object for the object where the object associated with the current object is situated. The property can be used to access other items at the page adapter level, such as common target-specific functions that could apply to several control types on the page. @@ -553,7 +553,7 @@ method to generate target-specific markup to send to the client browser. The method is called in place of the method if a object is attached to a object. + Override the method to generate target-specific markup to send to the client browser. The method is called in place of the method if a object is attached to a object. ]]> @@ -621,7 +621,7 @@ An adapter might need to maintain control state information when there are features that need to have state maintained across requests, independent from the state of the associated control. For example, a composite control consisting of a large textual display and a group of controls might render as a single view on desktop computer browsers. On other browsers, it might split its rendering—one view for the textual display and the other for the radio button group. The adapter would need to maintain its own target-specific information about the currently active view. - The method is called immediately after the method in the `SaveState` lifecycle stage. The adapter control state is separate and in addition to the control state of the control. + The method is called immediately after the method in the `SaveState` lifecycle stage. The adapter control state is separate and in addition to the control state of the control. ]]> @@ -651,7 +651,7 @@ An adapter needs to maintain view state information when there is data that must be maintained across requests, independent from the associated view state of the control. For example, a grid control on desktop computer browsers might render as a single view of rows and columns of values. On other browsers, it might split its rendering into multiple separate views, such as a list of rows and details of a single row. The adapter would need to maintain the data for the views that are not currently active in view state. - The method is called immediately before the method in the `SaveState` lifecycle stage. The adapter view state is separate and in addition to the view state of the control. + The method is called immediately before the method in the `SaveState` lifecycle stage. The adapter view state is separate and in addition to the view state of the control. ]]> diff --git a/xml/System.Web.UI.Adapters/PageAdapter.xml b/xml/System.Web.UI.Adapters/PageAdapter.xml index 075d0c901c764..e6e167047f9e0 100644 --- a/xml/System.Web.UI.Adapters/PageAdapter.xml +++ b/xml/System.Web.UI.Adapters/PageAdapter.xml @@ -28,7 +28,7 @@ - The method provides a DHTML code fragment that can be used to reference forms in scripts. -- The method returns a collection of the postback variables if the page is in postback. It is called by the .NET Framework instead of the method if a derived page adapter is present. +- The method returns a collection of the postback variables if the page is in postback. It is called by the .NET Framework instead of the method if a derived page adapter is present. - The and methods are used by control adapters to render hyperlinks if a derived page adapter is present. @@ -315,9 +315,9 @@ |Link type|Resulting link| |---------------|--------------------| |Code Entity Reference,cer|| -|Code Entity Reference Qualified, cerq|| +|Code Entity Reference Qualified, cerq|| |Code Entity Reference Specific,cers|| -|Code Entity Reference Qualified Specific, cerqs|| +|Code Entity Reference Qualified Specific, cerqs|| ]]> diff --git a/xml/System.Web.UI.DataVisualization.Charting/CalloutAnnotation.xml b/xml/System.Web.UI.DataVisualization.Charting/CalloutAnnotation.xml index 0f9a986d815de..5d4899640da90 100644 --- a/xml/System.Web.UI.DataVisualization.Charting/CalloutAnnotation.xml +++ b/xml/System.Web.UI.DataVisualization.Charting/CalloutAnnotation.xml @@ -89,7 +89,7 @@ must be anchored using either the or the property, and its property must be set to . + The must be anchored using either the or the property, and its property must be set to . ]]> @@ -122,7 +122,7 @@ must be anchored using either the or the property, and its property must be set to . + The must be anchored using either the or the property, and its property must be set to . ]]> diff --git a/xml/System.Web.UI.DataVisualization.Charting/Chart.xml b/xml/System.Web.UI.DataVisualization.Charting/Chart.xml index 40486f11976e9..99494127d9f96 100644 --- a/xml/System.Web.UI.DataVisualization.Charting/Chart.xml +++ b/xml/System.Web.UI.DataVisualization.Charting/Chart.xml @@ -1138,7 +1138,7 @@ property is set to . + This property has no effect if the property is set to . ]]> @@ -1273,14 +1273,14 @@ These data point properties include: -- -- -- -- -- -- -- -- , which are the names of the custom properties. +- +- +- +- +- +- +- +- , which are the names of the custom properties. ]]> @@ -2048,7 +2048,7 @@ These data point properties include: is set to . + This property has no effect if is set to . When you render a chart image using the image tag method, a chart image is generated and then saved to disk at the server, in a format that is determined by the property. diff --git a/xml/System.Web.UI.DataVisualization.Charting/TickMark.xml b/xml/System.Web.UI.DataVisualization.Charting/TickMark.xml index febf01a2f934a..6eda0cbe380c5 100644 --- a/xml/System.Web.UI.DataVisualization.Charting/TickMark.xml +++ b/xml/System.Web.UI.DataVisualization.Charting/TickMark.xml @@ -136,7 +136,7 @@ To display tick marks for three-dimensional (3D) charts, so that they are just drawn for the width of a wall, set the property to . Then specify a tick mark size of zero (0) using the property. - If the property is set to , tick marks are not displayed. Tick marks can also be toggled on or off by setting the [Tickmark.Enabled]() property to `true` or `false`. + If the property is set to , tick marks are not displayed. Tick marks can also be toggled on or off by setting the [Tickmark.Enabled]() property to `true` or `false`. ]]> diff --git a/xml/System.Web.UI.Design.WebControls.WebParts/WebPartDesigner.xml b/xml/System.Web.UI.Design.WebControls.WebParts/WebPartDesigner.xml index 40b89854089c2..b6b23c93fa48d 100644 --- a/xml/System.Web.UI.Design.WebControls.WebParts/WebPartDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls.WebParts/WebPartDesigner.xml @@ -27,7 +27,7 @@ ## Examples The following code example shows the interaction between a control and its associated . The control contains a control from which the end user selects his or her birthday, a control to submit the selection, and a control to display a message on the user's birthday. The verifies that the associated control is of the expected type and then customizes the design-time rendering of said control. Note that the visual customizations of the designer are visible only at design time, whereas those of the associated control are visible at both run time and design time. - All the methods overridden in this example derive from the base class. For other available members and their use, see . + All the methods overridden in this example derive from the base class. For other available members and their use, see . [!code-csharp[WebPartsDesigners_WebPartDesigner_Overview#1](~/samples/snippets/csharp/VS_Snippets_WebNet/WebPartsDesigners_WebPartDesigner_Overview/CS/BirthdayPart.cs#1)] [!code-vb[WebPartsDesigners_WebPartDesigner_Overview#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/WebPartsDesigners_WebPartDesigner_Overview/vb/birthdaypart.vb#1)] diff --git a/xml/System.Web.UI.Design.WebControls.WebParts/WebPartZoneBaseDesigner.xml b/xml/System.Web.UI.Design.WebControls.WebParts/WebPartZoneBaseDesigner.xml index d1dbf7302ea1f..92e0669def1f5 100644 --- a/xml/System.Web.UI.Design.WebControls.WebParts/WebPartZoneBaseDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls.WebParts/WebPartZoneBaseDesigner.xml @@ -80,7 +80,7 @@ method overrides to hide the property in the designer after calling the parent method. This is because the default control does not render any zone-level verbs. If you wish to render zone-level verbs in a derived class, you must override this method to not hide the property. + The method overrides to hide the property in the designer after calling the parent method. This is because the default control does not render any zone-level verbs. If you wish to render zone-level verbs in a derived class, you must override this method to not hide the property. ]]> diff --git a/xml/System.Web.UI.Design.WebControls/AccessDataSourceDesigner.xml b/xml/System.Web.UI.Design.WebControls/AccessDataSourceDesigner.xml index 5efffe7797f89..e181272354711 100644 --- a/xml/System.Web.UI.Design.WebControls/AccessDataSourceDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/AccessDataSourceDesigner.xml @@ -152,7 +152,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to, or remove them from, the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to, or remove them from, the **Properties** grid. For the control, the method creates the design-time property to shadow the property of the control. diff --git a/xml/System.Web.UI.Design.WebControls/AdRotatorDesigner.xml b/xml/System.Web.UI.Design.WebControls/AdRotatorDesigner.xml index 42ab000231c89..42ca4ea44b528 100644 --- a/xml/System.Web.UI.Design.WebControls/AdRotatorDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/AdRotatorDesigner.xml @@ -62,7 +62,7 @@ method in a templated data-bound control designer, see . + For a code example that shows how to override the method in a templated data-bound control designer, see . If the control that is associated with this designer has templates, it displays the templates in the designer. diff --git a/xml/System.Web.UI.Design.WebControls/BaseDataBoundControlDesigner.xml b/xml/System.Web.UI.Design.WebControls/BaseDataBoundControlDesigner.xml index dd352372c0966..ced5429130d4c 100644 --- a/xml/System.Web.UI.Design.WebControls/BaseDataBoundControlDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/BaseDataBoundControlDesigner.xml @@ -419,7 +419,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add or remove properties from the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add or remove properties from the **Properties** grid. For the class, the shadows the property of the control. It makes a copy of the attribute array of the , and then adds these attributes to the shadowed property. It sets the attribute of the shadowed property to `false` unless the attribute of the property of the control is already set to `true`. diff --git a/xml/System.Web.UI.Design.WebControls/BaseDataListDesigner.xml b/xml/System.Web.UI.Design.WebControls/BaseDataListDesigner.xml index 56855156b05f1..e3beacd2c1ec9 100644 --- a/xml/System.Web.UI.Design.WebControls/BaseDataListDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/BaseDataListDesigner.xml @@ -213,7 +213,7 @@ property causes the property of the associated control to be set. If the is set to a , indicating a new data source is to be defined, a **Create Data Source** dialog box is displayed. If the is set to a indicating there is no data source, the is set to an empty string (""). + Setting the designer's property causes the property of the associated control to be set. If the is set to a , indicating a new data source is to be defined, a **Create Data Source** dialog box is displayed. If the is set to a indicating there is no data source, the is set to an empty string (""). ]]> @@ -301,7 +301,7 @@ method attempts to construct a object from the data source that is defined by the and properties. If this is not possible, it creates a from dummy data. + The method attempts to construct a object from the data source that is defined by the and properties. If this is not possible, it creates a from dummy data. ]]> @@ -335,7 +335,7 @@ method attempts to construct a object from the data source that is specified by the `selectedDataSource` parameter. If this is not possible, it creates a from dummy data. + The method attempts to construct a object from the data source that is specified by the `selectedDataSource` parameter. If this is not possible, it creates a from dummy data. ]]> @@ -387,7 +387,7 @@ method uses the method to construct a data source from the object that is specified by the property of the associated control derived from the class. + The method uses the method to construct a data source from the object that is specified by the property of the associated control derived from the class. ]]> @@ -740,7 +740,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. For controls that are derived from the class, the creates design-time properties to shadow the , , , and properties. diff --git a/xml/System.Web.UI.Design.WebControls/BaseValidatorDesigner.xml b/xml/System.Web.UI.Design.WebControls/BaseValidatorDesigner.xml index 0c40bd410c1c0..4a09b7545d6ce 100644 --- a/xml/System.Web.UI.Design.WebControls/BaseValidatorDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/BaseValidatorDesigner.xml @@ -136,7 +136,7 @@ method to shadow control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the properties grid. + Control designer objects use methods that are derived from the method to shadow control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the properties grid. ]]> diff --git a/xml/System.Web.UI.Design.WebControls/BulletedListDesigner.xml b/xml/System.Web.UI.Design.WebControls/BulletedListDesigner.xml index 5e78e1b68078d..9f2890877e5a6 100644 --- a/xml/System.Web.UI.Design.WebControls/BulletedListDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/BulletedListDesigner.xml @@ -66,7 +66,7 @@ method to filter the set of events that the control it is designing will expose through the object. + Control designers use methods that are derived from the method to filter the set of events that the control it is designing will expose through the object. For the control, the method removes the event from the list that is exposed by the designer. diff --git a/xml/System.Web.UI.Design.WebControls/ButtonDesigner.xml b/xml/System.Web.UI.Design.WebControls/ButtonDesigner.xml index 80ac363049d76..3eb0b15c5c9e2 100644 --- a/xml/System.Web.UI.Design.WebControls/ButtonDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/ButtonDesigner.xml @@ -30,7 +30,7 @@ The following code example shows how to create a custom designer class that extends the class and overrides the method. If the property has not been set previously (that is, it has the field value), a call to the method sets it to a blue-dashed border with a width of three pixels, and then displays that border on the design surface. If the property has been set, the existing border property values are displayed. - Typically, the calls its base method, , which calls into the method of the associated control to generate the markup. + Typically, the calls its base method, , which calls into the method of the associated control to generate the markup. [!code-vb[System.Web.UI.Design.WebControls_ButtonDesignerSamples#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.UI.Design.WebControls_ButtonDesignerSamples/VB/custombutton.vb#1)] @@ -84,7 +84,7 @@ method replaces the property with the property of the control if the contains no displayable characters. Then, the method calls its base method, , which calls into the method to generate the markup. + The method replaces the property with the property of the control if the contains no displayable characters. Then, the method calls its base method, , which calls into the method to generate the markup. @@ -93,7 +93,7 @@ If the property has not been set previously (that is, it has the field value), a call to the method sets it to a blue-dashed border with a width of three pixels, and then displays that border on the design surface. If the property has been set, the existing border property values are displayed. - Typically, the calls its base method, , which calls into the method of the associated control to generate the markup. + Typically, the calls its base method, , which calls into the method of the associated control to generate the markup. [!code-vb[System.Web.UI.Design.WebControls_ButtonDesignerSamples#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.UI.Design.WebControls_ButtonDesignerSamples/VB/custombutton.vb#1)] diff --git a/xml/System.Web.UI.Design.WebControls/ChangePasswordDesigner.xml b/xml/System.Web.UI.Design.WebControls/ChangePasswordDesigner.xml index 33f0601d5c986..c7e28aa951d05 100644 --- a/xml/System.Web.UI.Design.WebControls/ChangePasswordDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/ChangePasswordDesigner.xml @@ -284,7 +284,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add or remove properties from the **Properties** grid. + Control designers use methods derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add or remove properties from the **Properties** grid. For the control, the method sets the attribute to `false` for properties that do not apply to templates (removes them from the **Properties** grid) when a user template has been defined. diff --git a/xml/System.Web.UI.Design.WebControls/CheckBoxDesigner.xml b/xml/System.Web.UI.Design.WebControls/CheckBoxDesigner.xml index b9ddb5c159dc6..e6c31a8fb8874 100644 --- a/xml/System.Web.UI.Design.WebControls/CheckBoxDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/CheckBoxDesigner.xml @@ -21,12 +21,12 @@ class overrides the method of the class to ensure that the control is displayed with a meaningful representation at design time. If the property is empty, the method of this class sets the property of the control to the property of the control. + The class overrides the method of the class to ensure that the control is displayed with a meaningful representation at design time. If the property is empty, the method of this class sets the property of the control to the property of the control. ## Examples - The following code example creates a custom designer class, named `SampleCheckBoxDesigner`, that inherits from the class. It overrides the method. If the property has not been set previously, a call to this method sets it to a string and displays that string on the design surface. If the property has been set, the existing property value is displayed. + The following code example creates a custom designer class, named `SampleCheckBoxDesigner`, that inherits from the class. It overrides the method. If the property has not been set previously, a call to this method sets it to a string and displays that string on the design surface. If the property has been set, the existing property value is displayed. [!code-vb[System.Web.UI.Design.WebControls_CheckBoxDesignerSamples#1](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.UI.Design.WebControls_CheckBoxDesignerSamples/VB/customcheckbox.vb#1)] @@ -80,7 +80,7 @@ ## Examples - The following code example overrides the method. If the property has not been set previously, a call to this method sets it to a string and displays that string on the design surface. If the property has already been set, the existing property value is displayed. + The following code example overrides the method. If the property has not been set previously, a call to this method sets it to a string and displays that string on the design surface. If the property has already been set, the existing property value is displayed. [!code-vb[System.Web.UI.Design.WebControls_CheckBoxDesignerSamples#2](~/samples/snippets/visualbasic/VS_Snippets_WebNet/System.Web.UI.Design.WebControls_CheckBoxDesignerSamples/VB/customcheckbox.vb#2)] diff --git a/xml/System.Web.UI.Design.WebControls/DataListDesigner.xml b/xml/System.Web.UI.Design.WebControls/DataListDesigner.xml index 41dd50d3bbc67..48e20027399d0 100644 --- a/xml/System.Web.UI.Design.WebControls/DataListDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/DataListDesigner.xml @@ -207,7 +207,7 @@ method. It alters the appearance of the control on the design surface if the control's property is `true`. + The following code example shows how to override the method. It alters the appearance of the control on the design surface if the control's property is `true`. The code uses `Try...Catch...Finally` syntax to do the following: diff --git a/xml/System.Web.UI.Design.WebControls/DataPagerDesigner.xml b/xml/System.Web.UI.Design.WebControls/DataPagerDesigner.xml index 296e6b2cc8eb4..021808edf1ddf 100644 --- a/xml/System.Web.UI.Design.WebControls/DataPagerDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/DataPagerDesigner.xml @@ -22,7 +22,7 @@ - The property returns the list of items that are used to create a smart tag panel. -- The property is used as the designer (shadowed) version of the property. +- The property is used as the designer (shadowed) version of the property. - The property returns a collection of template groups for the templated pager fields of the associated control. @@ -100,7 +100,7 @@ collection is not empty, the method refreshes the object to force the method to be called and then calls its base implementation. If the collection is empty, the method invokes the method to generate the markup. + If the collection is not empty, the method refreshes the object to force the method to be called and then calls its base implementation. If the collection is empty, the method invokes the method to generate the markup. ]]> @@ -126,7 +126,7 @@ method is used by the designer to render the control at design time if the collection is empty. The method calls the method to create a placeholder that displays the type and the ID of the control, and additional instructions for the user. + The method is used by the designer to render the control at design time if the collection is empty. The method calls the method to create a placeholder that displays the type and the ID of the control, and additional instructions for the user. ]]> @@ -202,7 +202,7 @@ method adds a new property to the property grid of the control that corresponds to the property. If the property is set to `true`, the method also sets the attribute of the property to `BrowsableAttribute.No`. This prevents pager fields from being deleted by using the `Fields` dialog box when a templated pager field is in template mode. + The method adds a new property to the property grid of the control that corresponds to the property. If the property is set to `true`, the method also sets the attribute of the property to `BrowsableAttribute.No`. This prevents pager fields from being deleted by using the `Fields` dialog box when a templated pager field is in template mode. ]]> diff --git a/xml/System.Web.UI.Design.WebControls/DetailsViewDesigner.xml b/xml/System.Web.UI.Design.WebControls/DetailsViewDesigner.xml index 1fcc0f361eb38..7b310260cec73 100644 --- a/xml/System.Web.UI.Design.WebControls/DetailsViewDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/DetailsViewDesigner.xml @@ -215,7 +215,7 @@ method calls the method to generate the markup for the design-time rendering of the control. The method also populates `regions` with a object for each clickable or selectable region of the design-time rendering. + The method calls the method to generate the markup for the design-time rendering of the control. The method also populates `regions` with a object for each clickable or selectable region of the design-time rendering. For the , the first cell in each row is selectable; all the cells in the rows are clickable. @@ -368,7 +368,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the `Properties` grid. + Control designers use methods derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the `Properties` grid. For the control, the method sets the object of the property to `false` when the control is in template mode. This ensures that a column that is in template mode cannot be deleted using the `Fields` dialog box. diff --git a/xml/System.Web.UI.Design.WebControls/EntityDataSourceDesigner.xml b/xml/System.Web.UI.Design.WebControls/EntityDataSourceDesigner.xml index 7ea56614254c7..481a101024318 100644 --- a/xml/System.Web.UI.Design.WebControls/EntityDataSourceDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/EntityDataSourceDesigner.xml @@ -347,7 +347,7 @@ . + This member overrides . ]]> diff --git a/xml/System.Web.UI.Design.WebControls/GridViewDesigner.xml b/xml/System.Web.UI.Design.WebControls/GridViewDesigner.xml index efb4cb133a9ff..c5aaae4da8192 100644 --- a/xml/System.Web.UI.Design.WebControls/GridViewDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/GridViewDesigner.xml @@ -377,7 +377,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. For the control, the method sets the object of the property to `false` when the control is in template mode. This is so a column that is in template mode cannot be deleted using the **Fields** dialog box. diff --git a/xml/System.Web.UI.Design.WebControls/HierarchicalDataBoundControlDesigner.xml b/xml/System.Web.UI.Design.WebControls/HierarchicalDataBoundControlDesigner.xml index 53999fe9be373..fab2fa5b3540f 100644 --- a/xml/System.Web.UI.Design.WebControls/HierarchicalDataBoundControlDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/HierarchicalDataBoundControlDesigner.xml @@ -208,7 +208,7 @@ property of the designer or the property of the associated control that is derived from the class. + The data source can be accessed using the property of the designer or the property of the associated control that is derived from the class. ]]> @@ -233,7 +233,7 @@ property of the designer or the property of the associated control that is derived from the class. + The data source can be accessed using the property of the designer or the property of the associated control that is derived from the class. ]]> @@ -338,7 +338,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. For controls that are derived from the class, the method creates design-time properties to shadow the and properties. diff --git a/xml/System.Web.UI.Design.WebControls/LinqDataSourceDesigner.xml b/xml/System.Web.UI.Design.WebControls/LinqDataSourceDesigner.xml index 60c95581487e8..d246655cbb3be 100644 --- a/xml/System.Web.UI.Design.WebControls/LinqDataSourceDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/LinqDataSourceDesigner.xml @@ -82,7 +82,7 @@ method can be called if the property of the associated control implements the interface. In that case, the property value is `true`. + The method can be called if the property of the associated control implements the interface. In that case, the property value is `true`. If the property is `true`, the **Configure Data Source** menu item is displayed in the **LinqDataSource Tasks** menu of the associated control on the visual designer surface. When this item is selected, the **Configure Data Source** wizard is started. @@ -112,7 +112,7 @@ ## Remarks The method can be called if all the following conditions are true: -- The property of the associated control implements the interface. +- The property of the associated control implements the interface. - The property contains a value. diff --git a/xml/System.Web.UI.Design.WebControls/ListControlDesigner.xml b/xml/System.Web.UI.Design.WebControls/ListControlDesigner.xml index 5d80352b96422..b6db691da7300 100644 --- a/xml/System.Web.UI.Design.WebControls/ListControlDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/ListControlDesigner.xml @@ -126,7 +126,7 @@ base class, the method sets the and properties of the object to reference the design-time data source, then calls the method, and then restores the and properties to their original values. + For the base class, the method sets the and properties of the object to reference the design-time data source, then calls the method, and then restores the and properties to their original values. For the class, however, the method has no functionality, because objects were just added to the collection. @@ -412,7 +412,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. For controls that are derived from the object, the adds the attribute to the and properties of the associated control. diff --git a/xml/System.Web.UI.Design.WebControls/ListViewDesigner.xml b/xml/System.Web.UI.Design.WebControls/ListViewDesigner.xml index e0580e1270f62..4c157ca6b885f 100644 --- a/xml/System.Web.UI.Design.WebControls/ListViewDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/ListViewDesigner.xml @@ -98,7 +98,7 @@ control ( and ) are not defined, the method calls the method to generate the HTML markup. + If the two required templates for the control ( and ) are not defined, the method calls the method to generate the HTML markup. ]]> @@ -175,7 +175,7 @@ method is used by the designer to render the control at design time if the two required templates for the control ( and ) are not defined. The method calls the method to create a placeholder that displays the type and the ID of the control, and additional instructions for the user. + The method is used by the designer to render the control at design time if the two required templates for the control ( and ) are not defined. The method calls the method to create a placeholder that displays the type and the ID of the control, and additional instructions for the user. ]]> @@ -288,7 +288,7 @@ property always returns 21. This causes 21 records to be displayed in the design surface for the control. An exception is if there is a control inside the template and the property is set to a value less than 21. In that case, the number of records to display is the value of the property. The maximum number of records that the control will display on the designer surface is 21 records. + The property always returns 21. This causes 21 records to be displayed in the design surface for the control. An exception is if there is a control inside the template and the property is set to a value less than 21. In that case, the number of records to display is the value of the property. The maximum number of records that the control will display on the designer surface is 21 records. ]]> diff --git a/xml/System.Web.UI.Design.WebControls/LoginDesigner.xml b/xml/System.Web.UI.Design.WebControls/LoginDesigner.xml index b0d8a0ccd9b72..4ebb0aac82b2f 100644 --- a/xml/System.Web.UI.Design.WebControls/LoginDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/LoginDesigner.xml @@ -320,7 +320,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. If a property has been defined for the control, the sets the attribute of properties that do not apply when templated to `false` so those properties do not appear in the **Properties** grid. diff --git a/xml/System.Web.UI.Design.WebControls/LoginViewDesigner.xml b/xml/System.Web.UI.Design.WebControls/LoginViewDesigner.xml index b6b0a0823d808..60f147f7bfcde 100644 --- a/xml/System.Web.UI.Design.WebControls/LoginViewDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/LoginViewDesigner.xml @@ -376,7 +376,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. The method applies the attribute of the property so that it does not appear in the **Properties** grid. diff --git a/xml/System.Web.UI.Design.WebControls/ObjectDataSourceDesigner.xml b/xml/System.Web.UI.Design.WebControls/ObjectDataSourceDesigner.xml index 423d8ff14171a..296628ca76d93 100644 --- a/xml/System.Web.UI.Design.WebControls/ObjectDataSourceDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/ObjectDataSourceDesigner.xml @@ -230,7 +230,7 @@ method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. + Control designers use methods that are derived from the method to shadow various control properties with corresponding design-time properties that the designer implements, and to add properties to or remove properties from the **Properties** grid. The method creates design-time properties to shadow the and properties of the associated control so that they appear in the **Properties** grid of the visual designer. diff --git a/xml/System.Web.UI.Design.WebControls/PanelContainerDesigner.xml b/xml/System.Web.UI.Design.WebControls/PanelContainerDesigner.xml index cdbdaacaf6824..178d2afef7d73 100644 --- a/xml/System.Web.UI.Design.WebControls/PanelContainerDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/PanelContainerDesigner.xml @@ -92,7 +92,7 @@ method calls the base method, which adds string representations of style attributes to the `styleAttributes` collection. These attributes are based on the style properties of the associated control. + The method calls the base method, which adds string representations of style attributes to the `styleAttributes` collection. These attributes are based on the style properties of the associated control. The sets the direction of `styleAttribute` to a code indicating left-to-right or right-to-left, based on the value of the property of the associated control. @@ -152,7 +152,7 @@ property is an empty string (""), the property returns an empty object. Otherwise, the property returns a default object that is generated by the base property. + If the property is an empty string (""), the property returns an empty object. Otherwise, the property returns a default object that is generated by the base property. diff --git a/xml/System.Web.UI.Design.WebControls/RepeaterDesigner.xml b/xml/System.Web.UI.Design.WebControls/RepeaterDesigner.xml index 63611f48e7f26..752c4b68bdaf1 100644 --- a/xml/System.Web.UI.Design.WebControls/RepeaterDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/RepeaterDesigner.xml @@ -367,7 +367,7 @@ method uses the method to construct a data source from the object that is specified by the property. + The method uses the method to construct a data source from the object that is specified by the property. ]]> diff --git a/xml/System.Web.UI.Design.WebControls/ValidationSummaryDesigner.xml b/xml/System.Web.UI.Design.WebControls/ValidationSummaryDesigner.xml index a52064892b77c..f39f5c7cfc3ca 100644 --- a/xml/System.Web.UI.Design.WebControls/ValidationSummaryDesigner.xml +++ b/xml/System.Web.UI.Design.WebControls/ValidationSummaryDesigner.xml @@ -93,7 +93,7 @@ method to shadow control properties with corresponding design-time properties that the designer implements, to add properties to the properties grid, to remove properties from the properties grid, and to change attributes of properties in the properties grid. + Control designers use methods that are derived from the method to shadow control properties with corresponding design-time properties that the designer implements, to add properties to the properties grid, to remove properties from the properties grid, and to change attributes of properties in the properties grid. ]]> diff --git a/xml/System.Web.UI.Design/ConnectionStringsExpressionEditor.xml b/xml/System.Web.UI.Design/ConnectionStringsExpressionEditor.xml index 12a099990cb2c..f9cf423b809c6 100644 --- a/xml/System.Web.UI.Design/ConnectionStringsExpressionEditor.xml +++ b/xml/System.Web.UI.Design/ConnectionStringsExpressionEditor.xml @@ -70,7 +70,7 @@ ## Remarks The method looks up the connection name and type specified by `expression`, and then returns the connection. - The visual designer uses the method to evaluate a connection string expression and provide the design-time value for an associated control property. The visual designer uses the method to parse the expression string at design time, and then calls the method with the parsed expression data. The visual designer uses the evaluated expression result to assign control property values that are rendered on the design surface. + The visual designer uses the method to evaluate a connection string expression and provide the design-time value for an associated control property. The visual designer uses the method to parse the expression string at design time, and then calls the method with the parsed expression data. The visual designer uses the evaluated expression result to assign control property values that are rendered on the design surface. At run time, the page parser uses the and methods of the corresponding implementation to evaluate an expression and provide the run-time value for an associated control property. diff --git a/xml/System.Web.UI.Design/ControlDesigner.xml b/xml/System.Web.UI.Design/ControlDesigner.xml index 69536a1cb8537..9b48299ac8819 100644 --- a/xml/System.Web.UI.Design/ControlDesigner.xml +++ b/xml/System.Web.UI.Design/ControlDesigner.xml @@ -1387,7 +1387,7 @@ - The user enters or exits template editing mode for the control. - The class supplies a default delegate to handle the event. Classes deriving from override the method to process events that are raised when the user clicks a control. + The class supplies a default delegate to handle the event. Classes deriving from override the method to process events that are raised when the user clicks a control. The method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. @@ -1539,7 +1539,7 @@ - The user enters or exits template editing mode for the control. - The class supplies a default delegate to handle the event. Classes deriving from should set the value and override the method to process events that are raised when the design host draws the control on the design surface. + The class supplies a default delegate to handle the event. Classes deriving from should set the value and override the method to process events that are raised when the design host draws the control on the design surface. The method allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. diff --git a/xml/System.Web.UI.Design/ControlLocation.xml b/xml/System.Web.UI.Design/ControlLocation.xml index 3150b8559d16a..5ddedb191e9de 100644 --- a/xml/System.Web.UI.Design/ControlLocation.xml +++ b/xml/System.Web.UI.Design/ControlLocation.xml @@ -15,7 +15,7 @@ enumeration is used by the method. + The enumeration is used by the method. ]]> diff --git a/xml/System.Web.UI.Design/DataBindingCollectionConverter.xml b/xml/System.Web.UI.Design/DataBindingCollectionConverter.xml index 912bab2589708..f81b3015ab2b7 100644 --- a/xml/System.Web.UI.Design/DataBindingCollectionConverter.xml +++ b/xml/System.Web.UI.Design/DataBindingCollectionConverter.xml @@ -21,7 +21,7 @@ method for all destination types except , for which an empty string ("") is returned. + This type converter calls the base method for all destination types except , for which an empty string ("") is returned. diff --git a/xml/System.Web.UI.Design/DataSourceDesigner.xml b/xml/System.Web.UI.Design/DataSourceDesigner.xml index 5f56d300486c7..79b5b56f513f8 100644 --- a/xml/System.Web.UI.Design/DataSourceDesigner.xml +++ b/xml/System.Web.UI.Design/DataSourceDesigner.xml @@ -248,7 +248,7 @@ method returns the result from the base method. + The default implementation of the method returns the result from the base method. ]]> diff --git a/xml/System.Web.UI.Design/DesignerAutoFormatCollection.xml b/xml/System.Web.UI.Design/DesignerAutoFormatCollection.xml index 54694cecf175d..7f5e39368cfd4 100644 --- a/xml/System.Web.UI.Design/DesignerAutoFormatCollection.xml +++ b/xml/System.Web.UI.Design/DesignerAutoFormatCollection.xml @@ -422,7 +422,7 @@ ## Remarks Enumerating through a collection is not a thread-safe procedure intrinsically. Even when a collection is synchronized, other threads can still modify the collection. This causes exceptions during enumeration. - Lock the collection by using the method during the entire enumeration to guarantee thread safety. For detailed information about locking collections for thread-safe access, see . + Lock the collection by using the method during the entire enumeration to guarantee thread safety. For detailed information about locking collections for thread-safe access, see . ]]> @@ -697,7 +697,7 @@ instance is cast to an interface. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> diff --git a/xml/System.Web.UI.Design/DesignerRegionCollection.xml b/xml/System.Web.UI.Design/DesignerRegionCollection.xml index 6a81f0bb29a29..5b3e74deaff11 100644 --- a/xml/System.Web.UI.Design/DesignerRegionCollection.xml +++ b/xml/System.Web.UI.Design/DesignerRegionCollection.xml @@ -22,7 +22,7 @@ ## Remarks The class, and any derived class, uses the class to contain and enumerate the designer regions for the control in a design host, such as [!INCLUDE[vsprvslong](~/includes/vsprvslong-md.md)]. - For example, the method can be used to define and add regions to the collection. + For example, the method can be used to define and add regions to the collection. Use the property to access the control designer object that contains the designer region collection. Use the methods and properties to examine and maintain the objects that are in the collection. @@ -557,7 +557,7 @@ ## Remarks Enumerating through a collection is not a thread-safe procedure intrinsically. Even when a collection is synchronized, other threads can still modify the collection. This causes exceptions during enumeration. - Lock the collection by using the method during the whole enumeration to guarantee thread safety. For detailed information about locking collections for thread-safe access, see . + Lock the collection by using the method during the whole enumeration to guarantee thread safety. For detailed information about locking collections for thread-safe access, see . ]]> diff --git a/xml/System.Web.UI.Design/ExpressionEditor.xml b/xml/System.Web.UI.Design/ExpressionEditor.xml index 486684e0cf4c4..537dc00b2e92f 100644 --- a/xml/System.Web.UI.Design/ExpressionEditor.xml +++ b/xml/System.Web.UI.Design/ExpressionEditor.xml @@ -104,7 +104,7 @@ ## Remarks The visual designer host uses the method to evaluate an expression and provide the design-time value for an associated control property. - The visual designer uses the method to parse the expression string at design time, and then calls the method with the parsed expression data. The visual designer uses the evaluated expression result to assign control property values that are rendered on the design surface. + The visual designer uses the method to parse the expression string at design time, and then calls the method with the parsed expression data. The visual designer uses the evaluated expression result to assign control property values that are rendered on the design surface. ]]> @@ -273,7 +273,7 @@ Classes deriving from the class optionally can override the method to provide a custom expression editor sheet. A custom expression editor sheet can allow design-time input for multiple properties, which are combined together to form the expression string. - For example, the class derives from the class and provides an implementation for evaluating and associating a resource string reference with a control property at design time. The class is associated with the expression prefix `Resources` and the implementation. The method returns a , which defines the individual properties that form a resource reference expression. + For example, the class derives from the class and provides an implementation for evaluating and associating a resource string reference with a control property at design time. The class is associated with the expression prefix `Resources` and the implementation. The method returns a , which defines the individual properties that form a resource reference expression. ]]> diff --git a/xml/System.Web.UI.Design/HtmlIntrinsicControlDesigner.xml b/xml/System.Web.UI.Design/HtmlIntrinsicControlDesigner.xml index 816ef26b7ed78..853846c3d33b6 100644 --- a/xml/System.Web.UI.Design/HtmlIntrinsicControlDesigner.xml +++ b/xml/System.Web.UI.Design/HtmlIntrinsicControlDesigner.xml @@ -16,7 +16,7 @@ namespace. + Intrinsic HTML controls are defined within, or derived from classes defined within, the namespace. ]]> diff --git a/xml/System.Web.UI.Design/IDataSourceSchema.xml b/xml/System.Web.UI.Design/IDataSourceSchema.xml index e9c8ad130047d..e89fd6bc2279a 100644 --- a/xml/System.Web.UI.Design/IDataSourceSchema.xml +++ b/xml/System.Web.UI.Design/IDataSourceSchema.xml @@ -41,7 +41,7 @@ method returns an array of objects that implement the interface. For example, in the array returned by the method, each element of the array is a object that implements . + A class that implements the method returns an array of objects that implement the interface. For example, in the array returned by the method, each element of the array is a object that implements . ]]> diff --git a/xml/System.Web.UI.Design/ReadWriteControlDesigner.xml b/xml/System.Web.UI.Design/ReadWriteControlDesigner.xml index a13e4749a8607..57c8245cacb75 100644 --- a/xml/System.Web.UI.Design/ReadWriteControlDesigner.xml +++ b/xml/System.Web.UI.Design/ReadWriteControlDesigner.xml @@ -112,7 +112,7 @@ ## Remarks > [!NOTE] -> The method is obsolete. Use the method for equivalent control designer functionality. +> The method is obsolete. Use the method for equivalent control designer functionality. > [!NOTE] > this method must be overridden in a derived class to implement the designer. @@ -147,7 +147,7 @@ ## Remarks > [!NOTE] -> The method is obsolete. Use the members of the property instead. For example, use the and methods on the property to map properties to styles. +> The method is obsolete. Use the members of the property instead. For example, use the and methods on the property to map properties to styles. ]]> diff --git a/xml/System.Web.UI.Design/ResourceExpressionEditor.xml b/xml/System.Web.UI.Design/ResourceExpressionEditor.xml index 69b0412c0bd6a..1f0736d730631 100644 --- a/xml/System.Web.UI.Design/ResourceExpressionEditor.xml +++ b/xml/System.Web.UI.Design/ResourceExpressionEditor.xml @@ -22,7 +22,7 @@ When you browse the property for a control in the design-time properties grid, the visual designer displays a dialog box to set expressions that provide the run-time value for a control property. You can select the expression type based on a list of expression prefixes. When you select the **Resources** expression prefix in the list, the visual designer uses the methods to set, evaluate, and convert the expression based on the resource expression syntax. The visual designer uses the evaluated expression result to assign control property values that are rendered on the design surface. - The base property for a returns the string `Resources`. The class is associated with the expression prefix `Resources` and the implementation. + The base property for a returns the string `Resources`. The class is associated with the expression prefix `Resources` and the implementation. The method evaluates an input resource expression. The method returns the implementation that is used to select the resource name, class, and designer default value, and to form a resource expression from the selected resource values. diff --git a/xml/System.Web.UI.Design/ResourceExpressionEditorSheet.xml b/xml/System.Web.UI.Design/ResourceExpressionEditorSheet.xml index bdc20290f80a9..b77acc2dd2e9c 100644 --- a/xml/System.Web.UI.Design/ResourceExpressionEditorSheet.xml +++ b/xml/System.Web.UI.Design/ResourceExpressionEditorSheet.xml @@ -18,7 +18,7 @@ ## Remarks The visual designer uses the class with the class to select the individual properties of a resource reference expression, and to combine the selected resource expression property values into a resource expression. - The method returns a object. In the expressions dialog box, when you select a control property and bind it to a resource expression, the visual designer calls the method. The visual designer uses the returned object to prompt for the and properties. Once the resource expression properties are selected, the visual designer calls the method to combine the properties into a resource expression string. + The method returns a object. In the expressions dialog box, when you select a control property and bind it to a resource expression, the visual designer calls the method. The visual designer uses the returned object to prompt for the and properties. Once the resource expression properties are selected, the visual designer calls the method to combine the properties into a resource expression string. The property must be specified in a resource expression; it indexes the resource value. The property is optional. It references the class key or file name that defines the resource in the global resources folder. diff --git a/xml/System.Web.UI.Design/RouteUrlExpressionEditorSheet.xml b/xml/System.Web.UI.Design/RouteUrlExpressionEditorSheet.xml index 2c511c5a5e7db..0f44b1e50a1b3 100644 --- a/xml/System.Web.UI.Design/RouteUrlExpressionEditorSheet.xml +++ b/xml/System.Web.UI.Design/RouteUrlExpressionEditorSheet.xml @@ -18,7 +18,7 @@ ## Remarks The visual designer uses the class together with the class to select the individual properties of a `RouteUrl` expression, and to combine the selected expression property values into a `RouteUrl` expression. - The method returns a object. In the expressions dialog box, when you select a control property and bind it to a `RouteUrl` expression, the visual designer calls the method. The visual designer uses the returned object to prompt for the and properties. Once the properties are selected, the visual designer calls the method to combine the properties into a `RouteUrl` expression string. + The method returns a object. In the expressions dialog box, when you select a control property and bind it to a `RouteUrl` expression, the visual designer calls the method. The visual designer uses the returned object to prompt for the and properties. Once the properties are selected, the visual designer calls the method to combine the properties into a `RouteUrl` expression string. The property must be specified if the property is not specified. The property must be specified if the is not specified. Both properties may be specified. diff --git a/xml/System.Web.UI.Design/RouteValueExpressionEditorSheet.xml b/xml/System.Web.UI.Design/RouteValueExpressionEditorSheet.xml index deb54fad29e38..f90f57a09c780 100644 --- a/xml/System.Web.UI.Design/RouteValueExpressionEditorSheet.xml +++ b/xml/System.Web.UI.Design/RouteValueExpressionEditorSheet.xml @@ -18,7 +18,7 @@ ## Remarks The visual designer uses the class together with the class to select the individual properties of a `RouteValue` expression, and to combine the selected expression property values into a `RouteValue` expression. - The method returns a object. In the expressions dialog box, when you select a control property and bind it to a `RouteValue` expression, the visual designer calls the method. The visual designer uses the returned object to prompt for the property. Once the property is selected, the visual designer calls the method to create a `RouteValue` expression string. + The method returns a object. In the expressions dialog box, when you select a control property and bind it to a `RouteValue` expression, the visual designer calls the method. The visual designer uses the returned object to prompt for the property. Once the property is selected, the visual designer calls the method to create a `RouteValue` expression string. The property must be specified in order to create a `RouteValue` expression string. diff --git a/xml/System.Web.UI.Design/SupportsPreviewControlAttribute.xml b/xml/System.Web.UI.Design/SupportsPreviewControlAttribute.xml index 2baa5e8fa1017..060ef1e6fb029 100644 --- a/xml/System.Web.UI.Design/SupportsPreviewControlAttribute.xml +++ b/xml/System.Web.UI.Design/SupportsPreviewControlAttribute.xml @@ -125,7 +125,7 @@ method overrides the method. + The method overrides the method. The method compares two instances based on the value of their properties. @@ -153,7 +153,7 @@ method overrides the method. + The method overrides the method. The method generates the same hash code for two objects that are equal according to the method. The hash code is suitable for use in hashing algorithms and data structures, such as hash tables. diff --git a/xml/System.Web.UI.Design/TemplateEditingVerb.xml b/xml/System.Web.UI.Design/TemplateEditingVerb.xml index 7bdbefdf1ba18..dc8e96ffbcf83 100644 --- a/xml/System.Web.UI.Design/TemplateEditingVerb.xml +++ b/xml/System.Web.UI.Design/TemplateEditingVerb.xml @@ -183,9 +183,9 @@ and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. + This method overrides and cleans up resources by calling `Dispose(false)`. Override `Dispose(Boolean)` to customize the cleanup. - Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. + Application code should not call this method; an object's `Finalize` method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the method. For more information, see [Finalize Methods and Destructors](http://msdn.microsoft.com/en-us/fd376774-1643-499b-869e-9546a3aeea70), [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md), and [Overriding the Finalize Method](http://msdn.microsoft.com/en-us/8026cb68-fe93-43fc-96c1-c09ad7d64cd3). diff --git a/xml/System.Web.UI.Design/TemplatedControlDesigner.xml b/xml/System.Web.UI.Design/TemplatedControlDesigner.xml index 630f30cb05acb..ccb0e39c4d944 100644 --- a/xml/System.Web.UI.Design/TemplatedControlDesigner.xml +++ b/xml/System.Web.UI.Design/TemplatedControlDesigner.xml @@ -507,7 +507,7 @@ ## Remarks > [!NOTE] -> The property is obsolete. Use the property for equivalent control designer functionality. +> The property is obsolete. Use the property for equivalent control designer functionality. A document is in template mode when a template is currently being viewed or edited in the forms designer. diff --git a/xml/System.Web.UI.Design/ViewEvent.xml b/xml/System.Web.UI.Design/ViewEvent.xml index b035afa41c5ae..f9b04457bbd36 100644 --- a/xml/System.Web.UI.Design/ViewEvent.xml +++ b/xml/System.Web.UI.Design/ViewEvent.xml @@ -16,7 +16,7 @@ object is provided to the designer component by the design host, for example [!INCLUDE[vsprvslong](~/includes/vsprvslong-md.md)], when raising an event caused by certain user actions on the design-time view of a control. The event is handled by a delegate method, which takes a object as a parameter. The property of the class is a object. The delegate method compares the property to the static fields to determine which type of action raised the event. For example, an event is raised under the following circumstances: + A object is provided to the designer component by the design host, for example [!INCLUDE[vsprvslong](~/includes/vsprvslong-md.md)], when raising an event caused by certain user actions on the design-time view of a control. The event is handled by a delegate method, which takes a object as a parameter. The property of the class is a object. The delegate method compares the property to the static fields to determine which type of action raised the event. For example, an event is raised under the following circumstances: - You click a region on the design surface. @@ -24,7 +24,7 @@ - You enter or exit template editing mode for a control. - The class supplies a default delegate to handle the event. Custom control designers override the , , and methods to process those events for the control on the design surface. + The class supplies a default delegate to handle the event. Custom control designers override the , , and methods to process those events for the control on the design surface. The designer host initializes a object for the type of action on the design surface, and then passes the object to the delegate. The property of the object indicates which type of action: diff --git a/xml/System.Web.UI.Design/WebFormsRootDesigner.xml b/xml/System.Web.UI.Design/WebFormsRootDesigner.xml index 42136231a7543..2a03f2419ea5e 100644 --- a/xml/System.Web.UI.Design/WebFormsRootDesigner.xml +++ b/xml/System.Web.UI.Design/WebFormsRootDesigner.xml @@ -127,7 +127,7 @@ property is set by the method. + The property is set by the method. ]]> diff --git a/xml/System.Web.UI.HtmlControls/HtmlButton.xml b/xml/System.Web.UI.HtmlControls/HtmlButton.xml index 9327c6e5e996b..539b246f39ef0 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlButton.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlButton.xml @@ -245,7 +245,7 @@ ## Remarks The method is used by the control, when it is clicked, to raise a event. - If the property is `true`, the method is called using the group of controls specified in the property. + If the property is `true`, the method is called using the group of controls specified in the property. This method is used primarily by control developers extending the functionality of the control. @@ -275,7 +275,7 @@ method writes the `onclick` attribute of the rendered control, and then calls the base method. + The method writes the `onclick` attribute of the rendered control, and then calls the base method. The method is used primarily by control developers extending the functionality of the control. diff --git a/xml/System.Web.UI.HtmlControls/HtmlContainerControl.xml b/xml/System.Web.UI.HtmlControls/HtmlContainerControl.xml index c1bc268ae64bf..e5019a1364ae6 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlContainerControl.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlContainerControl.xml @@ -162,7 +162,7 @@ To provide automatic HTML encoding and decoding, use the property. > [!NOTE] -> If there are no child controls, the property contains the value . +> If there are no child controls, the property contains the value . @@ -217,7 +217,7 @@ To prevent automatic HTML encoding and decoding, use the property. > [!NOTE] -> If there are no child controls, the property contains the value . +> If there are no child controls, the property contains the value . @@ -288,7 +288,7 @@ method overrides the method to render the opening tag, child controls, and closing tag of the control. + The method overrides the method to render the opening tag, child controls, and closing tag of the control. The method is used primarily by control developers extending the functionality of the control. diff --git a/xml/System.Web.UI.HtmlControls/HtmlControl.xml b/xml/System.Web.UI.HtmlControls/HtmlControl.xml index a6f1cb9effe7a..73ac50b9f183d 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlControl.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlControl.xml @@ -126,11 +126,11 @@ property. + Use this property to programmatically access the attributes of the HTML server control. All HTML server controls store their attributes in the property. HTML attributes are treated by the .NET Framework as properties on the HTML server control to which they belong. - For additional information on the attributes collection, see the class. + For additional information on the attributes collection, see the class. @@ -231,7 +231,7 @@ method to access an attribute on the server control. All HTML server controls store their attributes in the property. HTML attributes are treated by the ASP.NET page framework as properties on the HTML server control to which they belong. The method's `name` parameter is case-insensitive. + Use the method to access an attribute on the server control. All HTML server controls store their attributes in the property. HTML attributes are treated by the ASP.NET page framework as properties on the HTML server control to which they belong. The method's `name` parameter is case-insensitive. ]]> @@ -287,7 +287,7 @@ method writes the attribute of the control. + The method writes the attribute of the control. The method is used primarily by control developers extending the functionality of the control. @@ -349,7 +349,7 @@ method to set an attribute on the server control. All HTML server controls store their attributes in the property. + Use the method to set an attribute on the server control. All HTML server controls store their attributes in the property. HTML attributes are treated by the ASP.NET page framework as properties on the HTML server control to which they belong. The method's `name` parameter is case-insensitive. @@ -386,7 +386,7 @@ ## Remarks Use this property to programmatically access the style properties of the HTML server control. - For additional information on the CSS style collection, see the class. + For additional information on the CSS style collection, see the class. diff --git a/xml/System.Web.UI.HtmlControls/HtmlForm.xml b/xml/System.Web.UI.HtmlControls/HtmlForm.xml index 2ca3c7c15f0bc..06a9837149305 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlForm.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlForm.xml @@ -19,7 +19,7 @@ The control is a container for server controls on a Web Forms page. All server controls that post back to the server must be placed between the opening and closing tags of an control. > [!NOTE] -> ASP.NET allows only a single control to be active on a Web Forms page. If there is more than one active control on a Web Forms page, the common language runtime will throw an exception when you request the page. You can, however, use a control where each object contains one control, because only one is active at any given time. +> ASP.NET allows only a single control to be active on a Web Forms page. If there is more than one active control on a Web Forms page, the common language runtime will throw an exception when you request the page. You can, however, use a control where each object contains one control, because only one is active at any given time. You can control the behavior of the control by setting its properties. To specify the encoding type for the form's data, set the property. The method (`GET` or `POST`) that a browser uses to post form data to the server for processing is specified by setting the property. @@ -130,7 +130,7 @@ value for each control on a page. For more information, see the property. + To prevent naming conflicts when multiple instances of a control are rendered, [!INCLUDE[vstecasp](~/includes/vstecasp-md.md)] automatically generates a unique value for each control on a page. For more information, see the property. ]]> @@ -436,10 +436,10 @@ method is called just prior to rendering the control. If the property is set to `true`, the method registers the smart navigation script file reference so that it gets rendered. + The method is called just prior to rendering the control. If the property is set to `true`, the method registers the smart navigation script file reference so that it gets rendered. > [!NOTE] -> The property has been deprecated in ASP.NET version 2.0. +> The property has been deprecated in ASP.NET version 2.0. ]]> @@ -540,7 +540,7 @@ The method renders client script to ensure that the browser focus is set to the control specified in the property. > [!NOTE] -> A control specified by the property takes precedence over a control specified by the property. +> A control specified by the property takes precedence over a control specified by the property. ]]> diff --git a/xml/System.Web.UI.HtmlControls/HtmlGenericControl.xml b/xml/System.Web.UI.HtmlControls/HtmlGenericControl.xml index c93bc42ebe323..b0fb606dcc029 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlGenericControl.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlGenericControl.xml @@ -104,7 +104,7 @@ |`TagName`|The value of the `tag` parameter.| > [!NOTE] -> If the `tag` parameter is `null`, the property is set to . +> If the `tag` parameter is `null`, the property is set to . diff --git a/xml/System.Web.UI.HtmlControls/HtmlHead.xml b/xml/System.Web.UI.HtmlControls/HtmlHead.xml index 288ddcb3c671d..479c06572a4b7 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlHead.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlHead.xml @@ -143,7 +143,7 @@ property. + For information about this property, see the property. ]]> @@ -168,7 +168,7 @@ property. + For information about this property, see the property. ]]> diff --git a/xml/System.Web.UI.HtmlControls/HtmlInputButton.xml b/xml/System.Web.UI.HtmlControls/HtmlInputButton.xml index 3adb44205ef7b..6a8162472de6f 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlInputButton.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlInputButton.xml @@ -190,7 +190,7 @@ method overrides the method. is used primarily by control developers. + The method overrides the method. is used primarily by control developers. @@ -275,7 +275,7 @@ ## Remarks The method is used by the control, when it is clicked, to raise a event. - If the property is `true`, the method is called using the group of controls specified in the property. + If the property is `true`, the method is called using the group of controls specified in the property. This method is used primarily by control developers extending the functionality of the control. @@ -305,7 +305,7 @@ method overrides the base .method. is used primarily by control developers. + The method overrides the base .method. is used primarily by control developers. diff --git a/xml/System.Web.UI.HtmlControls/HtmlInputControl.xml b/xml/System.Web.UI.HtmlControls/HtmlInputControl.xml index 326fee2c0a886..97f496f3f7288 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlInputControl.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlInputControl.xml @@ -105,10 +105,10 @@ property to determine the unique identifier name for an . In this implementation, the `get` accessor returns the value of the property. However, the `set` accessor does not assign a value to this property. + Use the property to determine the unique identifier name for an . In this implementation, the `get` accessor returns the value of the property. However, the `set` accessor does not assign a value to this property. > [!NOTE] -> The `set` accessor does not assign a value to this property because the property must have the same value as the property for most controls to work properly. +> The `set` accessor does not assign a value to this property because the property must have the same value as the property for most controls to work properly. Classes that inherit from the class can override this implementation, if necessary. diff --git a/xml/System.Web.UI.HtmlControls/HtmlInputFile.xml b/xml/System.Web.UI.HtmlControls/HtmlInputFile.xml index d69f6ed13581b..01ea33cb41322 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlInputFile.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlInputFile.xml @@ -35,7 +35,7 @@ > [!NOTE] > The property of an control must be set to "multipart/form-data" for this control to work properly. - The control does not have a built-in way to post back to the server. To upload the file to the server, use the method of the object contained in the property. This operation is usually done in an event-handling method, such as for a button click. + The control does not have a built-in way to post back to the server. To upload the file to the server, use the method of the object contained in the property. This operation is usually done in an event-handling method, such as for a button click. > [!NOTE] > When you use the method of the class, make sure to specify a rooted path (for example, "C:\MyFiles\Test.txt"). The behavior of the method can be specified in the [httpRuntime Element (ASP.NET Settings Schema)](http://msdn.microsoft.com/en-us/e9b81350-8aaf-47cc-9843-5f7d0c59f369) configuration section with the `requireRootedSaveAsPath` attribute. The default value of this attribute is `true`. If you set this attribute to `false`, then using the method with no path specified will attempt to place the file in the `systemroot` \system32\inetsrv directory. By default, this directory is write-protected; therefore, the file can not be saved there. Make sure to provide write permission for the account used by ASP.NET for the directory where you want to store the file. @@ -165,7 +165,7 @@ control implements the interface, which has two methods: and . The method is called by the method and always returns `false`, indicating that the control's state is not managed by the ASP.NET page framework. + The control implements the interface, which has two methods: and . The method is called by the method and always returns `false`, indicating that the control's state is not managed by the ASP.NET page framework. The method is used primarily by control developers extending the functionality of the control. @@ -308,7 +308,7 @@ control implements the interface, which has two methods: and . The method does not participate in the processing of the control and is included to complete the interface implementation. + The control implements the interface, which has two methods: and . The method does not participate in the processing of the control and is included to complete the interface implementation. The method is used primarily by control developers to extend the functionality of the control. @@ -441,7 +441,7 @@ The property retrieves the full path of the file on the client's computer (for example "C:\MyFiles\Test.txt"). This is useful when you need to know where the file is stored on the computer submitting the file. This property is also commonly used to determine the original file name. To get the original file name, parse the value of this property. > [!NOTE] -> The property is read-only. If you attempt to assign a value to this property, a is thrown. +> The property is read-only. If you attempt to assign a value to this property, a is thrown. diff --git a/xml/System.Web.UI.HtmlControls/HtmlInputImage.xml b/xml/System.Web.UI.HtmlControls/HtmlInputImage.xml index e159298a519c7..9589eff3bb99c 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlInputImage.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlInputImage.xml @@ -33,7 +33,7 @@ ## Remarks Use the control to create a button that displays an image. You can programmatically control the action associated with the control by providing an event handler for the event. - The coordinates where the user clicks an control can be determined by using the and properties of the object that is passed as a parameter to the user-defined event handler. + The coordinates where the user clicks an control can be determined by using the and properties of the object that is passed as a parameter to the user-defined event handler. For a list of initial property values for an instance of , see the constructor. @@ -365,7 +365,7 @@ ## Remarks The event is raised when the user clicks an control. - The coordinates where the user clicks an control can be determined by using the and properties of the object. The object is passed as a parameter to the user-defined event handler. + The coordinates where the user clicks an control can be determined by using the and properties of the object. The object is passed as a parameter to the user-defined event handler. > [!NOTE] > The origin (0, 0) is located at the upper-left corner of the image. diff --git a/xml/System.Web.UI.HtmlControls/HtmlInputRadioButton.xml b/xml/System.Web.UI.HtmlControls/HtmlInputRadioButton.xml index a9b65c6ce0029..ae123ee47eaaf 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlInputRadioButton.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlInputRadioButton.xml @@ -277,7 +277,7 @@ Caption Text
The event is raised when the property of the control changes values between posts to the server. This allows you to create a custom event handler that performs a specific set of instructions (such as data validation) when the event is raised. > [!NOTE] -> The control must have view state enabled for the event to work correctly. To enable view state for all controls on the Web Forms page, set the property to `true`. You can also enable view state for an individual control by setting the property to `true`. +> The control must have view state enabled for the event to work correctly. To enable view state for all controls on the Web Forms page, set the property to `true`. You can also enable view state for an individual control by setting the property to `true`. Raising an event invokes the event handler through a delegate. For more information, see [NIB: Raising an Event](http://msdn.microsoft.com/en-us/f2adaf01-1ed1-42e1-8c31-8d467e7e0ee2). @@ -391,7 +391,7 @@ Caption Text
The event is raised when the property of the control changes value between posts to the server. This allows you to create a custom event handler that performs a specific set of instructions (such as data validation) when the event is raised. > [!NOTE] -> The control must have view state enabled for the event to work correctly. To enable view state for all controls on the Web Forms page, set the property to `true`. You can also enable view state for an individual control by setting the property to `true`. +> The control must have view state enabled for the event to work correctly. To enable view state for all controls on the Web Forms page, set the property to `true`. You can also enable view state for an individual control by setting the property to `true`. For more information about handling events, see [NIB: Consuming Events](http://msdn.microsoft.com/en-us/01e4f1bc-e55e-413f-98c7-6588493e5f67). diff --git a/xml/System.Web.UI.HtmlControls/HtmlInputReset.xml b/xml/System.Web.UI.HtmlControls/HtmlInputReset.xml index cb60a2523b4c1..19b4683b5c380 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlInputReset.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlInputReset.xml @@ -60,7 +60,7 @@ |Property|Value| |--------------|-----------| -||The "reset" literal string.| +||The "reset" literal string.| @@ -97,7 +97,7 @@ |Property|Value| |--------------|-----------| -||The value of the `type` parameter.| +||The value of the `type` parameter.| Setting the `type` parameter to a value not recognized as a valid HTML `` element results in a default HTML `` element as a single-line text input field. diff --git a/xml/System.Web.UI.HtmlControls/HtmlInputSubmit.xml b/xml/System.Web.UI.HtmlControls/HtmlInputSubmit.xml index 97611246881ad..dc530b993eb1c 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlInputSubmit.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlInputSubmit.xml @@ -65,7 +65,7 @@ |Property|Value| |--------------|-----------| -||The "submit" literal string.| +||The "submit" literal string.| @@ -102,7 +102,7 @@ |Property|Value| |--------------|-----------| -||The value of the `type` parameter.| +||The value of the `type` parameter.| diff --git a/xml/System.Web.UI.HtmlControls/HtmlSelect.xml b/xml/System.Web.UI.HtmlControls/HtmlSelect.xml index 75657cb045d03..7a7c789fab27c 100644 --- a/xml/System.Web.UI.HtmlControls/HtmlSelect.xml +++ b/xml/System.Web.UI.HtmlControls/HtmlSelect.xml @@ -34,7 +34,7 @@ control to create a selection box. Specify item listings in the control by placing HTML `